API-Dokumentation

WebSocketOpenAI-kompatible Ereignisse

Verwandeln Sie Text in Sprache

Senden Sie Text über eine WebSocket-Verbindung und empfangen Sie Audio in Blöcken. Beginnen Sie mit einem vollständigen Beispiel, das eine abspielbare WAV-Datei speichert.

Modell-ID
Text reinAudioausgang
WSSwss://api.starsg.ai/v1/realtime?model=tts-altair-v1-mini
Neu bei Sprach-APIs? Beginnen Sie mit diesen vier Begriffen.
WebSocket
Eine Verbindung, die offen bleibt, sodass Ihr Programm und der Server Nachrichten in beide Richtungen austauschen können.
Modell
Die Engine, die die Aufgabe ausführt. Verwenden Sie zum Sprechen ein TTS-Modell und zum Transkribieren ein ASR-Modell. Kopieren Sie den genauen öffentlichen Ausweis.
Stimme
Die für die Synthese verwendete Stimme. Wählen Sie einen voice_id aus dem Katalog des ausgewählten Modells; Anerkennung braucht keine Stimme.
API-Schlüssel
Ihre Zugangsdaten, erstellt in der Konsole. Es wird in den Authorization-Header eingefügt, wenn die Verbindung geöffnet wird.

Ihre erste Verbindung

Wählen Sie Ihre Integrationsmethode und -umgebung und führen Sie dann die folgenden Schritte aus.

  1. Bereiten Sie einen Ordner vor und installieren Sie die Bibliothek

    Verwenden Sie Python 3.10 oder höher. Öffnen Sie ein Terminal in einem leeren Ordner und installieren Sie das offizielle OpenAI SDK. Die Verbindung zum Sprachgateway erfolgt über WebSocket. Das Beispiel wurde mit der folgenden Version getestet. Herunterladen ↗

    bash
    python3 -m venv .venv
    .venv/bin/python -m pip install "openai[realtime]==3.35.1"
  2. Legen Sie Ihren API-Schlüssel fest

    Erstellen Sie einen Schlüssel in der Konsole und ersetzen Sie dann YOUR_API_KEY unten durch Ihren eigenen Schlüssel. Führen Sie dies im selben Terminal wie das Beispiel aus. Verwalten Sie API-Schlüssel ↗

    bash
    export STARSG_API_KEY="YOUR_API_KEY"

    Halten Sie Ihren Schlüssel geheim. Dies sind lokale/Server-Beispiele, kein Browsercode. Platzieren Sie keinen permanenten API-Schlüssel auf einer Webseite oder einem öffentlichen Repository. Durch das Ausführen des Beispiels wird ein abrechenbarer Modellaufruf durchgeführt.

  3. Speichern Sie das Beispiel und führen Sie es aus

    Kopieren Sie das vollständige Beispiel unten in eine neue Nur-Text-Datei mit dem Namen speech.py in diesem Ordner. Speichern Sie es und führen Sie dann diesen Befehl im selben Terminal aus.

    bash
    .venv/bin/python speech.py
    Wie Erfolg aussieht

    Das Terminal gibt „Gespeichert:“ aus und erstellt eine Ausgabe.wav. Öffnen Sie es mit Ihrem Audioplayer. Um es erneut auszuführen, benennen Sie zunächst die Datei um oder entfernen Sie sie. das Beispiel wird es nicht überschreiben.

Vollständiges Beispiel

Kopieren Sie die gesamte Datei. Es stellt eine Verbindung her, konfiguriert die Sitzung, sendet eine Eingabe, wartet auf den Abschluss und schließt die Verbindung. Es wird nicht automatisch erneut versucht.

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 = "Hallo! Dies ist mein erstes Sprachsynthesebeispiel."
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())

Das Beispiel verwendet eine öffentliche Modell-ID. Die Verfügbarkeit hängt von Ihrem Konto und Ihrer Umgebung ab. Wählen Sie ein Modell, das diese Echtzeitaufgabe unterstützt. Modelle ansehen ↗

Um eine Stimme auszuwählen, suchen Sie im Stimmenkatalog dieses Modells nach voice_id und stellen Sie SPEECH_VOICE in Ihrem Terminal ein, bevor Sie es ausführen. Lassen Sie es weg, um die Standardstimme zu verwenden. Ein Anzeigename wie „Alloy“ ist nicht voice_id. Ersetzen Sie VOICE_ID unten durch einen Wert aus diesem Katalog.

bash
export SPEECH_VOICE="VOICE_ID"

Ereignisfluss

