TTS API Demo: Canlı İstek ve Yanıt Örnekleri

Çalıştırmadan önce

Oynat'a basıp ses duymayı bekleyenler için adil bir uyarı: bu tts api demosu ses çıkarmaz. Hizmet, uncensored modeli üzerinden POST /v1/chat/completions ile metin döndürür. GET /v1/models ile mevcut olanları listelemek için ikinci bir uç nokta vardır. Ses, görüntü veya gömme döndüren bir şey yoktur.

Neden bir demo? Çünkü birçok ses projesi tam olarak bu parçaya ihtiyaç duyar: bir senaryo yazarı, bir metin temizleyici, kimin ne söyleyeceğine karar veren bir bölen. Aşağıdaki örnekler bu işleri gösterir ve çıktı formatı ses kodunuzun ayrıştırdığı yapıdır.

Bir anahtara ihtiyacınız var. Google veya e-posta ve şifre ile API anahtarı sayfasında kaydolun ve tek tıkla $0.50 deneme kredisi talep edin. 7 gün geçerlidir ve kart gerektirmez. Komutların okuyabilmesi için anahtarı dışa aktarın:

Copyexport XTTS_API_KEY="paste-your-key-here"
curl -s https://api.xtts.cc/v1/models -H "Authorization: Bearer $XTTS_API_KEY" | grep uncensored

Bu çağrı uncensored içeren bir JSON listesi döndürürse, anahtar çalışır ve devam edebilirsiniz.

Demo 1: düz bir istek

En küçük kullanışlı çağrı kısa, konuşma tarzında bir paragraf ister:

Copycurl -s https://api.xtts.cc/v1/chat/completions \
  -H "Authorization: Bearer $XTTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "You write short lines for a voice actor. No stage directions."},
      {"role": "user", "content": "Welcome listeners to a show about lighthouses. Two sentences."}
    ],
    "temperature": 0.7,
    "max_tokens": 120
  }'

Yanıt aşağıdaki örneğe benzer. content içindeki metin her çalışmada farklı olacaktır; bu yüzden yapıyı göstermek için bir örnek olarak değerlendirin, kaydedilmiş bir çıktı olarak değil.

Copy{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "model": "uncensored",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Welcome to the show. Tonight we climb the stairs of the world's loneliest lighthouses."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 38, "completion_tokens": 21, "total_tokens": 59}
}

Kodunuz choices[0].message.content değerini okur. finish_reason oluşturmanın neden sonlandığını belirtir: doğal bir son için stop, max_tokens keserse length. max_tokens değerini belirtmezseniz, tamamlama 100.000 tokenlik pencerenin kalanını kullanabilir; bu pencere hem istemi hem de tamamlamayı kapsar.

Başlıkların anlattıkları

curl komutuna -i ekleyin; X-Request-Id, X-Balance-USD, X-RateLimit-Limit-Requests ve X-RateLimit-Limit-Concurrency göreceksiniz. Bakiye başlığı bir demoda kullanışlıdır çünkü her çağrının ardından düşüşünü izleyebilirsiniz. Bu istek için kullanım 38 x $0,15 / 1.000.000 artı 21 x $0,50 / 1.000.000 eder; bu da $0,0000057 artı $0,0000105, yaklaşık $0,0000162 eder.

Demo 2: senaryoyu akış olarak gönder

Ses için genellikle tüm metnin tamamlanmasını beklemek istemezsiniz. "stream": true ekleyin ve API, metni küçük parçalar halinde sunucu tarafından gönderilen olaylar (SSE) olarak iletir. Aşağıdaki Node örneği, metin geldiğinde yazdırır; bu noktada bir cümle kuyruğunu besleyebilirsiniz.

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.xtts.cc/v1",
  apiKey: process.env.XTTS_API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [
    { role: "user", content: "Read a four-line weather report for a coastal town." },
  ],
});

for await (const chunk of stream) {
  const piece = chunk.choices[0]?.delta?.content ?? "";
  process.stdout.write(piece);
}
process.stdout.write("\n");

