TTS-API-Demo: Live-Anfragen- und Antwortbeispiele

Bevor du irgendetwas ausführst

Eine faire Warnung für alle, die erwarten, auf Play zu drücken und eine Stimme zu hören: Dieses TTS-API-Demo erzeugt keinen Ton. Der Dienst gibt Text vom Modell uncensored über POST /v1/chat/completions zurück. Es gibt einen zweiten Endpunkt, GET /v1/models, um aufzulisten, was verfügbar ist. Es werden keine Audio-, Bild- oder Embedding-Daten zurückgegeben.

Warum ein Demo? Weil viele Sprach-Projekte genau diesen Teil benötigen: einen Skriptautor, einen Textbereiniger, einen Splitter, der entscheidet, wer was sagt. Die folgenden Beispiele zeigen diese Aufgaben, und das Ausgabeformat ist das, was dein Sprach-Code parsen wird.

Du brauchst einen Schlüssel. Registriere dich auf der API-Schlüssel-Seite mit Google oder E-Mail und Passwort, und beanspruche das $0,50 Trial-Guthaben mit einem Klick. Es ist 7 Tage gültig und benötigt keine Karte. Exportiere den Schlüssel, damit die folgenden Befehle ihn lesen können:

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

Wenn dieser Aufruf eine JSON-Liste zurückgibt, die uncensored enthält, funktioniert der Schlüssel und du kannst fortfahren.

Demo 1: Eine einfache Anfrage

Der kleinste nützliche Aufruf fragt einen kurzen, gesprochenen Absatz ab:

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

Die Antwort sieht wie das unten gezeigte Beispiel aus. Der Text in content wird bei jeder Ausführung anders sein, also betrachte ihn als Illustration der Struktur und nicht als aufgezeichnete Ausgabe.

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

Dein Sprach-Code liest choices[0].message.content. Der finish_reason sagt dir, warum die Generierung endete: stop für ein natürliches Ende, length wenn max_tokens es vorzeitig abschneidet. Wenn du max_tokens weglässt, kann die Vervollständigung den Rest des 100.000-Token-Fensters nutzen, was Prompt und Vervollständigung zusammen abdeckt.

Was die Header dir sagen

Füge dem curl-Befehl -i hinzu, und du siehst X-Request-Id, X-Balance-USD, X-RateLimit-Limit-Requests und X-RateLimit-Limit-Concurrency. Der Balance-Header ist in einem Demo nützlich, weil du sehen kannst, wie er nach jedem Aufruf um einen winzigen Betrag sinkt. Für diese Anfrage beläuft sich die Nutzung oben auf 38 x $0,15 / 1.000.000 plus 21 x $0,50 / 1.000.000, was $0,0000057 plus $0,0000105 entspricht, etwa $0,0000162.

Demo 2: Das Skript streamen

Für Audio willst du selten auf den vollständigen Text warten. Füge "stream": true hinzu, und die API sendet Server-Sent Events, ein kleines Textstück nach dem anderen. Das Node-Beispiel unten gibt Text aus, sobald er eingeht, genau dort, wo du eine Satz-Warteschlange speisen würdest.

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

Führe es als ES-Modul aus (speichere es als demo.mjs und führe node demo.mjs nach npm install openai aus). Über die Leitung ist jedes Event eine Zeile, die mit data: beginnt, gefolgt von JSON, und der Stream schließt mit einem abschließenden Marker. Die Token-Nutzung wird am Ende des Streams gemeldet. Ein Punkt ist wichtig für die Planung: Eine gestreamte Anfrage behält ihren Concurrency-Slot bis zum Ende des Streams, sodass ein langsamer Verbraucher deine nächste Anfrage blockieren kann.

Demo 3: Tool Calling als Sprach-Router

Tool Calling ermöglicht es dem Modell, eine strukturierte Anweisung zurückzugeben, anstatt Fließtext. In einem Sprachprojekt ist dies eine saubere Möglichkeit, einen Vortragsstil pro Zeile auszuwählen. Du definierst eine Funktion namens say, und das Modell füllt ihre Argumente aus. Dein Code entscheidet dann, was er damit macht. Das Modell führt nichts selbst aus.

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

Argumente kommen als JSON-String an, also parst und validiere sie vor der Verwendung. Modelle können einen Stil außerhalb deines Enums produzieren oder ein Feld weglassen, und ein nicht geprüfter Wert sollte niemals deine Engine erreichen. Wenn du möchtest, dass das Gespräch fortgesetzt wird, hänge die Assistant-Nachricht und eine Antwort mit role: "tool" und der passenden tool_call_id an und rufe die API erneut auf.

Beim Streaming kommen Tool-Calls in Stücken an. Der Funktionsname kommt zuerst, und der Argument-String baut sich über Chunks auf, also sammle Fragmente nach Index und parse, sobald der Stream endet.

Demo 4: JSON-Modus für eine Cast-Liste

Wenn du Tool-Definitionen überspringen möchtest, gibt der JSON-Modus gültiges JSON im Nachrichteninhalt zurück. Dies eignet sich gut, um eine grobe Szene in Zeilen pro Sprecher umzuwandeln.

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."}
    ]
  }'

