Voce e catalogo

GET /v1/chat/catalog elenca modelli pubblici, voci e prezzi correnti del credito. La chat di testo utilizza POST /v1/chat/completions; il discorso utilizza gli endpoint seguenti.

Modelli e prezzi

Catalogo dei modelli in tempo reale · prezzi di credito

Caricamento catalogo modelli...

Discorso al testo

POST /v1/chat/transcribe accetta { "audio": "data:audio/webm;base64,..." }. È supportato anche il supporto semplice 64, fino a 10MB decodificato. Restituisce text e language.

Sintesi vocale dal testo

Catalogo dei modelli in tempo reale · prezzi di credito

Caricamento catalogo modelli...

Espandi un modello per visualizzarne le voci abilitate. Gli amministratori possono modificare i nomi e le descrizioni delle voci. Le voci disabilitate vengono omesse dal catalogo e non possono essere utilizzate per nuove richieste di sintesi; aggiorna questa pagina per vedere le impostazioni correnti. La disabilitazione di un modello rimuove anche tutte le sue voci dalla documentazione e dagli elenchi delle voci del catalogo e rifiuta nuove richieste di sintesi. La riattivazione di un modello preserva le impostazioni vocali individuali. Se la voce predefinita o il suo modello è disabilitato, viene selezionata invece una voce abilitata di un altro modello abilitato.

POST /v1/chat/speech accetta { "text": "Hello", "voice": "speech-light:af_bella" } (fino a 2,000 caratteri). Omettere voice per l'impostazione predefinita configurata. Utilizzare voices[].id dal catalogo; modelId identifica il modello e la frequenza del parlato. Famiglie: Speech Standard, Speech Light, Speech Pro e Speech Expressive. I modelli di parlato e chat sono indipendenti.

La risposta include audio (URI dati MP3, data:audio/mpeg;base64,...), voice e billing: { model, credits, characters, price, unit: "1000_characters" }. Tutte le voci, incluso Speech Pro, restituiscono MP3. Assegna audio a src di un elemento audio oppure decodifica la base64 dopo la virgola e salvala come .mp3. Il parlato Pro non richiede conversione lato client; gli ID vocali e i prezzi basati sui caratteri rimangono invariati. Vedi l'esempio Python eseguibile.

Discorso in streaming

Invia "stream": true allo stesso endpoint POST /v1/chat/speech. Streaming di supporto Speech Standard, Speech Light, Speech Pro e Speech Expressive; il catalogo espone speechModels[].streaming. Omettendo stream o impostandolo su false, si mantiene la risposta JSON sopra.

{ "text": "Hello. How was your day?", "voice": "speech-pro:Ashley", "stream": true }

La risposta è un flusso binario MP3 continuo con Content-Type: audio/mpeg, non JSON, base64 o SSE. Il proxy inoltra l'audio non appena arriva; La voce Pro viene convertita in modo incrementale in MP3. Ciò non garantisce la latenza di generazione di un modello. Il testo viene inviato come un'unica richiesta, senza suddivisione automatica della frase.

Con curl e FFmpeg installati, questo esempio riproduce l'audio mentre arriva:

curl --fail --no-buffer https://api.coldstart.win/v1/chat/speech \
  -H "Authorization: Bearer $COLDSTART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello. How was your day?","voice":"speech-pro:Ashley","stream":true}' \
  | ffplay -nodisp -autoexit -f mp3 -i pipe:0

Per un client di chiamata vocale, consumare il corpo della risposta in modo incrementale e alimentare un decoder/lettore MP3 persistente. In un browser, utilizza response.body.getReader() con un'implementazione di riproduzione in streaming; response.blob(), arrayBuffer() e json() attendono l'intera risposta. I blocchi di rete sono intervalli di byte arbitrari, non file MP3 autonomi. Annulla il recupero/lettore quando l'utente interrompe o riattacca. La riproduzione tramite browser richiede ancora la consueta interazione dell'utente per sbloccare l'audio.

Le intestazioni di risposta espongono X-Speech-Voice (ID voce pubblica con codifica URL), X-Speech-Credits, X-Speech-Characters e X-Speech-Usage-Id. L'importo del credito è l'addebito iniziale; le richieste completate utilizzano lo stesso prezzo basato sui caratteri delle richieste non in streaming. Uno streaming non riuscito o una disconnessione prima che il server completi l'elaborazione rimborsa la richiesta e registra l'utilizzo non riuscito. L'annullamento dopo il completamento del server non annulla un addebito andato a buon fine.

Prima dell'avvio dell'audio, gli errori utilizzano il normale stato HTTP e il corpo dell'errore JSON. Dopo l'avvio dell'audio, un errore chiude improvvisamente la connessione; scarta l'output incompleto e controlla la cronologia delle attività per il risultato della fatturazione finale. Non considerare HTTP 200 o la ricezione del primo blocco come prova del corretto completamento. I proxy aggiuntivi devono disabilitare il buffering e la compressione della risposta per questa route; il API invia X-Accel-Buffering: no e Cache-Control: no-store, no-transform.

Se il testo vocale viene rifiutato esplicitamente dalla policy dei contenuti, entrambe le modalità di risposta restituiscono HTTP 400 con il codice di errore content_policy_violation prima dell'avvio dell'audio. L'addebito viene rimborsato. Non riprovare automaticamente lo stesso testo; rivederlo per conformarsi alla politica sui contenuti. Il supporto dello streaming non rimuove le restrizioni sui contenuti.

Le richieste vocali sono indipendenti; passare esplicitamente l'ID della voce pubblica desiderata. Il JSON vocale contiene l'URI dei dati audio e la fatturazione; lo streaming restituisce byte audio.

Crediti vocali = numero di caratteri fatturabili del testo normalizzato × prezzo del modello/1,000, arrotondato per eccesso alle cifre decimali di 8. Speech Light, Speech Pro e Speech Expressive contano le unità di codice UTF-16, a seconda del modello selezionato: i caratteri cinesi/inglesi ordinari contano come uno e un carattere supplementare come 😀 conta come due. Speech Standard utilizza punti di codice Unicode. Il speechModels[].characterCounting del catalogo e il billing.character_counting della risposta identificano la regola di conteggio (utf16_code_units o unicode_codepoints); billing.characters è la quantità fatturata. La formattazione e le didascalie vengono rimosse prima della sintesi e del conteggio. La sintesi fallita o vuota viene rimborsata. Ogni richiesta di sintesi viene fatturata; la riproduzione dell'audio restituito non costa nulla. La console memorizza nella cache l'audio per messaggio e voce per la sessione della pagina corrente.