Jede Nachricht ist ein JSON-Ereignis. Senden bedeutet Ihr Programm → Server; Empfangen bedeutet Server → Ihr Programm. Warten Sie auf session.updated, bevor Sie Eingaben senden.

  1. Erhalten
    session.created

    Der Server hat eine Sitzung geöffnet. Sie können nun die Konfiguration senden.

  2. Schicken
    session.update

    Legen Sie die Aufgabe, das Audioformat und optional die Stimme fest.

  3. Erhalten
    session.updated

    Der Server hat die Konfiguration akzeptiert. Senden Sie nun die Eingabe.

  4. Schicken
    conversation.item.create

    Erstellen Sie eine Benutzernachricht mit content.type=input_text und content.text, die Ihren Text enthält.

  5. Schicken
    response.create

    Bitten Sie den Server, Audio für den Text zu generieren.

  6. Erhalten
    response.output_audio.delta

    Dekodieren Sie das Deltafeld Base64 und sammeln Sie die PCM-Bytes der Reihe nach. Bei diesen Blöcken handelt es sich nicht um separate WAV-Dateien.

  7. Erhalten
    response.done

    Überprüfen Sie, ob „response.status“ abgeschlossen ist, fügen Sie dann einen WAV-Header hinzu und speichern Sie das gesammelte Audio. Andere Status sind Fehler.

Überprüfen Sie die Meldung „session.update“.
json
{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "output_modalities": [
      "audio"
    ],
    "audio": {
      "output": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        }
      }
    }
  }
}

Parameterreferenz

Namen mit Punkten zeigen an, wo ein Feld im JSON-Objekt hingehört. „Erforderlich“ unten gilt für den Arbeitsablauf in diesem Handbuch. Erweiterte Unterstützung und Einschränkungen hängen vom Modell ab.

Verbindung und Authentifizierung

modelstringErforderlich

Erforderlicher Abfrageparameter im WebSocket URL. Verwenden Sie die genaue öffentliche Modell-ID aus dem Echtzeitkatalog. Die Modelle ASR und TTS sind nicht austauschbar.

Beispiel/Einstellung tts-altair-v1-mini
AuthorizationstringErforderlich

Verbindungsheader: Bearer, ein Leerzeichen, dann Ihr API-Schlüssel. Verwenden Sie den Schlüssel für die Zielumgebung. Legen Sie es nicht in den URL.

Beispiel/Einstellung Bearer <API_KEY>

Sitzung und Input

session.typestringErforderlich

Nutzen Sie Echtzeit für eine Text-to-Speech-Sitzung. Dies ist ein Synthese-Workflow, kein allgemeines Sprachagentengespräch.

Beispiel/Einstellung "realtime"
session.output_modalitiesstring[]Erforderlich

Fordern Sie eine Audioausgabe zur Synthese an. Senden Sie dieses Array in session.update.

Beispiel/Einstellung ["audio"]
session.audio.output.formatobjectErforderlich

Audiokonfiguration: Typ ist Audio/PCM, Rate ist 24000. In diesem Beispiel werden mono, vorzeichenbehaftete 16-Bit-Little-Endian-Samples verwendet: 48,000 Bytes pro Sekunde. WAV-Header werden nicht über den Socket gesendet.

Beispiel/Einstellung {"type":"audio/pcm","rate":24000}
session.audio.output.voicestringOptional

Optional voice_id aus dem Sprachkatalog des ausgewählten Modells. Es ist auf das Modell beschränkt. Lassen Sie es für den Serverstandard weg; Verwenden Sie keinen Anzeigenamen des Anbieters. Stellen Sie es ein, bevor die Audioausgabe beginnt.

Durchsuchen Sie Stimmen
Standard / weggelassen Die Standardstimme des Modells
item.content[].textstringErforderlich

Zu synthetisierender Text, innerhalb von „conversation.item.create“ → „Item“ → „Content“. Legen Sie den Typ des Inhaltselements auf input_text, item.type auf message und item.role auf user fest. Textgrenzen hängen vom Modell ab.

Optionale Sprachsteuerung

Beginnen Sie ohne diese Steuerelemente. Überprüfen Sie die output_controls des Modells, bevor Sie sie hinzufügen. Nicht unterstützte Lautstärke- oder Tonhöhenwerte verursachen einen Fehler; Sie werden nicht stillschweigend ignoriert. Sprach- und Geschwindigkeitssperre nach der ersten Audioausgabe; Lautstärke und Tonhöhe können später aktualisiert werden.

session.audio.output.speednumberOptional

E Sprechgeschwindigkeitsmultiplikator: 1.0 ist die normale Geschwindigkeit. Die akzeptierten Min/Max-Werte hängen vom Modell ab; Sehen Sie sich den Katalog an. Stellen Sie es vor der ersten Audioausgabe ein.

