Demo API TTS: Esempi live di richiesta e risposta

Prima di eseguire qualsiasi cosa

Un avviso onesto per chi si aspetta di premere play e sentire una voce: questa demo dell'API TTS non produce suono. Il servizio restituisce testo da un modello, uncensored, tramite POST /v1/chat/completions. C'è un secondo endpoint, GET /v1/models, per elencare le risorse disponibili. Nulla restituisce audio, immagini o embedding.

Perché una demo? Perché molti progetti vocali hanno bisogno esattamente di questa parte: uno scrittore di copioni, un pulitore di testo, uno splitter che decide chi dice cosa. Gli esempi qui sotto mostrano questi lavori e il formato di output è ciò che il tuo codice vocale analizzerà.

Hai bisogno di una chiave. Iscriviti alla pagina della chiave API con Google o con email e password, poi richiedi il credito di prova da $0,50 con un clic. È valido per 7 giorni e non richiede carta. Esporta la chiave in modo che i comandi seguenti possano leggerla:

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

Se quella chiamata restituisce un elenco JSON che include uncensored, la chiave funziona e puoi continuare.

Demo 1: una richiesta semplice

La chiamata utile più piccola richiede un breve paragrafo in stile parlato:

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

La risposta appare come l'esempio sotto. Il testo all'interno di content varierà ad ogni esecuzione, quindi trattalo come un'illustrazione della struttura e non come output registrato.

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

Il tuo codice vocale legge choices[0].message.content. Il campo finish_reason indica perché la generazione è terminata: stop per una conclusione naturale, length se la generazione è stata interrotta da max_tokens. Se ometti max_tokens, il completamento potrebbe utilizzare tutto ciò che rimane della finestra di contesto da 100.000 token, che copre prompt e completamento insieme.

Cosa ti dicono le intestazioni

Aggiungi -i al comando curl e vedrai X-Request-Id, X-Balance-USD, X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency. L'intestazione del saldo è utile in una demo perché puoi vederla diminuire di una piccola quantità dopo ogni chiamata. Per questa richiesta l'utilizzo sopra ammonta a 38 x $0,15 / 1.000.000 più 21 x $0,50 / 1.000.000, che è $0,0000057 più $0,0000105, circa $0,0000162.

Demo 2: streaming del copione

Per l'audio raramente vuoi aspettare il testo completo. Aggiungi "stream": true e l'API invia eventi server-sent, un piccolo pezzo di testo alla volta. L'esempio Node sotto stampa il testo man mano che arriva, dove dovresti alimentare una coda di frasi.

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

Esegui come modulo ES (salva come demo.mjs ed esegui node demo.mjs dopo npm install openai). Sul filo ogni evento è una riga che inizia con data: seguita da JSON, e lo stream si chiude con un marcatore finale. L'utilizzo dei token viene riportato alla fine dello stream. Un punto importante per la pianificazione: una richiesta in streaming mantiene la sua slot di concorrenza fino alla fine dello stream, quindi un consumatore lento può bloccare la tua prossima richiesta.

Demo 3: chiamata di funzioni come router vocale

La chiamata di funzioni permette al modello di restituire un'istruzione strutturata invece che prosa. In un progetto vocale è un modo pulito per scegliere uno stile di consegna per riga. Definisci una funzione chiamata say, e il modello compila i suoi argomenti. Il tuo codice decide poi cosa farne. Il modello non esegue nulla di per sé.

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

Gli argomenti arrivano come stringa JSON, quindi analizzali e validali prima dell'uso. I modelli possono produrre uno stile al di fuori della tua enum o omettere un campo, e un valore non controllato non dovrebbe mai raggiungere il tuo motore. Se vuoi che la conversazione continui, aggiungi il messaggio dell'assistente e una risposta con role: "tool" e il corrispondente tool_call_id, poi richiama l'API.

Durante lo streaming, le chiamate di funzioni arrivano a pezzi. Il nome della funzione viene per primo e la stringa degli argomenti si accumula nei chunk, quindi raccogli i frammenti per indice e analizza una volta terminato lo stream.

Demo 4: modalità JSON per un cast

Se preferisci saltare le definizioni degli strumenti, la modalità JSON fornisce JSON valido nel contenuto del messaggio. È un buon adattamento per trasformare una scena approssimativa in righe per parlante.

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

