Trasforma il discorso in testo
Invia audio tramite una connessione WebSocket e ricevi aggiornamenti sulla trascrizione. Questo primo esempio legge una registrazione in modo da poter apprendere il flusso senza impostare un microfono.
wss://api.starsg.ai/v1/realtime?model=asr-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.
- Ingresso audio
- La registrazione da trascrivere. Questo esempio utilizza PCM mono, 24 kHz, 16-bit. Python legge l'audio da un file WAV; Node.js legge un file PCM senza intestazione.
- 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.
Prepara una breve registrazione
Inserisci input.wav nella stessa cartella: mono, 24,000 Hz, 16-bit PCM WAV, almeno 100 ms di parlato. Puoi anche usare output.wav dall'esempio di sintesi e rinominarlo input.wav.
Se la tua registrazione utilizza un altro formato, installa FFmpeg, sostituisci recording.mp3 con il nome del tuo file, quindi convertilo: FFmpeg ↗
ffmpeg -n -i recording.mp3 -ar 24000 -ac 1 -c:a pcm_s16le input.wav
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 può stampare gli aggiornamenti “Parziali:”, quindi “Finali:” seguiti dalla trascrizione completata. Alcuni modelli potrebbero produrre solo il risultato finale.
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 = "asr-altair-v1-mini"
SESSION = json.loads("{\"type\":\"transcription\",\"audio\":{\"input\":{\"format\":{\"type\":\"audio/pcm\",\"rate\":24000},\"transcription\":{\"model\":\"asr-altair-v1-mini\"},\"turn_detection\":null}}}")
with wave.open("input.wav", "rb") as source:
if (source.getnchannels(), source.getsampwidth(),
source.getframerate(), source.getcomptype()) != (1, 2, 24000, "NONE"):
raise ValueError("Expected mono, 24 kHz, 16-bit PCM WAV")
pcm = source.readframes(source.getnframes())
if len(pcm) < 4800:
raise ValueError("Audio must be at least 100 ms")
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")
for offset in range(0, len(pcm), 4800):
await connection.input_audio_buffer.append(
audio=base64.b64encode(pcm[offset:offset + 4800]).decode()
)
await connection.input_audio_buffer.commit()
transcripts = {}
while True:
event = await receive()
kind = event["type"]
item = (event.get("item_id"), event.get("content_index", 0))
if kind == "conversation.item.input_audio_transcription.delta":
mode = event.get("text_mode", "snapshot")
if mode == "snapshot":
transcripts[item] = event["delta"]
elif mode == "append":
transcripts[item] = transcripts.get(item, "") + event["delta"]
else:
raise ValueError("Unknown text_mode: " + str(mode))
print("Partial:", transcripts[item])
elif kind == "conversation.item.input_audio_transcription.completed":
if not event.get("transcript", "").strip():
raise ValueError("Empty final transcript")
print("Final:", event["transcript"])
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 ↗
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 la sessione di trascrizione, il formato audio di input, il modello di riconoscimento e il rilevamento delle svolte.
- Ricevere
session.updatedIl server ha accettato la configurazione. Ora invia l'input.
- Inviare
input_audio_buffer.appendInvia Base64 PCM nel campo audio. Questo esempio utilizza blocchi di byte 4,800, equivalenti a 100 ms nel formato configurato.
- Inviare
input_audio_buffer.commitTermina il turno di input. Con turn_detection=null è necessario impegnarsi esplicitamente; non inviare Response.create per il riconoscimento.
- Ricevere
conversation.item.input_audio_transcription.deltaLeggi delta e text_mode; aggiorna item_id e content_index corrispondenti.
- Ricevere
conversation.item.input_audio_transcription.completedIl campo della trascrizione è il testo finale autorevole. Salvalo, quindi chiudi questo esempio a giro singolo.
Esaminare il messaggio session.update
{
"type": "session.update",
"session": {
"type": "transcription",
"audio": {
"input": {
"format": {
"type": "audio/pcm",
"rate": 24000
},
"transcription": {
"model": "asr-altair-v1-mini"
},
"turn_detection": null
}
}
}
}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/ambientazioneasr-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.typestringNecessarioUtilizzare la trascrizione solo per il riconoscimento. Restituisce il testo senza generare una risposta vocale dell'assistente.
Esempio/ambientazione"transcription"session.audio.input.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.input.transcription.modelstringNecessarioUtilizza lo stesso ID modello pubblico ASR della query URL. Non sostituire il nome del modello del fornitore a monte.
Esempio/ambientazioneasr-altair-v1-minisession.audio.input.turn_detectionobject | nullOpzionaleL'esempio imposta esplicitamente null per disabilitare il rilevamento automatico delle svolte (VAD). Invia input_audio_buffer.commit quando tutto l'audio in ingresso è stato inviato. Si tratta di un'impostazione scelta, non di un reclamo relativo all'impostazione predefinita del server.
Esempio/ambientazionenullaudiostringNecessarioBase64-encoded byte PCM grezzi in input_audio_buffer.append. Invia almeno 100 ms in un turno impegnato. Un MP3, un'intestazione WAV, un nome file o URL non può sostituire questo campo.
Risoluzione dei problemi
Leggi prima l'errore restituito. Una connessione aperta o una trascrizione parziale non significa che questo turno di riconoscimento sia terminato. Aspetta la trascrizione finale.
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 o errore nel formato audio
Utilizzare PCM little-endian mono, 24 kHz, firmato 16-bit con almeno 100 ms di parlato. Python legge PCM WAV; Node.js legge PCM senza intestazione. Converti la registrazione utilizzando il comando sopra invece di rinominarne semplicemente l'estensione.
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.
Impossibile trovare input.wav o input.pcm
Conserva la registrazione accanto all'esempio ed esegui il comando da quella cartella. Python utilizza input.wav; Node.js utilizza input.pcm. Il testo finale appare dopo “Finale:”; il riconoscimento non crea un file audio.
Contesto del protocollo: OpenAI WebSockets ↗