TTS API-demo: Live voorbeelden van verzoeken en antwoorden

Voordat je iets uitvoert

Een eerlijke waarschuwing voor iedereen die verwacht op afspelen te drukken en een stem te horen: deze tts api demo levert geen geluid. De service retourneert tekst van één model, uncensored, via POST /v1/chat/completions. Er is een tweede endpoint, GET /v1/models, voor het opsommen van wat beschikbaar is. Er wordt geen audio, afbeeldingen of embeddings geretourneerd.

Waarom dan een demo? Omdat veel speech-projecten precies dit onderdeel nodig hebben: een scriptauteur, een tekstopruimer, een splitter die beslist wie wat zegt. De onderstaande voorbeelden tonen die taken, en het outputformaat is wat je speech code zal parseren.

Je hebt een sleutel nodig. Meld je aan op de API key pagina met Google of met e-mail en wachtwoord, en claim het $0,50 trial tegoed met één klik. Het is 7 dagen geldig en vereist geen creditcard. Exporteer de sleutel zodat de onderstaande commando's deze kunnen lezen:

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

Als die verzoek een JSON-lijst teruggeeft die uncensored bevat, werkt de sleutel en kun je verder gaan.

Demo 1: een gewoon verzoek

Het kleinste nuttige verzoek vraagt om een korte tekst in spreekstijl:

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
  }'

Het antwoord lijkt op het voorbeeld hieronder. De tekst binnen content verschilt bij elke uitvoering, dus beschouw het als een illustratie van de structuur en niet als een vaste uitvoer.

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}
}

Je code voor tekst-naar-spraak leest choices[0].message.content. De finish_reason vertelt waarom de generatie eindigde: stop voor een natuurlijk einde, length als max_tokens het afkapt. Als je max_tokens weglaat, kan de voltooiing het resterende deel van het contextvenster van 100.000 tokens gebruiken, wat zowel de prompt als de voltooiing omvat.

Wat de headers je vertellen

Voeg -i toe aan het curl-commando en je ziet X-Request-Id, X-Balance-USD, X-RateLimit-Limit-Requests en X-RateLimit-Limit-Concurrency. De balansheader is nuttig in een demo, omdat je kunt zien hoe deze na elk verzoek met een klein bedrag daalt. Voor dit verzoek komt het gebruik hierboven overeen met 38 x $0,15 / 1.000.000 plus 21 x $0,50 / 1.000.000, wat $0,0000057 plus $0,0000105 is, ongeveer $0,0000162.

Demo 2: het script streamen

Voor audio wil je zelden wachten op de volledige tekst. Voeg "stream": true toe en de API stuurt server-sent events, één klein tekstfragment tegelijk. Het Node-voorbeeld hieronder drukt tekst af zodra deze aankomt, waar je een zinnenwachtrij zou voeden.

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");

Voer het uit als een ES-module (sla op als demo.mjs en voer node demo.mjs uit na npm install openai). Op de draad is elk evenement een regel die begint met data: gevolgd door JSON, en de stream sluit met een eindmarker. Tokengebruik wordt aan het einde van de stream gerapporteerd. Een punt dat belangrijk is voor de planning: een gestreamd verzoek houdt zijn concurrency slot vast tot de stream eindigt, dus een trage consument kan je volgende verzoek blokkeren.

Demo 3: function calling als stemrouter

Function calling stelt het model in staat een gestructureerde instructie terug te geven in plaats van tekst. In een voice project is dit een schone manier om een presentatiestijl per regel te kiezen. Je definieert een functie genaamd say, en het model vult de argumenten in. Je code beslist vervolgens wat ermee te doen. Het model voert niets zelf uit.

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"])

Argumenten komen aan als een JSON-string, dus parseer en valideer ze voordat je ze gebruikt. Modellen kunnen een stijl buiten je enum produceren of een veld weglaten, en een niet-gecontroleerde waarde mag je engine nooit bereiken. Als je het gesprek wilt laten doorgaan, voeg dan het assistant-bericht toe en een antwoord met role: "tool" en de bijbehorende tool_call_id, en roep de API opnieuw aan.

Bij streaming komen tool calls in stukken aan. De functienaam komt eerst en de argumentstring bouwt zich op over chunks, dus verzamel fragmenten op index en parse zodra de stream klaar is.

Demo 4: JSON-modus voor een castlijst