Beispiel/Einstellung 1.0
session.audio.output.options.volumenumber | nullOptional

Plattformerweiterung in Optionen: Verstärkungsmultiplikator, neutraler Wert 1.0. Der Protokollbereich ist 0 < Volumen ≤ 10, das Modell muss ihn jedoch unterstützen. Ausgelassen oder null verwendet den neutralen Wert; Nicht unterstützte Werte werden abgelehnt.

Standard / weggelassen 1.0
session.audio.output.options.pitchnumber | nullOptional

Plattformerweiterung in den Optionen: Tonhöhenverschiebung in Halbtönen, neutraler Wert 0. Der äußere Protokollbereich ist −24 bis 24; ein Modell erlaubt möglicherweise weniger. Nutzen Sie die angekündigten Limits. Weggelassen oder null verwendet neutrale Tonhöhe.

Standard / weggelassen 0

Fehlerbehebung

Lesen Sie zuerst die zurückgegebene Fehlermeldung. Das Öffnen einer Verbindung oder das Eintreffen eines Audioblocks bedeutet nicht, dass die Anfrage erfolgreich abgeschlossen wurde.

Befehl nicht gefunden oder Modul fehlt

Installieren Sie die ausgewählte Laufzeit, öffnen Sie Ihr Terminal erneut und führen Sie die Setup-Befehle im Projektordner aus. Verwenden Sie für Python den oben gezeigten .venv-Interpreter. Installieren Sie den Websocket-Client, nicht das gleichnamige Websocket-Paket. Node.js-Beispiele verwenden das ws-Paket und eine .mjs-Datei.

401 / 403 oder fehlender Schlüssel API

Überprüfen Sie, ob die Umgebungsvariable in diesem Terminal festgelegt ist, YOUR_API_KEY ersetzt wurde und der Schlüssel zur Zielumgebung gehört. Bestätigen Sie den Modellzugriff und den Kontostatus. Halten Sie den Schlüssel aus Screenshots und Protokollen fern.

Handshake schlägt fehl, 404 / 503 oder Modell nicht gefunden

Überprüfen Sie den WSS-Hostnamen, den Port, den /v1/realtime-Pfad und die genaue öffentliche Modell-ID. Verwenden Sie den Echtzeitmodellkatalog für die Zielumgebung. Folgen Sie nicht einer Weiterleitung zu einem unsicheren HTTP URL. A 503 kann vom Dienstbetreiber verlangen, die Verfügbarkeit zu prüfen.

Kein Transkript, ungültiger Ton oder verstümmelte Wiedergabe

Überprüfen Sie 24 kHz, Mono, 16-Bit-Little-Endian-PCM und mindestens 100 ms Sprache. Verwenden Sie den Konvertierungsbefehl, anstatt die Datei umzubenennen. Die Erkennung sendet rohes PCM, nicht den WAV-Header. Zur Synthese dekodieren Sie Base64 und fügen Sie PCM-Blöcke zusammen, bevor Sie eine WAV-Datei erstellen.

invalid_value oder ein nicht unterstütztes Steuerelement

Entfernen Sie optionale Geschwindigkeits-, Lautstärke- und Tonhöheneinstellungen und überprüfen Sie dann output_controls für das ausgewählte Modell. Verwenden Sie voice_id oder numerische Grenzwerte eines anderen Modells nicht wieder. Ein abgelehntes session.update wendet diese Konfiguration nicht an.

Zeitüberschreitung oder Verbindung wird vorzeitig geschlossen

Die Beispiele stoppen nach 90 Sekunden. Versuchen Sie es mit einer kürzeren Eingabe und prüfen Sie den Netzwerkzugriff. Betrachten Sie ein teilweises Transkript oder eine teilweise Audioaufnahme nicht als Erfolg. Überprüfen Sie, ob die vorherige Anfrage ausgeführt wurde, bevor Sie es erneut versuchen, um doppelte Aufrufe zu vermeiden.

Die Datei „output.wav“ existiert bereits oder die Eingabedatei fehlt

Führen Sie das Skript aus dem Ordner aus, der Speech.py ​​oder Speech.mjs enthält. Geben Sie dort input.wav (Python) oder input.pcm (Node.js) ein. Benennen Sie die vorherige Ausgabe.wav um, bevor Sie sie erneut generieren. Eine „Final:“-Zeile ist das Erkennungsergebnis; Es wird keine Audiodatei erstellt.

Protokollhintergrund: OpenAI WebSockets ↗