Der JSON-Modus garantiert, dass die Ausgabe geparst werden kann, nicht aber, dass sie deiner Struktur entspricht. Beschreibe die Struktur im Prompt, wie oben, und prüfe Schlüssel im Code. Eine niedrige Temperatur hält die Struktur stabil.

Demo 5: Ein langes Dokument in einer Anfrage

Das Kontextfenster hat 100.000 Token, die sich aus Prompt und Vervollständigung teilen. Das reicht aus, um ein langes Transkript oder eine ganze kurze Geschichte zu senden und nach einer Version zu fragen, die für das Ohr geschrieben ist. Der Anfragekörper kann bis zu 8 MB groß sein, daher ist die Größe selten das Limit; die Token-Anzahl ist es.

Hier sind die Kosten für einen schweren Aufruf. Angenommen, du sendest 80.000 Token und erhältst 2.000 zurück. Input: 80.000 x $0,15 / 1.000.000 = $0,012. Output: 2.000 x $0,50 / 1.000.000 = $0,001. Die Summe beträgt $0,013, also würde das $0,50 Trial-Guthaben etwa 38 solcher Aufrufe abdecken. Langer Input ist im Vergleich zu langem Output günstig, weshalb Zusammenfassungen und Umformulierungen großer Texte erschwinglich sind, während das Generieren eines ganzen Romans auf einmal nicht erschwinglich ist.

Ein praktischer Tipp für lange Inputs: Platziere deine Anweisungen zuerst und wiederhole die Hauptregel am Ende. Modelle neigen dazu, der neuesten Anweisung am besten zu folgen, und eine Ein-Zeilen-Erinnerung nach 80.000 Token Quelltext kostet fast nichts.

Fehler in der Demo lesen

Brich absichtlich einmal etwas, damit du es später erkennst. Sende die Anfrage mit einem falschen Schlüssel, und du erhältst einen Authentifizierungsfehler statt einer Vervollständigung. Sende zehn Anfragen gleichzeitig von einem Trial-Key, und einige kommen als HTTP 429 zurück.

Die 429 hat drei Ursachen, und der Fehlercode unterscheidet sie:

• rate_limited bedeutet zu viele Anfragen in einer Minute: 60 auf einem Trial-Key, 300 auf einem Full-Key.
• concurrency bedeutet zu viele Anfragen gleichzeitig im Flug: 2 auf einem Trial-Key, 8 auf einem Full-Key.
• Eine 429 mit einem Retry-After: 5-Header bedeutet, dass der Dienst kurzzeitig überlastet war. Warte fünf Sekunden und sende ihn erneut.

Fehlgeschlagene oder abgelehnte Anfragen werden nicht berechnet, also kosten Fehler nichts. Um die Limits zu sehen, die dein Schlüssel hat, lies X-RateLimit-Limit-Requests und X-RateLimit-Limit-Concurrency bei jeder normalen Antwort. Eine kleine Retry-Schleife, die für den Retry-After-Wert oder fünf Sekunden, wenn er fehlt, schläft, ist alles, was ein Demo-Skript benötigt.

Was du als Nächstes versuchen kannst

Sobald diese vier Aufrufe funktionieren, hast du die Bausteine einer Skript-Pipeline. Verpacke die einfache Anfrage in eine Funktion, führe die Streaming-Schleife in eine Warteschlange, und verbinde die Warteschlange mit der Speech-Engine deiner Wahl. Engines unterscheiden sich in Preis, Lizenz und Qualität, also lies ihre aktuellen Bedingungen. Dieser Dienst stellt keine bereit und trifft keine Aussagen darüber.

Die Kosten bleiben gering, während du experimentierst. Bei $0,15 pro Million Input-Token und $0,50 pro Million Output-Token kostet eine typische Demo-Anfrage einen Bruchteil eines Cents, und das $0,50 Trial-Guthaben deckt Hunderte davon ab. Sieh dir die Preisseite für Aufladungen von $20 bis $500 mit Boni von 5 % bis 15 % an, zahlbar mit Krypto. Die Dokumentation deckt die vollständige Parameterliste, Ratenlimits (8 parallel und 300 pro Minute auf einem Full-Key) und Fehlercodes ab. Prompts werden nicht zum Training verwendet.

Eine vernünftige Reihenfolge für einen ersten Nachmittag: Führe die einfache Anfrage aus, bis der Ton stimmt, wechsle zum Streaming und gib Sätze aus, sobald sie abgeschlossen sind, und füge entweder Tool-Calls oder den JSON-Modus hinzu, je nachdem, wie dein Speech-Code seine Eingabe haben möchte. Halte jeden Prompt in einer Datei unter Versionskontrolle. Wenn eine Zeile in der endgültigen Audio-Ausgabe falsch klingt, kannst du sie auf die genaue Anweisung zurückverfolgen, die sie erzeugt hat, und eine Sache nach der anderen ändern.

Weitere Anleitungen

• TTS-API Python: Text für Speech mit dem SDK vorbereiten
• TTS-API Kostenlos: Was das $0,50 Trial-Guthaben abdeckt (Nur Text)
• Voice-Cloning-API: OpenAI-kompatible TTS