La modalità JSON garantisce che l'output venga analizzato, non che corrisponda alla tua forma. Descrivi la forma nel prompt, come sopra, e controlla le chiavi nel codice. Una temperatura bassa mantiene la struttura stabile.

Demo 5: un documento lungo in una richiesta

La finestra di contesto è di 100.000 token, condivisa da prompt e completamento. È sufficiente per inviare una trascrizione lunga o un'intera storia breve e chiedere una versione scritta per l'orecchio. Il corpo della richiesta può essere fino a 8 MB, quindi la dimensione raramente è il limite; lo è il conteggio dei token.

Ecco il costo di una richiesta pesante. Supponiamo di inviare 80.000 token e riceverne 2.000. Input: 80.000 x $0,15 / 1.000.000 = $0,012. Output: 2.000 x $0,50 / 1.000.000 = $0,001. Il totale è $0,013, quindi il credito di prova da $0,50 coprirebbe circa 38 richieste simili. Un input lungo è economico rispetto a un output lungo, motivo per cui riassunti e riscritture di testi grandi sono accessibili, mentre generare un romanzo intero in una volta no.

Un consiglio pratico per gli input lunghi: metti le tue istruzioni all'inizio e ripeti la regola chiave alla fine. I modelli tendono a seguire meglio l'istruzione più recente e un promemoria di una riga dopo 80.000 token di testo sorgente costa quasi nulla.

Lettura degli errori nella demo

Rompi qualcosa apposta una volta così da riconoscerlo in seguito. Invia la richiesta con una chiave sbagliata e otterrai un errore di autenticazione invece che un completamento. Invia dieci richieste nello stesso istante da una chiave di prova e alcune torneranno come HTTP 429.

Il 429 ha tre cause e il codice errore le distingue:

• rate_limited significa troppe richieste in un minuto: 60 su una chiave di prova, 300 su una chiave completa.
• concurrency significa troppe richieste in volo contemporaneamente: 2 su una chiave di prova, 8 su una chiave completa.
• Un 429 con un'intestazione Retry-After: 5 significa che il servizio era brevemente sovraccarico. Attendi cinque secondi e invialo di nuovo.

Le richieste fallite o rifiutate non vengono addebitate, quindi gli errori non costano nulla. Per vedere i limiti della tua chiave, leggi X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency in qualsiasi risposta normale. Un piccolo ciclo di ritentativi che attende il valore di Retry-After, o cinque secondi se è assente, è tutto ciò di cui ha bisogno uno script demo.

Cosa provare dopo

Una volta che queste quattro chiamate funzionano, hai i pezzi di una pipeline di script. Avvolgi la richiesta semplice in una funzione, esegui il ciclo di streaming in una coda e collega la coda al motore vocale che preferisci. I motori differiscono per prezzo, licenza e qualità, quindi leggi i loro termini attuali. Questo servizio non ne fornisce uno e non dichiara nulla su di essi.

I costi rimangono piccoli mentre sperimenti. A $0,15 per milione di token di input e $0,50 per milione di token di output, una chiamata demo tipica costa una frazione di centesimo e il credito di prova da $0,50 ne copre centinaia. Consulta la pagina dei prezzi per ricariche da $20 a $500 con bonus dal 5% al 15%, pagabili con cripto. La documentazione copre l'elenco completo dei parametri, i limiti di velocità (8 paralleli e 300 al minuto su una chiave completa) e i codici di errore. I prompt non vengono utilizzati per l'addestramento.

Un ordine ragionevole per un primo pomeriggio: esegui la richiesta semplice finché il tono non è corretto, passa allo streaming e stampa le frasi man mano che si completano, poi aggiungi o chiamate di funzioni o modalità JSON, a seconda di come il tuo codice vocale vuole il suo input. Tieni ogni prompt in un file sotto controllo versione. Quando una riga suona male nell'audio finale, puoi poi risalire all'istruzione esatta che l'ha prodotta e cambiare una cosa alla volta.

Altre guide

• API TTS Python: Prepara il testo per la sintesi vocale con l'SDK
• API TTS Gratis: Cosa Copre il Credito di Prova da $0,50 (Solo Testo)
• API Voice Cloning: TTS compatibile con OpenAI