Bunu bir ES modülü olarak çalıştırın (demo.mjs olarak kaydedin ve npm install openai sonrasında node demo.mjs çalıştırın). Hat üzerinde her olay, JSON ile devam eden data: ile başlayan bir satır olarak gelir ve akış son bir işaret ile kapanır. Token kullanımı akışın sonunda raporlanır. Planlama için tek önemli nokta: akışlı bir istek, akış bitene kadar eşzamanlılık slotunu tutar; bu nedenle yavaş bir tüketici kendi sonraki isteğinizi engelleyebilir.

Demo 3: ses rotası olarak fonksiyon çağırma

Tool calling, modelin metin yerine yapılandırılmış bir talimat döndürmesini sağlar. Bir ses projesinde bu, satır başına bir teslimat tarzı seçmek için temiz bir yoldur. say adında bir fonksiyon tanımlarsınız ve model argümanlarını doldurur. Kodunuz sonra bunlarla ne yapılacağına karar verir. Model kendi başına hiçbir şey çalıştırmaz.

Copyimport json
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.xtts.cc/v1", api_key=os.environ["XTTS_API_KEY"])

tools = [{
    "type": "function",
    "function": {
        "name": "say",
        "description": "Queue one line for the voice engine.",
        "parameters": {
            "type": "object",
            "properties": {
                "text": {"type": "string"},
                "style": {"type": "string", "enum": ["calm", "urgent", "whisper"]},
            },
            "required": ["text", "style"],
        },
    },
}]

messages = [
    {"role": "system", "content": "Always answer by calling say, once per line."},
    {"role": "user", "content": "The alarm sounds. The guard tells everyone to leave."},
]

r = client.chat.completions.create(
    model="uncensored", messages=messages, tools=tools, tool_choice="auto"
)

msg = r.choices[0].message
for call in msg.tool_calls or []:
    args = json.loads(call.function.arguments)
    print(args["style"], "->", args["text"])

Argümanlar bir JSON dizgesi olarak gelir; bu yüzden kullanmadan önce ayrıştırın ve doğrulayın. Modeller, enum'unuz dışında bir stil üretebilir veya bir alanı atlayabilir; kontrol edilmemiş bir değer asla motorunuza ulaşmamalıdır. Sohbetin devam etmesini istiyorsanız, asistan mesajını ve role: "tool" ile eşleşen tool_call_id içeren bir yanıtı ekleyin, sonra API'yi tekrar çağırın.

Akış sırasında fonksiyon çağrıları parçalar halinde gelir. Fonksiyon adı önce gelir ve argüman dizgesi parçalar arasında birikir; bu yüzden parçaları indeksle toplayın ve akış bittiğinde bir kez ayrıştırın.

Demo 4: oyuncu kadrosu için JSON modu

Fonksiyon tanımlarını atlamak isterseniz, JSON modu mesaj içeriğinde geçerli JSON sağlar. Bu, kabaca bir sahneyi konuşmacı başına satırlara dönüştürmek için uygundur.

Copycurl -s https://api.xtts.cc/v1/chat/completions \
  -H "Authorization: Bearer $XTTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "response_format": {"type": "json_object"},
    "temperature": 0.2,
    "messages": [
      {"role": "system", "content": "Return JSON: {\"lines\": [{\"speaker\": string, \"text\": string}]}"},
      {"role": "user", "content": "Ana asks Ben to hold the ladder. Ben agrees reluctantly."}
    ]
  }'

JSON modu çıktının ayrıştırılacağını garanti eder, ancak şeklinizin eşleşeceğini değil. Şekli yukarıdaki gibi istemde tanımlayın ve kodda anahtarları kontrol edin. Düşük sıcaklık yapıyı sabit tutar.

Demo 5: tek istekte uzun bir belge

Bağlam penceresi 100.000 tokenlik bir kapasiteye sahiptir; istem ve tamamlama bunu paylaşır. Bu, uzun bir transkript veya kısa bir öykü gönderip onu kulağa yazılmış bir sürüm olarak istemek için yeterlidir. İstek gövdesi 8 MB'a kadar olabilir; bu yüzden boyut nadiren sınırdır; token sayısı sınırdır.

