Trasforma il testo in parlato
Invia testo tramite una connessione WebSocket e ricevi audio in blocchi. Inizia con un esempio completo che salva un file WAV riproducibile.
wss://api.starsg.ai/v1/realtime?model=tts-altair-v1-miniSei nuovo alle API vocali? Inizia con questi quattro termini.
- WebSocket
- Una connessione che rimane aperta in modo che il tuo programma e il server possano scambiarsi messaggi in entrambe le direzioni.
- Modello
- Il motore che esegue l'attività. Utilizza un modello tts per parlare e un modello asr per trascrivere; copiare il suo esatto ID pubblico.
- Voce
- La voce utilizzata per la sintesi. Scegli uno voice_id dal catalogo del modello selezionato; il riconoscimento non ha bisogno di una voce.
- Chiave API
- Le tue credenziali di accesso, create nella console. Va nell'intestazione Authorization quando si apre la connessione.
La tua prima connessione
Scegli il metodo e l'ambiente di integrazione, quindi segui i passaggi seguenti.
Preparare una cartella e installare la libreria
Utilizzare Python 3.10 o successivo. Apri un terminale in una cartella vuota e installa OpenAI SDK ufficiale. Si collega al gateway vocale su WebSocket; l'esempio è stato testato con la versione seguente. Scaricamento ↗
python3 -m venv .venv .venv/bin/python -m pip install "openai[realtime]==3.35.1"
Imposta la chiave API
Crea una chiave nella console, quindi sostituisci YOUR_API_KEY di seguito con la tua chiave. Eseguilo nello stesso terminale dell'esempio. Gestisci le chiavi API ↗
export STARSG_API_KEY="YOUR_API_KEY"
Mantieni la tua chiave privata. Questi sono esempi locali/server, non codice del browser. Non inserire una chiave API permanente in una pagina Web o in un archivio pubblico. L'esecuzione dell'esempio effettua una chiamata al modello fatturabile.
Salva l'esempio ed eseguilo
Copia l'esempio completo di seguito in un nuovo file di testo semplice denominato speech.py in questa cartella. Salvalo, quindi esegui questo comando nello stesso terminale.
.venv/bin/python speech.py
Che aspetto ha il successoIl terminale stampa "Saved:" e crea output.wav. Aprilo con il tuo lettore audio. Per eseguire di nuovo, rinominare o rimuovere prima il file; l'esempio non lo sovrascriverà.
Esempio completo
Copia l'intero file. Si connette, configura la sessione, invia un input, attende il completamento e chiude la connessione. Non riprova automaticamente.
import asyncio
import base64
import json
import os
from pathlib import Path
import wave
from openai import AsyncOpenAI
API_KEY = os.environ["STARSG_API_KEY"]
BASE_URL = "https://api.starsg.ai/v1"
MODEL = "tts-altair-v1-mini"
SESSION = json.loads("{\"type\":\"realtime\",\"output_modalities\":[\"audio\"],\"audio\":{\"output\":{\"format\":{\"type\":\"audio/pcm\",\"rate\":24000}}}}")
TEXT = "Ciao! Questo è il mio primo esempio di sintesi vocale."
OUTPUT = Path("output.wav")
if OUTPUT.exists():
raise FileExistsError("output.wav exists; rename it before running again")
voice = os.environ.get("SPEECH_VOICE")
if voice:
SESSION["audio"]["output"]["voice"] = voice
async def main():
async with AsyncOpenAI(api_key=API_KEY, base_url=BASE_URL,
max_retries=0) as client:
async with client.realtime.connect(model=MODEL) as connection:
async def receive():
event = (await connection.recv()).model_dump()
if event["type"] == "error" or event["type"].endswith(".failed"):
raise RuntimeError(json.dumps(event.get("error", event), ensure_ascii=False))
return event
async def wait_for(kind):
while True:
event = await receive()
if event["type"] == kind:
return event
await wait_for("session.created")
await connection.session.update(session=SESSION)
await wait_for("session.updated")
await connection.conversation.item.create(item={
"type": "message", "role": "user",
"content": [{"type": "input_text", "text": TEXT}]
})
await connection.response.create()
audio = bytearray()
while True:
event = await receive()
if event["type"] == "response.output_audio.delta":
audio.extend(base64.b64decode(event["delta"], validate=True))
elif event["type"] == "response.done":
if event.get("response", {}).get("status") != "completed":
raise RuntimeError("Audio generation did not complete")
if not audio or len(audio) % 2:
raise ValueError("No valid PCM audio received")
with OUTPUT.open("xb") as target:
with wave.open(target, "wb") as wav:
wav.setparams((1, 2, 24000, 0, "NONE", "not compressed"))
wav.writeframes(audio)
print("Saved:", OUTPUT.resolve())
return
async def run():
await asyncio.wait_for(main(), timeout=90)
asyncio.run(run())
L'esempio utilizza un ID modello pubblico. La disponibilità dipende dall'account e dall'ambiente; scegli un modello che supporti questa attività in tempo reale. Visualizza i modelli ↗
Per scegliere una voce, trova il suo voice_id nel catalogo vocale di quel modello e imposta SPEECH_VOICE nel tuo terminale prima di eseguire. Ometterlo per utilizzare la voce predefinita. Un nome visualizzato come "Alloy" non è voice_id. Sostituisci VOICE_ID di seguito con un valore da quel catalogo.
export SPEECH_VOICE="VOICE_ID"
Flusso degli eventi
Ogni messaggio è un evento JSON. Invia significa il tuo programma → server; ricevere significa server → il tuo programma. Attendi session.updated prima di inviare input.
- Ricevere
session.createdIl server ha aperto una sessione. Ora puoi inviare la sua configurazione.
- Inviare
session.updateImposta l'attività, il formato audio e la voce opzionale.
- Ricevere
session.updatedIl server ha accettato la configurazione. Ora invia l'input.
- Inviare
conversation.item.createCrea un messaggio utente con content.type=input_text e content.text contenente il tuo testo.
- Inviare
response.createChiedi al server di generare l'audio per il testo.
- Ricevere
response.output_audio.deltaDecodifica il campo delta Base64 e raccogli i byte PCM in ordine. Questi blocchi non sono file WAV separati.
- Ricevere
response.doneControlla che Response.status sia completato, quindi aggiungi un'intestazione WAV e salva l'audio raccolto. Altri stati sono fallimenti.
Esaminare il messaggio session.update
{
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": [
"audio"
],
"audio": {
"output": {
"format": {
"type": "audio/pcm",
"rate": 24000
}
}
}
}
}Riferimento ai parametri
I nomi con punti mostrano a che punto appartiene un campo nell'oggetto JSON. La sezione "Obbligatorio" di seguito si applica al flusso di lavoro descritto in questa guida. Il supporto avanzato e i limiti dipendono dal modello.
Connessione e autenticazione
modelstringNecessarioParametro di query obbligatorio nello WebSocket URL. Utilizza l'ID modello pubblico esatto dal catalogo in tempo reale. I modelli ASR e TTS non sono intercambiabili.
Esempio/ambientazionetts-altair-v1-miniAuthorizationstringNecessarioIntestazione della connessione: Bearer, uno spazio, quindi la chiave API. Utilizzare la chiave per l'ambiente di destinazione; non inserirlo nello URL.
Esempio/ambientazioneBearer <API_KEY>
Sessione e input
session.typestringNecessarioUtilizza il tempo reale per una sessione di sintesi vocale. Questo è un flusso di lavoro di sintesi, non una conversazione generale con un agente vocale.
Esempio/ambientazione"realtime"session.output_modalitiesstring[]NecessarioRichiedi l'output audio per la sintesi. Invia questo array in session.update.
Esempio/ambientazione["audio"]session.audio.output.formatobjectNecessarioConfigurazione audio: il tipo è audio/pcm, la velocità è 24000. Questo esempio utilizza campioni little-endian mono con segno 16 bit: 48,000 byte al secondo. Le intestazioni WAV non vengono inviate tramite il socket.
Esempio/ambientazione{"type":"audio/pcm","rate":24000}session.audio.output.voicestringOpzionalevoice_id opzionale dal catalogo vocale del modello selezionato. È limitato al modello. Ometterlo per impostazione predefinita del server; non utilizzare il nome visualizzato del fornitore. Impostalo prima che inizi l'uscita audio.
Sfoglia le vociPredefinito/omesso La voce predefinita del modelloitem.content[].textstringNecessarioTesto da sintetizzare, all'interno di conversazione.item.create → elemento → contenuto. Imposta il tipo dell'elemento di contenuto su input_text, item.type su messaggio e item.role su utente. I limiti del testo dipendono dal modello.
Comandi vocali opzionali
Inizia senza questi controlli. Controlla il modello output_controls prima di aggiungerli. I valori di volume o intonazione non supportati causano un errore; non vengono silenziosamente ignorati. Blocco vocale e velocità dopo la prima uscita audio; volume e tono potrebbero essere aggiornati in seguito.
session.audio.output.speednumberOpzionaleMoltiplicatore della velocità di conversazione: 1.0 è la velocità normale. I valori min/max accettati dipendono dal modello; controllare il catalogo. Impostalo prima del primo audio in uscita.
Esempio/ambientazione1.0session.audio.output.options.volumenumber | nullOpzionaleEstensione della piattaforma in opzioni: moltiplicatore di guadagno, valore neutro 1.0. L'intervallo del protocollo è 0 < volume ≤ 10, ma il modello deve supportarlo. Omesso o nullo utilizza il valore neutro; i valori non supportati vengono rifiutati.
Predefinito/omesso1.0session.audio.output.options.pitchnumber | nullOpzionaleEstensione della piattaforma nelle opzioni: pitch shift in semitoni, valore neutro 0. L'intervallo del protocollo esterno è compreso tra −24 e 24; un modello può consentire di meno. Usa i suoi limiti pubblicizzati. Omesso o nullo utilizza l'intonazione neutra.
Predefinito/omesso0
Risoluzione dei problemi
Leggere prima il messaggio di errore restituito. L'apertura di una connessione o l'arrivo di un pezzo audio non significa che la richiesta è stata completata con successo.
Comando non trovato o modulo mancante
Installa il runtime selezionato, riapri il terminale ed esegui i comandi di installazione nella cartella del progetto. Per Python, utilizzare l'interprete .venv mostrato sopra; installa websocket-client, non il pacchetto websocket dal nome simile. Gli esempi Node.js utilizzano il pacchetto ws e un file .mjs.
401 / 403 o chiave API mancante
Verifica che la variabile di ambiente sia impostata in questo terminale, YOUR_API_KEY sia stata sostituita e la chiave appartenga all'ambiente di destinazione. Conferma l'accesso del modello e lo stato dell'account. Tieni la chiave lontana da screenshot e log.
L'handshake non riesce, 404 / 503 o modello non trovato
Controlla il nome host WSS, la porta, il percorso /v1/realtime e l'ID esatto del modello pubblico. Utilizzare il catalogo dei modelli in tempo reale per l'ambiente di destinazione. Non seguire un reindirizzamento a un HTTP URL non sicuro. Uno 503 potrebbe richiedere all'operatore del servizio di verificare la disponibilità.
Nessuna trascrizione, audio non valido o riproduzione confusa
Controlla 24 kHz, mono, PCM little-endian 16-bit e almeno 100 ms di parlato. Utilizzare il comando di conversione anziché rinominare il file. Il riconoscimento invia PCM non elaborato, non l'intestazione WAV. Per la sintesi, decodifica Base64 e unisci i blocchi PCM prima di creare un file WAV.
invalid_value o un controllo non supportato
Rimuovi le impostazioni opzionali di velocità, volume e tono, quindi controlla output_controls per il modello selezionato. Non riutilizzare voice_id o limiti numerici di un altro modello. Un session.update rifiutato non applica quella configurazione.
Timeout o connessione chiusa prima del completamento
Gli esempi si fermano dopo 90 secondi. Prova un input più breve e controlla l'accesso alla rete. Non considerare una trascrizione parziale o un audio parziale come un successo. Controlla se la richiesta precedente è stata eseguita prima di riprovare, per evitare chiamate duplicate.
output.wav esiste già o manca il file di input
Esegui lo script dalla cartella contenente Speech.py o Speech.mjs. Inserisci lì input.wav (Python) o input.pcm (Node.js). Rinominare l'output precedente.wav prima di generarlo nuovamente. Una riga “Finale:” è il risultato del riconoscimento; non crea un file audio.
Contesto del protocollo: OpenAI WebSockets ↗