Transformez la parole en texte
Envoyez de l'audio via une connexion WebSocket et recevez des mises à jour de transcription. Ce premier exemple lit un enregistrement afin que vous puissiez apprendre le flux sans configurer de microphone.
wss://api.starsg.ai/v1/realtime?model=asr-altair-v1-miniVous débutez avec les API vocales ? Commencez par ces quatre termes.
- WebSocket
- Une connexion qui reste ouverte afin que votre programme et le serveur puissent échanger des messages dans les deux sens.
- Modèle
- Le moteur qui effectue la tâche. Utiliser un modèle tts pour parler et un modèle asr pour transcrire ; copiez son identifiant public exact.
- Entrée audio
- L'enregistrement à retranscrire. Cet exemple utilise du PCM mono, 24 kHz, 16-bit. Python lit l'audio d'un fichier WAV ; Node.js lit un fichier PCM sans en-tête.
- Clé API
- Votre identifiant d'accès, créé dans la console. Il va dans l’en-tête Authorization lorsque la connexion s’ouvre.
Votre première connexion
Choisissez votre méthode d'intégration et votre environnement, puis suivez les étapes ci-dessous.
Préparez un dossier et installez la bibliothèque
Utilisez Python 3.10 ou une version ultérieure. Ouvrez un terminal dans un dossier vide et installez le OpenAI SDK officiel. Il se connecte à la passerelle vocale via WebSocket ; l'exemple a été testé avec la version ci-dessous. Télécharger ↗
python3 -m venv .venv .venv/bin/python -m pip install "openai[realtime]==3.35.1"
Définissez votre clé API
Créez une clé dans la console, puis remplacez YOUR_API_KEY ci-dessous par votre propre clé. Exécutez-le dans le même terminal que l'exemple. Gérer les clés API ↗
export STARSG_API_KEY="YOUR_API_KEY"
Gardez votre clé privée. Ce sont des exemples locaux/de serveur, pas du code de navigateur. Ne placez pas de clé API permanente dans une page Web ou un référentiel public. L’exécution de l’exemple génère un appel de modèle facturable.
Préparez un court enregistrement
Placez input.wav dans le même dossier : mono, 24,000 Hz, 16-bit PCM WAV, au moins 100 ms de parole. Vous pouvez également utiliser output.wav de l'exemple de synthèse et le renommer input.wav.
Si votre enregistrement utilise un autre format, installez FFmpeg, remplacez recording.mp3 par votre nom de fichier, puis convertissez-le : FFmpeg ↗
ffmpeg -n -i recording.mp3 -ar 24000 -ac 1 -c:a pcm_s16le input.wav
Enregistrez l'exemple et exécutez-le
Copiez l'exemple complet ci-dessous dans un nouveau fichier texte brut nommé speech.py dans ce dossier. Enregistrez-le, puis exécutez cette commande dans le même terminal.
.venv/bin/python speech.py
À quoi ressemble le succèsLe terminal peut imprimer les mises à jour « Partielle : », puis « Finale : » suivi de la transcription complétée. Certains modèles peuvent produire uniquement le résultat final.
Exemple complet
Copiez l'intégralité du fichier. Il se connecte, configure la session, envoie une entrée, attend la fin et ferme la connexion. Il ne réessaye pas automatiquement.
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'exemple utilise un ID de modèle public. La disponibilité dépend de votre compte et de votre environnement ; choisissez un modèle qui prend en charge cette tâche en temps réel. Voir les modèles ↗
Flux d'événements
Chaque message est un événement JSON. Envoyer signifie votre programme → serveur ; recevoir signifie serveur → votre programme. Attendez session.updated avant d’envoyer votre entrée.
- Recevoir
session.createdLe serveur a ouvert une session. Vous pouvez maintenant envoyer sa configuration.
- Envoyer
session.updateDéfinissez la session de transcription, le format audio d'entrée, le modèle de reconnaissance et la détection de virage.
- Recevoir
session.updatedLe serveur a accepté la configuration. Maintenant, envoyez l'entrée.
- Envoyer
input_audio_buffer.appendEnvoyez Base64 PCM dans le champ audio. Cet exemple utilise des morceaux d'octets 4,800, équivalents à 100 ms au format configuré.
- Envoyer
input_audio_buffer.commitTerminez le tour d’entrée. Avec turn_detection=null, vous devez vous engager explicitement ; n'envoyez pas de réponse.create pour reconnaissance.
- Recevoir
conversation.item.input_audio_transcription.deltaLire delta et text_mode ; mettez à jour les item_id et content_index correspondants.
- Recevoir
conversation.item.input_audio_transcription.completedLe champ de transcription constitue le texte final faisant autorité. Enregistrez-le, puis fermez cet exemple en un seul tour.
Inspectez le message 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
}
}
}
}Référence des paramètres
Les noms avec des points indiquent la place d'un champ dans l'objet JSON. « Obligatoire » ci-dessous s'applique au flux de travail de ce guide. La prise en charge avancée et les limites dépendent du modèle.
Connexion et authentification
modelstringRequisParamètre de requête obligatoire dans le WebSocket URL. Utilisez l’ID de modèle public exact du catalogue en temps réel. Les modèles ASR et TTS ne sont pas interchangeables.
Exemple / réglageasr-altair-v1-miniAuthorizationstringRequisEn-tête de connexion : Bearer, un espace, puis votre clé API. Utilisez la clé de l'environnement cible ; ne le mettez pas dans le URL.
Exemple / réglageBearer <API_KEY>
Session et contribution
session.typestringRequisUtilisez la transcription uniquement à des fins de reconnaissance. Il renvoie du texte sans générer de réponse vocale d'assistant.
Exemple / réglage"transcription"session.audio.input.formatobjectRequisConfiguration audio : le type est audio/pcm, le débit est 24000. Cet exemple utilise des échantillons little-endian mono bits signés 16 : 48,000 octets par seconde. Les en-têtes WAV ne sont pas envoyés via le socket.
Exemple / réglage{"type":"audio/pcm","rate":24000}session.audio.input.transcription.modelstringRequisUtilisez le même ID de modèle public ASR que la requête URL. Ne remplacez pas le nom du modèle du fournisseur en amont.
Exemple / réglageasr-altair-v1-minisession.audio.input.turn_detectionobject | nullFacultatifL'exemple définit explicitement null pour désactiver la détection automatique des virages (VAD). Envoyez input_audio_buffer.commit lorsque tous les signaux audio d’entrée ont été envoyés. Il s'agit d'un paramètre choisi, et non d'une réclamation concernant la valeur par défaut du serveur.
Exemple / réglagenullaudiostringRequisBase64-encoded octets PCM bruts dans input_audio_buffer.append. Envoyez au moins 100 ms dans un tour engagé. Un MP3, un en-tête WAV, un nom de fichier ou un URL ne peuvent pas remplacer ce champ.
Dépannage
Lisez d'abord l'erreur renvoyée. Une connexion ouverte ou une transcription partielle ne signifie pas que ce tour de reconnaissance est terminé. Attendez la transcription finale.
Commande introuvable ou module manquant
Installez le runtime sélectionné, rouvrez votre terminal et exécutez les commandes de configuration dans le dossier du projet. Pour Python, utilisez l'interpréteur .venv présenté ci-dessus ; installez websocket-client, pas le package websocket du même nom. Les exemples Node.js utilisent le package ws et un fichier .mjs.
401 / 403 ou clé API manquante
Vérifiez que la variable d'environnement est définie dans ce terminal, que YOUR_API_KEY a été remplacée et que la clé appartient à l'environnement cible. Confirmez l'accès au modèle et l'état du compte. Gardez la clé hors des captures d’écran et des journaux.
Échec de la négociation, 404 / 503 ou modèle introuvable
Vérifiez le nom d'hôte WSS, le port, le chemin /v1/realtime et l'ID de modèle public exact. Utilisez le catalogue de modèles en temps réel pour l'environnement cible. Ne suivez pas une redirection vers un HTTP URL non sécurisé. Un 503 peut exiger que l'opérateur de service vérifie la disponibilité.
Aucune transcription ou erreur de format audio
Utilisez un PCM petit-boutiste mono, 24 kHz, signé 16 bits avec au moins 100 ms de parole. Python lit PCM WAV ; Node.js lit PCM sans en-tête. Convertissez l'enregistrement à l'aide de la commande ci-dessus plutôt que de simplement renommer son extension.
Délai d'expiration ou connexion fermée avant la fin
Les exemples s'arrêtent après 90 secondes. Essayez une saisie plus courte et vérifiez l'accès au réseau. Ne considérez pas une transcription partielle ou un audio partiel comme un succès. Vérifiez si la requête précédente a été exécutée avant de réessayer, pour éviter les appels en double.
Impossible de trouver input.wav ou input.pcm
Conservez l'enregistrement à côté de l'exemple et exécutez la commande à partir de ce dossier. Python utilise input.wav ; Node.js utilise input.pcm. Le texte final apparaît après « Final : » ; la reconnaissance ne crée pas de fichier audio.
Contexte du protocole : OpenAI WebSockets ↗