Ağır bir çağrının maliyeti burada. Diyelim ki 80.000 token gönderip 2.000 token alıyorsunuz. Giriş: 80.000 x $0.15 / 1.000.000 = $0.012. Çıktı: 2.000 x $0.50 / 1.000.000 = $0.001. Toplam $0.013'tür, bu nedenle $0.50'lık deneme kredisi yaklaşık 38 çağrıyı karşılayabilir. Uzun giriş, uzun çıktıya göre ucuzdur; bu nedenle büyük metinlerin özetleri ve yeniden yazımları uygun maliyetlidirken tek seferde bir romanın tamamını oluşturmak uygun değildir.

Uzun girişler için pratik bir ipucu: talimatlarınızı en başa yazın ve temel kuralı sona tekrarlayın. Modeller genellikle en son talimatı en iyi şekilde takip eder ve 80.000 token kaynak metinden sonra bir satırlık hatırlatma neredeyse hiçbir maliyet gerektirmez.

Demoda hata okuma

Bilerek bir kez bozarak daha sonra tanıyın. Yanlış bir anahtarla istek gönderin ve tamamlama yerine kimlik doğrulama hatası alırsınız. Deneme anahtarından aynı anda on istek gönderin ve bazıları HTTP 429 olarak döner.

429'nın üç nedeni vardır ve hata kodu bunları ayırt eder:

• rate_limited bir dakikada çok fazla istek anlamına gelir: deneme anahtarında 60, tam anahtarında 300.
• concurrency, aynı anda uçta olan çok fazla istek anlamına gelir: deneme anahtarında 2, tam anahtarında 8.
• Retry-After: 5 başlığı olan bir 429, hizmetin kısa süreli aşırı yüklendiğini gösterir. Beş saniye bekleyin ve tekrar gönderin.

Başarısız veya reddedilen istekler ücretlendirilmez; bu yüzden hatalar bedavadır. Anahtarınızın limitlerini görmek için herhangi bir normal yanıtta X-RateLimit-Limit-Requests ve X-RateLimit-Limit-Concurrency okuyun. Retry-After değerini veya eksikse beş saniyeyi uyuyarak çalışan küçük bir tekrar döngüsü bir demo betiği için yeterlidir.

Sırada ne deneyebilirsiniz

Bu dört çağrı çalıştığında, bir betik hattının parçalarına sahip olursunuz. Düz istek bir fonksiyonun içine alın, akış döngüsünü bir kuyruğa bağlayın ve kuyruğu seçtiğiniz ses motoruna bağlayın. Motorlar fiyat, lisans ve kalite açısından farklılık gösterir, bu nedenle mevcut şartlarını okuyun. Bu hizmet bir tane sağlamaz ve bunlar hakkında bir şey söylemez.

Deneme yaparken maliyetler küçük kalır. Milyon giriş token başına $0.15 ve milyon çıktı token başına $0.50 ile tipik bir demo çağrısı bir kuruşun çok küçük bir kısmına mal olur ve $0.50'lık deneme kredisi yüzlerce tanesini karşılar. 20 $ ile 500 $ arasında bakiye yüklemek için fiyatlandırma sayfasına bakın; %5 ile %15 arasında bonuslar sunulur; kripto ile ödeme yapılır. dokümantasyon tam parametre listesini, hız limitlerini (tam anahtar için eşzamanlı 8 ve dakika başına 300) ve hata kodlarını kapsar. İstemler eğitim için kullanılmaz.

İlk bir öğleden sonra için mantıklı bir sıra: ton doğru olana kadar düz isteği çalıştırın, akışa geçin ve cümleler tamamlandığında yazdırın, ardından ses kodunuzun girdiyi nasıl istediğine uyan tool calls veya JSON modundan birini ekleyin. Her istemi sürüm kontrolü altında bir dosyada tutun. Son ses yanlış duyulduğunda, bunu üreten tam talimata iz sürüp tek bir şeyi değiştirebilirsiniz.

Daha fazla kılavuz

• TTS API Python: Konuşma Motoru İçin Metni Hazırlayın
• TTS API Ücretsiz: $0.50 Deneme Ne Kapsar (Yalnızca Metin)
• Ses Klonlama API: OpenAI Uyumlu TTS