Als je de tool-definities wilt overslaan, geeft JSON-modus geldige JSON in de berichtinhoud. Dit is een goede oplossing om een ruwe scène om te zetten in regels per spreker.

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-modus garandeert dat de uitvoer geparsed kan worden, niet dat deze overeenkomt met jouw structuur. Beschrijf de structuur in de prompt, zoals hierboven, en controleer de sleutels in de code. Een lage temperatuur houdt de structuur stabiel.

Demo 5: een lang document in één verzoek

Het contextvenster is 100.000 tokens, gedeeld door prompt en uitvoer. Dat is genoeg om een lange transcriptie of een compleet kort verhaal te sturen en om een versie voor het oor te vragen. De request body kan maximaal 8 MB zijn, dus de grootte is zelden de limiet; het tokenaantal is dat wel.

Hier is de kosten van een zwaar verzoek. Stel je stuurt 80.000 tokens en krijgt er 2.000 terug. Input: 80.000 x $0,15 / 1.000.000 = $0,012. Output: 2.000 x $0,50 / 1.000.000 = $0,001. Het totaal is $0,013, dus het $0,50 trial tegoed zou ongeveer 38 verzoeken zoals dit kunnen dekken. Lange input is goedkoop in vergelijking met lange output, daarom zijn samenvattingen en herschrijvingen van grote teksten betaalbaar, terwijl het genereren van een heel boek in één keer niet betaalbaar is.

Een praktische tip voor lange inputs: plaats je instructies eerst en herhaal de belangrijkste regel aan het einde. Modellen volgen de meest recente instructie het beste, en een eenregelige herinnering na 80.000 tokens aan brontekst kost bijna niets.

Fouten in de demo lezen

Breek iets opzettelijk één keer, zodat je het later herkent. Stuur het verzoek met een verkeerde sleutel en je krijgt een authenticatiefout in plaats van een voltooiing. Stuur tien verzoeken tegelijk vanaf een trial key en sommige komen terug als HTTP 429.

De 429 heeft drie oorzaken, en de error code maakt ze uit elkaar:

• rate_limited betekent te veel verzoeken in één minuut: 60 op een trial key, 300 op een volledige sleutel.
• concurrency betekent te veel verzoeken in flight tegelijk: 2 op een trial key, 8 op een full key.
• Een 429 met een Retry-After: 5 header betekent dat de service kortstondig overbelast was. Wacht vijf seconden en stuur het opnieuw.

Mislukte of geweigerde verzoeken worden niet in rekening gebracht, dus fouten kosten niets. Om de limieten van je key te zien, lees X-RateLimit-Limit-Requests en X-RateLimit-Limit-Concurrency op elke normale response. Een kleine retry loop die slaapt voor de Retry-After waarde, of vijf seconden als die ontbreekt, is alles wat een demo script nodig heeft.

Wat je daarna kunt proberen

Zodra deze vier calls werken, heb je de onderdelen van een script pipeline. Wrap het gewone verzoek in een functie, voer de streaming loop uit naar een queue, en koppel de queue aan de speech engine van je keuze. Engines verschillen in prijs, licentie en kwaliteit, dus lees hun huidige voorwaarden. Deze service levert er geen en maakt geen uitspraken hierover.

Kosten blijven klein terwijl je experimenteert. Bij $0,15 per miljoen input tokens en $0,50 per miljoen output tokens kost een typische demo call een fractie van een cent, en het $0,50 trial dekt er honderden. Zie de pricing pagina voor top-ups van $20 tot $500 met bonussen van 5% tot 15%, betaalbaar met crypto. De docs dekken de volledige parameterlijst, rate limits (8 concurrent en 300 per minuut op een full key) en error codes. Prompts worden niet gebruikt voor training.

Een redelijke volgorde voor een eerste middag: voer het gewone verzoek uit totdat de toon goed is, schakel over op streaming en print zinnen zodra ze klaar zijn, voeg dan of tool calls of JSON-modus toe, afhankelijk van hoe je speech code zijn input wil ontvangen. Houd elke prompt in een bestand onder versiebeheer. Als een regel verkeerd klinkt in de finale audio, kun je deze dan terugtracen naar de exacte instructie die hem produceerde en één ding tegelijk veranderen.

Meer handleidingen

• TTS API Python: Bereid tekst voor voor speech met de SDK
• TTS API Gratis: Wat het $0,50 Trial Dekt (Alleen Tekst)
• Voice Cloning API: OpenAI-compatibele TTS