Documentation API

WebSocketÉvénements compatibles OpenAI

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.

ID du modèle
Texte dansSortie audio
WSSwss://api.starsg.ai/v1/realtime?model=tts-altair-v1-mini
Vous 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.

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

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

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

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

    bash
    .venv/bin/python speech.py
    À quoi ressemble le succès

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

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 = "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.

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

  1. Recevoir
    session.created

    Le serveur a ouvert une session. Vous pouvez maintenant envoyer sa configuration.

  2. Envoyer
    session.update

    Définissez la tâche, le format audio et la voix facultative.

  3. Recevoir
    session.updated

    Le serveur a accepté la configuration. Maintenant, envoyez l'entrée.

  4. Envoyer
    conversation.item.create

    Créez un message utilisateur avec content.type=input_text et content.text contenant votre texte.

  5. Envoyer
    response.create

    Demandez au serveur de générer de l'audio pour le texte.

  6. Recevoir
    response.output_audio.delta

    Décodez le champ delta Base64 et collectez les octets PCM dans l'ordre. Ces morceaux ne sont pas des fichiers WAV distincts.

  7. Recevoir
    response.done

    Vé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
json
{
  "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

modelstringRequis

Paramè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églage tts-altair-v1-mini
AuthorizationstringRequis

En-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églage Bearer <API_KEY>

Session et contribution

session.typestringRequis

Utilisez 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[]Requis

Demander une sortie audio pour la synthèse. Envoyez ce tableau dans session.update.

Exemple / réglage ["audio"]
session.audio.output.formatobjectRequis

Configuration 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.voicestringFacultatif

voice_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 voix
Par défaut / omis La voix par défaut du modèle
item.content[].textstringRequis

Texte à 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.speednumberFacultatif

Multiplicateur 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églage 1.0
session.audio.output.options.volumenumber | nullFacultatif

Extension 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 / omis 1.0
session.audio.output.options.pitchnumber | nullFacultatif

Extension 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 / omis 0

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 ↗