API-Dokumentation

WebSocketOpenAI-kompatible Ereignisse

Verwandeln Sie Sprache in Text

Senden Sie Audio über eine WebSocket-Verbindung und erhalten Sie Transkriptionsaktualisierungen. In diesem ersten Beispiel wird eine Aufnahme vorgelesen, sodass Sie den Ablauf lernen können, ohne ein Mikrofon aufzustellen.

Modell-ID
AudioeingangText raus
WSSwss://api.starsg.ai/v1/realtime?model=asr-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.
Audioeingang
Die zu transkribierende Aufnahme. In diesem Beispiel wird Mono, 24 kHz, 16-Bit PCM verwendet. Python liest das Audio aus einer WAV-Datei; Node.js liest eine PCM-Datei ohne Header.
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. Bereiten Sie eine kurze Aufnahme vor

    Platzieren Sie input.wav im selben Ordner: Mono, 24,000 Hz, 16-Bit-PCM-WAV, mindestens 100 ms Sprache. Sie können auch „output.wav“ aus dem Synthesebeispiel verwenden und es in „input.wav“ umbenennen.

    Wenn Ihre Aufnahme ein anderes Format verwendet, installieren Sie FFmpeg, ersetzen Sie recording.mp3 durch Ihren Dateinamen und konvertieren Sie es dann: FFmpeg ↗

    bash
    ffmpeg -n -i recording.mp3 -ar 24000 -ac 1 -c:a pcm_s16le input.wav
  4. 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 druckt möglicherweise „Teilweise:“-Aktualisierungen, dann „Endgültig:“, gefolgt von der abgeschlossenen Transkription. Einige Modelle liefern möglicherweise nur das Endergebnis.

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 = "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())

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 ↗

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 Transkriptionssitzung, das Eingabeaudioformat, das Erkennungsmodell und die Abbiegeerkennung fest.

  3. Erhalten
    session.updated

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

  4. Schicken
    input_audio_buffer.append

    Senden Sie Base64 PCM im Audiofeld. In diesem Beispiel werden 4,800-Byte-Blöcke verwendet, was 100 ms im konfigurierten Format entspricht.

  5. Schicken
    input_audio_buffer.commit

    Beenden Sie die Eingaberunde. Bei turn_detection=null müssen Sie einen expliziten Commit durchführen. Senden Sie nicht „response.create“ zur Erkennung.

  6. Erhalten
    conversation.item.input_audio_transcription.delta

    Delta und text_mode lesen; Aktualisieren Sie die passenden item_id und content_index.

  7. Erhalten
    conversation.item.input_audio_transcription.completed

    Das Transkriptfeld ist der maßgebliche Endtext. Speichern Sie es und schließen Sie dann dieses Single-Turn-Beispiel.

Überprüfen Sie die Meldung „session.update“.
json
{
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        },
        "transcription": {
          "model": "asr-altair-v1-mini"
        },
        "turn_detection": null
      }
    }
  }
}

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 asr-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

Verwenden Sie die Transkription nur zur Erkennung. Es gibt Text zurück, ohne eine Sprachantwort des Assistenten zu generieren.

Beispiel/Einstellung "transcription"
session.audio.input.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.input.transcription.modelstringErforderlich

Verwenden Sie dieselbe öffentliche Modell-ID ASR wie die URL-Abfrage. Ersetzen Sie nicht den Modellnamen des Upstream-Anbieters.

Beispiel/Einstellung asr-altair-v1-mini
session.audio.input.turn_detectionobject | nullOptional

Das Beispiel legt explizit null fest, um die automatische Abbiegeerkennung (VAD) zu deaktivieren. Senden Sie input_audio_buffer.commit, wenn das gesamte Eingangsaudio gesendet wurde. Dies ist eine gewählte Einstellung, keine Aussage über die Server-Standardeinstellung.

Beispiel/Einstellung null
audiostringErforderlich

Base64-encoded rohe PCM-Bytes in input_audio_buffer.append. Senden Sie mindestens 100 ms in einer festgelegten Runde. Ein MP3, WAV-Header, Dateiname oder URL kann dieses Feld nicht ersetzen.

Fehlerbehebung

Lesen Sie zuerst den zurückgegebenen Fehler. Eine offene Verbindung oder ein teilweises Transkript bedeutet nicht, dass diese Erkennungsrunde abgeschlossen ist. Warten Sie auf das endgültige Transkript.

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 oder ein Fehler im Audioformat

Verwenden Sie Mono, 24 kHz, vorzeichenbehaftetes 16-Bit-Little-Endian-PCM mit mindestens 100 ms Sprache. Python liest PCM WAV; Node.js liest PCM ohne Header. Konvertieren Sie die Aufnahme mit dem obigen Befehl, anstatt nur die Erweiterung umzubenennen.

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.

Input.wav oder input.pcm kann nicht gefunden werden

Bewahren Sie die Aufzeichnung neben dem Beispiel auf und führen Sie den Befehl in diesem Ordner aus. Python verwendet input.wav; Node.js verwendet input.pcm. Der endgültige Text erscheint nach „Final:“; Die Erkennung erstellt keine Audiodatei.

Protokollhintergrund: OpenAI WebSockets ↗