> ## Documentation Index > Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt > Use this file to discover all available pages before exploring further. # Echtzeit-Sprachtranskription > Über WebSocket eine dauerhafte Verbindung aufbauen, Text während des Sprechens ausgeben und so eine latenzarme Streaming-Sprache-zu-Text-Umwandlung realisieren ## Einführung Die Echtzeit-Sprachtranskription baut über WebSocket (ein Protokoll, das eine dauerhafte Verbindung zwischen Client und Server hält und Daten in beide Richtungen übertragen kann) eine persistente Verbindung auf und verarbeitet den kontinuierlich eingehenden Audiostream so, dass er gleichzeitig empfangen, transkribiert und zurückgegeben wird. Das eignet sich für latenzempfindliche Sprachszenarien. Der Unterschied zur Dateitranskription [STT](/de/api/STT): | Dimension | Dateitranskription (STT) | Echtzeittranskription (diese Seite) | | --------- | ---------------------------------------------------- | --------------------------------------------------------------- | | Protokoll | HTTP, eine Anfrage liefert das vollständige Ergebnis | WebSocket, liefert fortlaufend inkrementelle Ergebnisse | | Eingabe | vollständige Audiodatei (≤25MB) | kontinuierlicher Audiostream (PCM-Segmente) | | Latenz | wartet, bis das gesamte Segment verarbeitet ist | gibt Text bereits während des Sprechens zurück | | Einsatz | Aufnahmetranskription, Untertitelerstellung | Echtzeit-Meeting-Untertitel, Sprachassistenten, Live-Mitschrift | **Verfügbare Modelle:** * **gpt-live-transcribe**: Streaming-Transkriptionsmodell, unterstützt mehrere Sprachen und gibt den transkribierten Text in Echtzeit zur Audioeingabe aus. **Diese Schnittstelle ist für die serverseitige Integration gedacht, ein Browser kann sich nicht direkt verbinden.** Aus Sicherheitsgründen prüft und verweigert das Gateway Verbindungen mit `Origin`-Header, lehnt das Subprotokoll `openai-insecure-api-key` ab und akzeptiert den Schlüssel nur über den standardmäßigen `Authorization`-Header. Ein vom Browser initiierter WebSocket fügt automatisch einen `Origin`-Header hinzu und wird daher abgelehnt. Wenn Sie im Frontend eine Echtzeittranskription benötigen, bauen Sie auf Ihrem eigenen Server die Verbindung zum Gateway auf und leiten die Ergebnisse anschließend an das Frontend weiter. ## Schnellstart ### Verbindungs-Endpoint ```text theme={null} wss://aihubmix.com/v1/realtime?intent=transcription&model=gpt-live-transcribe ``` * `intent=transcription`: **Pflicht**, deklariert dies als Transkriptionssitzung. * `model=gpt-live-transcribe`: **Pflicht**, das Modell wird beim Verbindungsaufbau durch den URL-Parameter fest vorgegeben und kann während der Sitzung nicht mehr geändert werden (siehe die Einschränkungen weiter unten). ### Authentifizierung Beim Handshake wird der Schlüssel über den standardmäßigen HTTP-Header übergeben: ```text theme={null} Authorization: Bearer $AIHUBMIX_API_KEY ``` ### Anforderungen an das Audioformat Derzeit wird nur ein Eingabeformat unterstützt. Konvertieren Sie das Audio vor dem Senden in: * **Kodierung**: PCM16 (16-Bit-Ganzzahl mit Vorzeichen, Little-Endian) * **Abtastrate**: 24000 Hz * **Kanal**: Mono Also `audio/pcm@24000`. Das Senden eines anderen Formats (z. B. G.711/µ-law) wird abgelehnt und die Sitzung geschlossen. **Transkriptionssitzungen unterstützen keine Sprachaktivitätserkennung (turn\_detection / VAD)**, sie muss explizit auf `null` gesetzt werden. Wenn Sie das Feld weglassen oder einen anderen Wert als `null` übergeben, lehnt der Modellanbieter die Transkription mit `invalid_value` ab. Das Gateway erzwingt für die weitergeleitete Konfiguration `turn_detection` auf `null`, es wird jedoch empfohlen, dass Sie es auch clientseitig aktiv auf `null` setzen, um das Verhalten klar zu halten. ## Sitzungskonfiguration (session.update) Nach dem Verbindungsaufbau sendet der Client zunächst einen `session.update`-Frame, um die Transkriptionsparameter zu konfigurieren. Wenn Sie ihn nicht senden, injiziert das Gateway zur Absicherung eine Standardkonfiguration mit dem autorisierten Modell, eine explizite Konfiguration wird jedoch empfohlen. ```json theme={null} { "type": "session.update", "session": { "type": "transcription", "audio": { "input": { "format": { "type": "audio/pcm", "rate": 24000 }, "transcription": { "model": "gpt-live-transcribe", "languages": ["en", "zh"], "prompt": "会议录音，含产品名与英文缩写", "keywords": ["AiHubMix", "gpt-live-transcribe"], "delay": "low" }, "turn_detection": null, "noise_reduction": { "type": "near_field" } } } } } ``` ### Konfigurationsparameter Sitzungstyp, im Transkriptionsszenario fest auf `transcription` gesetzt. Eingabe-Audioformat, fest auf `{ "type": "audio/pcm", "rate": 24000 }` gesetzt. Transkriptionsmodell. Muss mit dem `model` der Verbindungs-URL übereinstimmen (`gpt-live-transcribe`). Die Übergabe eines anderen Modells gilt als unbefugt, und die Sitzung wird mit `1008` geschlossen. Liste der erwarteten Sprachen in Array-Form (z. B. `["en", "zh"]`). `gpt-live-transcribe` verwendet den **Plural** `languages`, sodass mehrere Sprachen auf einmal deklariert werden können; die Angabe von Sprachen erhöht die Genauigkeit und senkt die Latenz. Das Wertelexikon finden Sie unter [Sprachcodes](#sprachcodes-language-codes) weiter unten. Singular-Schreibweise, ein einzelner ISO-639-1-Code (z. B. `"en"`). Verwenden Sie entweder dies oder `languages`, **übergeben Sie nicht beides gleichzeitig** (das gleichzeitige Übergeben wird mit `invalid_value` abgelehnt). Offiziell wird für `gpt-live-transcribe` der Plural `languages` empfohlen; das Gateway akzeptiert auch den Singular `language`, was die Migration von altem Code erleichtert. Freitext-Prompt, der das Aufnahmeszenario beschreibt (z. B. „Kundenservice-Anruf", „Sprechstunde mit medizinischen Fachbegriffen") und dem Modell hilft, sich dem Sprachregister anzupassen. In der Praxis gibt der Server ihn in `session.updated` unverändert zurück, er ist also wirksam. Array von wörtlichen Hinweiswörtern für fehleranfällige Begriffe wie Produktnamen, Abkürzungen und Eigennamen (z. B. `["AiHubMix", "gpt-live-transcribe"]`). Es handelt sich um einen **Hinweis** und keine erzwungene Ausgabe; jedes Wort steht als eigener Eintrag, und `<`, `>` sowie Zeilenumbrüche sollten vermieden werden. In der Praxis wird es zurückgegeben und ist wirksam. Latenz-/Genauigkeitsstufe, mögliche Werte `minimal`, `low`, `medium`, `high`, `xhigh`: je höher die Stufe, desto genauer, aber desto höher die Latenz. **Hinweis**: Das Gateway akzeptiert das Feld (ohne Fehler), gibt es in der Praxis jedoch nicht in `session.updated` zurück; die Wirksamkeit richtet sich nach der offiziellen Dokumentation und ist bisher nicht durch die Rückmeldung bestätigt. Sprachaktivitätserkennung. Bei Transkriptionssitzungen muss sie `null` sein. Optionale Rauschunterdrückungskonfiguration, z. B. `{ "type": "near_field" }` (Nahfeld, geeignet, wenn sich das Mikrofon nah am Sprecher befindet) oder `{ "type": "far_field" }` (Fernfeld). ### Sprachcodes (language codes) Die Werte von `languages` / `language` folgen dem nachstehenden Format, sind **groß-/kleinschreibungssensitiv und müssen einer der unten unterstützten Formen entsprechen**; das Übergeben nicht unterstützter oder falsch formatierter Codes wird von der Realtime-API abgelehnt: | Kategorie | Beispiel | Erläuterung | | -------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------- | | ISO 639-1 (zweistellig) | `en`, `zh`, `es`, `fr`, `ja` | am gebräuchlichsten, ein zweistelliger Code pro Sprache | | Teil von ISO 639-3 (dreistellig) | `eng`, `spa`, `yue`, `cmn` | dient der Unterscheidung von Dialekten, z. B. `yue`=Kantonesisch, `cmn`=Hochchinesisch | | Regionalisiertes Chinesisch | `zh-cn`, `zh-tw`, `zh-hk` | Sprache + Region, unterscheidet Kurz-/Langzeichen und Wortgebrauch in Hongkong/Taiwan | Wenn Sie den Plural `languages` verwenden, setzen Sie die am wahrscheinlichsten auftretende Sprache an den Anfang. Für gemischtsprachige Szenarien (z. B. chinesisch-englisch gemischt) können Sie `["zh", "en"]` schreiben; für eine einzelne Sprache genügt `["en"]`, was genauer und schneller ist als keine Angabe. ## Audio senden Zerlegen Sie das PCM16-Audio in kleine Segmente (z. B. je 100ms), kodieren Sie sie in base64 und senden Sie sie fortlaufend über das Ereignis `input_audio_buffer.append`: ```json theme={null} { "type": "input_audio_buffer.append", "audio": "" } ``` Da die Transkriptionssitzung kein VAD (Sprachaktivitätserkennung) aktiviert, erkennt der Server nicht automatisch, wann ein Redeabschnitt endet. Nachdem Sie ein Audiosegment gesendet haben, müssen Sie **manuell** einen `input_audio_buffer.commit`-Frame senden, um das Ende dieses Segments zu markieren, den Abschluss der Transkription auszulösen und das `completed`-Ergebnis zurückzugeben: ```json theme={null} { "type": "input_audio_buffer.commit" } ``` ## Transkriptionsergebnisse empfangen Der Server sendet fortlaufend Ereignisse; die wichtigsten Ereignistypen: Bestätigung der Sitzungserstellung bzw. der Konfigurationsaktualisierung. **Inkrementelles** Transkriptionsergebnis, das Feld `delta` ist das neu hinzugekommene Textsegment. Wird während des Sprechens zurückgegeben, geeignet für die Echtzeitanzeige. Ein Sprachabschnitt ist **fertig** transkribiert, das Feld `transcript` ist der vollständige Text dieses Abschnitts. Fehlerereignis, enthält Fehlercode und Beschreibung. ## Vollständiges Beispiel Nachfolgend werden zwei Schreibweisen gezeigt, wählen Sie eine davon: * **Offizielles OpenAI SDK (empfohlen)**: Kein manuelles Schreiben von WebSocket erforderlich, richten Sie einfach `websocket_base_url` (der WebSocket-Basisadressparameter des SDK) auf das Gateway aus, um die offizielle Bibliothek weiterzuverwenden. * **Natives websockets**: Ohne SDK-Installation direkt Frames gemäß Protokoll senden und empfangen, mit minimalen Abhängigkeiten und einfacher Fehlersuche. **Warum übergibt das offizielle Demo den Modellnamen nicht, wir aber schon?** Der Transkriptions-Intent von OpenAI legt das Modell in `transcription.model` von `session.update` ab, die Verbindungs-URL trägt nur `?intent=transcription`. Beim AiHubMix-Gateway ist es anders: Der Modellname **muss** in der Handshake-URL erscheinen (`?model=gpt-live-transcribe`), denn das Gateway benötigt ihn genau im Moment des WebSocket-Handshakes, um den **Modellanbieter auszuwählen, zu authentifizieren und das Kontingent zu reservieren**, während `session.update` erst nach Abschluss des Handshakes eintrifft und dafür zu spät kommt. Deshalb müssen Sie bei Verwendung des SDK dem `connect()` explizit `model` übergeben (das SDK hängt es an die URL-Query an); fehlt es, antwortet das Gateway **bereits während des Handshakes mit `400 missing_model_parameter`**: `connect()` wirft direkt eine Exception, die Verbindung kommt gar nicht zustande und der Schritt `session.update` wird nie erreicht. Innerhalb der Sitzung muss `transcription.model` weiterhin mit der URL übereinstimmen. ```python Python (OpenAI SDK) theme={null} # Abhängigkeit: pip install "openai[realtime]" import asyncio import base64 from openai import AsyncOpenAI # Zur Wiederverwendung des offiziellen SDK sind nur drei Anpassungen nötig: # 1) websocket_base_url auf das AiHubMix-Gateway richten (statt auf die OpenAI-Standardadresse) # 2) connect() explizit model übergeben (siehe Note oben), für den Gateway-Handshake erforderlich # 3) extra_query mit intent=transcription versehen client = AsyncOpenAI( api_key="sk-***", # durch Ihren AiHubMix-API-Schlüssel ersetzen websocket_base_url="wss://aihubmix.com/v1", ) async def main(): async with client.realtime.connect( model="gpt-live-transcribe", # Pflicht: landet in der Handshake-URL, das Gateway wählt darüber die Route und rechnet ab extra_query={"intent": "transcription"}, ) as conn: # 1) Transkriptionssitzung konfigurieren await conn.session.update(session={ "type": "transcription", "audio": {"input": { "format": {"type": "audio/pcm", "rate": 24000}, "transcription": { "model": "gpt-live-transcribe", "languages": ["en", "zh"], "prompt": "会议录音,含产品名与英文缩写", "keywords": ["AiHubMix", "gpt-live-transcribe"], }, "turn_detection": None, "noise_reduction": {"type": "near_field"}, }}, }) # 2) Lokales rohes PCM16-/24kHz-/Mono-Audio lesen und in Blöcken senden async def send_audio(): with open("audio_pcm16_24k.raw", "rb") as f: pcm = f.read() chunk = 24000 * 2 // 10 # 100ms = Abtastrate × 2 Byte ÷ 10 for i in range(0, len(pcm), chunk): await conn.input_audio_buffer.append( audio=base64.b64encode(pcm[i:i + chunk]).decode() ) await asyncio.sleep(0.1) # Echtzeit-Rhythmus simulieren # Kein VAD: nach dem Senden des Audios manuell commit, um den Abschluss der Transkription auszulösen await conn.input_audio_buffer.commit() asyncio.create_task(send_audio()) # 3) Transkriptionsergebnisse empfangen async for evt in conn: etype = getattr(evt, "type", "") if etype.endswith("transcription.delta"): print(getattr(evt, "delta", ""), end="", flush=True) elif etype.endswith("transcription.completed"): print("\n[完成]", getattr(evt, "transcript", "")) break # nach Erhalt des vollständigen Ergebnisses beenden elif etype == "error": print("\n[错误]", evt.to_dict()) break asyncio.run(main()) ``` ```python Python (websockets) theme={null} import asyncio import base64 import json import websockets API_KEY = "sk-***" # durch Ihren AiHubMix-API-Schlüssel ersetzen URL = ( "wss://aihubmix.com/v1/realtime" "?intent=transcription&model=gpt-live-transcribe" ) async def main(): # websockets >= 13 verwendet additional_headers; ältere Versionen verwenden extra_headers async with websockets.connect( URL, additional_headers={"Authorization": f"Bearer {API_KEY}"} ) as ws: # 1) Transkriptionssitzung konfigurieren await ws.send(json.dumps({ "type": "session.update", "session": { "type": "transcription", "audio": {"input": { "format": {"type": "audio/pcm", "rate": 24000}, "transcription": {"model": "gpt-live-transcribe", "language": "en"}, "turn_detection": None, "noise_reduction": {"type": "near_field"}, }}, }, })) # 2) Lokales rohes PCM16-/24kHz-/Mono-Audio lesen und in Blöcken senden async def send_audio(): with open("audio_pcm16_24k.raw", "rb") as f: pcm = f.read() chunk = 24000 * 2 // 10 # 100ms = Abtastrate × 2 Byte ÷ 10 for i in range(0, len(pcm), chunk): await ws.send(json.dumps({ "type": "input_audio_buffer.append", "audio": base64.b64encode(pcm[i:i + chunk]).decode(), })) await asyncio.sleep(0.1) # Echtzeit-Rhythmus simulieren # Kein VAD: nach dem Senden des Audios manuell commit, um den Abschluss der Transkription auszulösen await ws.send(json.dumps({"type": "input_audio_buffer.commit"})) asyncio.create_task(send_audio()) # 3) Transkriptionsergebnisse empfangen async for msg in ws: evt = json.loads(msg) etype = evt.get("type", "") if etype.endswith("transcription.delta"): print(evt.get("delta", ""), end="", flush=True) elif etype.endswith("transcription.completed"): print("\n[完成]", evt.get("transcript", "")) break # nach Erhalt des vollständigen Ergebnisses beenden elif etype == "error": print("\n[错误]", evt.get("error")) break asyncio.run(main()) ``` ```bash Verbindungstest (wscat) theme={null} # Mit wscat schnell Konnektivität und Authentifizierung prüfen (zuvor npm i -g wscat) wscat -c "wss://aihubmix.com/v1/realtime?intent=transcription&model=gpt-live-transcribe" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" # Nach erfolgreicher Verbindung genügt das Einfügen eines session.update-Frames zum Start (Audio muss selbst in base64 kodiert und über input_audio_buffer.append gesendet werden) ``` Um beliebiges Audio in das von dieser Schnittstelle geforderte rohe PCM-Format zu konvertieren, können Sie ffmpeg verwenden: ```bash theme={null} ffmpeg -i input.mp3 -f s16le -acodec pcm_s16le -ac 1 -ar 24000 audio_pcm16_24k.raw ``` ## Laufverhalten (produktiv getestet) Nachfolgend die tatsächlichen Laufergebnisse des obigen Beispiels in der Produktivumgebung `aihubmix.com` (Modell `gpt-live-transcribe`). Konfiguriert wurden `languages: ["en", "zh"]` + `prompt` + `keywords` + `delay: "low"` + `noise_reduction: { "type": "near_field" }`: ```text theme={null} # 1) Bestätigung durch die Server-Rückgabe (session.updated): languages / prompt / keywords / noise_reduction werden alle unverändert zurückgegeben session.updated session.audio.input.transcription = { "model": "gpt-live-transcribe", "language": null, "languages": ["en", "zh"], "keywords": ["AiHubMix", "gpt-live-transcribe"], "prompt": "Product demo recording, contains the brand name AiHubMix." } noise_reduction = { "type": "near_field" } turn_detection = null # Hinweis: Das in der Anfrage übergebene Feld delay erscheint nicht in der Rückgabe # 2) Nachdem das Audio (PCM16 / 24 kHz / mono) blockweise gesendet und committet wurde, wird die Transkription Wort für Wort inkrementell zurückgegeben (delta), am Ende folgt der vollständige Text (completed) Hello, this is a real-time transcription test for AIHubMix. The weather is really nice today [abgeschlossen] Hello, this is a real-time transcription test for AIHubMix. The weather is really nice today ``` In der Praxis wurden `languages`, `prompt`, `keywords` und `noise_reduction` vom Server allesamt in `session.updated` unverändert zurückgegeben, was zeigt, dass die Konfiguration tatsächlich wirksam ist (nicht nur akzeptiert, aber unverarbeitet). Das Feld `delay` wird vom Gateway akzeptiert, aber nicht zurückgegeben; die Wirksamkeit richtet sich nach der offiziellen Dokumentation. Von `language` (Singular) und `languages` (Plural) darf nur eines übergeben werden. ## Abrechnungshinweise * **Stückpreis**: `gpt-live-transcribe` wird mit **\$0.017 / Minute** abgerechnet (maßgeblich ist der aktuelle Listenpreis auf der [Modell-Detailseite](https://aihubmix.com/model/gpt-live-transcribe)). * Die Abrechnung erfolgt nach der **transkribierten Audiodauer**: maßgeblich sind die tatsächlich an das Transkriptionsmodell weitergeleiteten Audiosekunden, aufgerundet auf ganze Sekunden. Beispiel: Bei der Transkription von 90 Sekunden Audio werden `90 ÷ 60 × $0.017 = $0.0255` berechnet. * Die Abrechnung wird nicht durch Netzwerk-Roundtrips oder Leerlaufzeiten beeinflusst, sondern misst nur das tatsächlich zur Transkription zugeführte Audio. * **Laufende Abrechnung**: Dies ist eine dauerhafte Verbindung, die Kosten werden nicht erst am Ende der Sitzung auf einmal abgerechnet, sondern **während der Sitzung segmentweise in Echtzeit abgezogen**. Beim Aufbau der Sitzung wird zunächst eine **Kontingentreservierung** in Höhe von etwa 1 Minute Verbrauch vorgenommen (nur als Zugangsprüfung, kein tatsächlicher Abzug); während der Sitzung wird die Reservierung alle 20 Sekunden rollierend verlängert, die tatsächlichen Kosten werden segmentweise nach den real weitergeleiteten Sekunden abgezogen, und nach Sitzungsende wird die verbleibende Reservierung freigegeben. **Daher muss das verfügbare Guthaben des Kontos für mindestens etwa 1 Minute Verbrauch ausreichen, damit die Sitzung aufgebaut werden kann.** * In den Verbrauchsdetails unter [Nutzung und Abrechnung](https://aihubmix.com) weist die **Anmerkung** jedes Echtzeittranskriptions-Eintrags den „Stückpreis pro Minute" und die „diesmal berechneten Sekunden" aus, was die einzelne Abstimmung erleichtert. Abrechnungseintrag einer gpt-live-transcribe-Echtzeittranskription in der Activity-Ansicht von Nutzung und Abrechnung, mit einer Anmerkung, die 7 s Audio zu $0.017 pro Minute ausweist ## Einschränkungen und Auflagen 1. **Dauer einer einzelnen Sitzung**: Eine WebSocket-Verbindung dauert maximal **62 Minuten**, danach schließt der Server sie aktiv; wenn Sie länger benötigen, teilen Sie die Verbindung auf und verbinden sich erneut. 2. **Unzureichendes Guthaben**: Es gibt zwei Fälle. **Beim Aufbau der Sitzung**: Reicht das verfügbare Guthaben nicht aus, um die Reservierung von etwa 1 Minute abzudecken, wird der Handshake direkt abgelehnt (HTTP 403), und die Sitzung kommt nicht zustande. **Während der laufenden Sitzung**: Wird das Guthaben aufgebraucht (festgestellt bei der Verlängerungsprüfung alle 20 Sekunden oder bei der Nachprüfung nach segmentweisem Abzug), wird die bereits aufgebaute Verbindung sofort geschlossen. 3. **Nur serverseitig**: Direkte Browser-Verbindungen werden nicht unterstützt (der `Origin`-Header wird geprüft), bitte serverseitig integrieren. 4. **Modellsperre**: Das Modell wird in der Verbindungs-URL fest vorgegeben; der Versuch, das Modell während der Sitzung über `session.update` zu ändern, wird abgelehnt und die Sitzung geschlossen. 5. **Formatsperre**: Es wird nur `audio/pcm@24000` in Mono unterstützt, andere Formate werden abgelehnt. ## Häufige Fehler | Szenario | Schließcode / Status | Erläuterung | | ---------------------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------- | | Dienst nicht aktiviert | HTTP 403 `realtime_disabled` | Echtzeittranskription ist für diese Umgebung nicht freigegeben | | `Origin`-Header vorhanden / Browser-Direktverbindung | Handshake abgelehnt | auf serverseitige Verbindung umstellen | | Modelländerung während der Sitzung | `1008` `model_override_forbidden` | Das Modell kann nur in der Verbindungs-URL angegeben werden | | Audioformat nicht PCM | `1008` `audio_format_unsupported` | in `audio/pcm@24000` konvertieren | | Unzureichendes Guthaben beim Verbindungsaufbau | HTTP 403 `insufficient_user_quota` | Guthaben reicht nicht aus, um etwa 1 Minute Verbrauch zu reservieren; nach dem Aufladen erneut versuchen | | Guthaben während der Sitzung aufgebraucht | Verbindung wird geschlossen | nach dem Aufladen erneut verbinden | *** Zuletzt aktualisiert: 2026-09-16