Transformez le texte en discours
Envoyez du texte via une connexion WebSocket et recevez de l'audio par morceaux. Commencez par un exemple complet qui enregistre un fichier WAV lisible.
wss://api.starsg.ai/v1/realtime?model=tts-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.
- Voix
- La voix utilisée pour la synthèse. Choisissez un voice_id dans le catalogue du modèle sélectionné ; la reconnaissance n'a pas besoin d'une voix.
- 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.
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 imprime « Enregistré : » et crée output.wav. Ouvrez-le avec votre lecteur audio. Pour réexécuter, renommez ou supprimez d'abord ce fichier ; l'exemple ne l'écrasera pas.
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 = "tts-altair-v1-mini"
SESSION = json.loads("{\"type\":\"realtime\",\"output_modalities\":[\"audio\"],\"audio\":{\"output\":{\"format\":{\"type\":\"audio/pcm\",\"rate\":24000}}}}")
TEXT = "Bonjour! Ceci est mon premier exemple de synthèse 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'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 ↗
Pour choisir une voix, recherchez son voice_id dans le catalogue vocal de ce modèle et définissez SPEECH_VOICE dans votre terminal avant de l'exécuter. Omettez-le pour utiliser la voix par défaut. Un nom d'affichage tel que « Alloy » n'est pas le voice_id. Remplacez VOICE_ID ci-dessous par une valeur de ce catalogue.
export SPEECH_VOICE="VOICE_ID"
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 tâche, le format audio et la voix facultative.
- Recevoir
session.updatedLe serveur a accepté la configuration. Maintenant, envoyez l'entrée.
- Envoyer
conversation.item.createCréez un message utilisateur avec content.type=input_text et content.text contenant votre texte.
- Envoyer
response.createDemandez au serveur de générer de l'audio pour le texte.
- Recevoir
response.output_audio.deltaDécodez le champ delta Base64 et collectez les octets PCM dans l'ordre. Ces morceaux ne sont pas des fichiers WAV distincts.
- Recevoir
response.doneVérifiez que réponse.status est terminé, puis ajoutez un en-tête WAV et enregistrez l'audio collecté. D'autres statuts sont des échecs.
Inspectez le message session.update
{
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": [
"audio"
],
"audio": {
"output": {
"format": {
"type": "audio/pcm",
"rate": 24000
}
}
}
}
}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églagetts-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 le temps réel pour une session de synthèse vocale. Il s'agit d'un flux de travail de synthèse et non d'une conversation générale avec un agent vocal.
Exemple / réglage"realtime"session.output_modalitiesstring[]RequisDemander une sortie audio pour la synthèse. Envoyez ce tableau dans session.update.
Exemple / réglage["audio"]session.audio.output.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.output.voicestringFacultatifvoice_id en option dans le catalogue vocal du modèle sélectionné. Il est limité au modèle. Omettez-le pour la valeur par défaut du serveur ; n’utilisez pas de nom d’affichage de fournisseur. Réglez-le avant le début de la sortie audio.
Parcourir les voixPar défaut / omis La voix par défaut du modèleitem.content[].textstringRequisTexte à synthétiser, dans conversation.item.create → item → content. Définissez le type de l'élément de contenu sur input_text, item.type sur message et item.role sur user. Les limites de texte dépendent du modèle.
Commandes vocales en option
Commencez sans ces contrôles. Vérifiez le output_controls du modèle avant de les ajouter. Les valeurs de volume ou de hauteur non prises en charge provoquent une erreur ; ils ne sont pas ignorés en silence. Verrouillage vocal et rapide après la première sortie audio ; le volume et la hauteur peuvent être mis à jour ultérieurement.
session.audio.output.speednumberFacultatifMultiplicateur de débit de parole : 1.0 correspond à la vitesse normale. Les valeurs min/max acceptées dépendent du modèle ; consultez le catalogue. Réglez-le avant la première sortie audio.
Exemple / réglage1.0session.audio.output.options.volumenumber | nullFacultatifExtension de plateforme en options : multiplicateur de gain, valeur neutre 1.0. La plage de protocole est 0 < volume ≤ 10, mais le modèle doit la prendre en charge. Omis ou nul utilise la valeur neutre ; les valeurs non prises en charge sont rejetées.
Par défaut / omis1.0session.audio.output.options.pitchnumber | nullFacultatifExtension de plateforme en options : pitch shift en demi-tons, valeur neutre 0. La plage de protocole externe va de −24 à 24 ; un modèle peut permettre moins. Utilisez ses limites annoncées. Omis ou nul utilise une hauteur neutre.
Par défaut / omis0
Dépannage
Lisez d'abord le message d'erreur renvoyé. Une ouverture de connexion ou l’arrivée d’un morceau audio ne signifie pas que la demande s’est terminée avec succès.
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, audio invalide ou lecture tronquée
Vérifiez 24 kHz, mono, PCM petit-boutiste 16 bits et au moins 100 ms de parole. Utilisez la commande de conversion plutôt que de renommer le fichier. La reconnaissance envoie du PCM brut, pas l'en-tête WAV. Pour la synthèse, décodez Base64 et joignez les morceaux PCM avant de créer un fichier WAV.
invalid_value ou un contrôle non pris en charge
Supprimez les paramètres facultatifs de vitesse, de volume et de hauteur, puis vérifiez output_controls pour le modèle sélectionné. Ne réutilisez pas le voice_id ou les limites numériques d’un autre modèle. Une session.update rejetée n'applique pas cette configuration.
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.
output.wav existe déjà ou le fichier d'entrée est manquant
Exécutez le script à partir du dossier contenant Speech.py ou Speech.mjs. Mettez-y input.wav (Python) ou input.pcm (Node.js). Renommez le fichier output.wav précédent avant de le générer à nouveau. Une ligne « Final : » est le résultat de la reconnaissance ; il ne crée pas de fichier audio.
Contexte du protocole : OpenAI WebSockets ↗