Documentazione API

WebSocketEventi compatibili con OpenAI

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.

ID modello
Inserisci testoUscita audio
WSSwss://api.starsg.ai/v1/realtime?model=tts-altair-v1-mini
Sei 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.

  1. 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 ↗

    bash
    python3 -m venv .venv
    .venv/bin/python -m pip install "openai[realtime]==3.35.1"
  2. 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 ↗

    bash
    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.

  3. 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.

    bash
    .venv/bin/python speech.py
    Che aspetto ha il successo

    Il 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.

python
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.

bash
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.

  1. Ricevere
    session.created

    Il server ha aperto una sessione. Ora puoi inviare la sua configurazione.

  2. Inviare
    session.update

    Imposta l'attività, il formato audio e la voce opzionale.

  3. Ricevere
    session.updated

    Il server ha accettato la configurazione. Ora invia l'input.

  4. Inviare
    conversation.item.create

    Crea un messaggio utente con content.type=input_text e content.text contenente il tuo testo.

  5. Inviare
    response.create

    Chiedi al server di generare l'audio per il testo.

  6. Ricevere
    response.output_audio.delta

    Decodifica il campo delta Base64 e raccogli i byte PCM in ordine. Questi blocchi non sono file WAV separati.

  7. Ricevere
    response.done

    Controlla che Response.status sia completato, quindi aggiungi un'intestazione WAV e salva l'audio raccolto. Altri stati sono fallimenti.

Esaminare il messaggio session.update
json
{
  "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

modelstringNecessario

Parametro 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/ambientazione tts-altair-v1-mini
AuthorizationstringNecessario

Intestazione della connessione: Bearer, uno spazio, quindi la chiave API. Utilizzare la chiave per l'ambiente di destinazione; non inserirlo nello URL.

Esempio/ambientazione Bearer <API_KEY>

Sessione e input

session.typestringNecessario

Utilizza 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[]Necessario

Richiedi l'output audio per la sintesi. Invia questo array in session.update.

Esempio/ambientazione ["audio"]
session.audio.output.formatobjectNecessario

Configurazione 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.voicestringOpzionale

voice_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 voci
Predefinito/omesso La voce predefinita del modello
item.content[].textstringNecessario

Testo 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.speednumberOpzionale

Moltiplicatore 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/ambientazione 1.0
session.audio.output.options.volumenumber | nullOpzionale

Estensione 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/omesso 1.0
session.audio.output.options.pitchnumber | nullOpzionale

Estensione 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/omesso 0

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 ↗