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.
wss://api.starsg.ai/v1/realtime?model=asr-altair-v1-miniNeu 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.
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 ↗
python3 -m venv .venv .venv/bin/python -m pip install "openai[realtime]==3.35.1"
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 ↗
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.
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 ↗
ffmpeg -n -i recording.mp3 -ar 24000 -ac 1 -c:a pcm_s16le input.wav
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.
.venv/bin/python speech.py
Wie Erfolg aussiehtDas 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.
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.
- Erhalten
session.createdDer Server hat eine Sitzung geöffnet. Sie können nun die Konfiguration senden.
- Schicken
session.updateLegen Sie die Transkriptionssitzung, das Eingabeaudioformat, das Erkennungsmodell und die Abbiegeerkennung fest.
- Erhalten
session.updatedDer Server hat die Konfiguration akzeptiert. Senden Sie nun die Eingabe.
- Schicken
input_audio_buffer.appendSenden Sie Base64 PCM im Audiofeld. In diesem Beispiel werden 4,800-Byte-Blöcke verwendet, was 100 ms im konfigurierten Format entspricht.
- Schicken
input_audio_buffer.commitBeenden Sie die Eingaberunde. Bei turn_detection=null müssen Sie einen expliziten Commit durchführen. Senden Sie nicht „response.create“ zur Erkennung.
- Erhalten
conversation.item.input_audio_transcription.deltaDelta und text_mode lesen; Aktualisieren Sie die passenden item_id und content_index.
- Erhalten
conversation.item.input_audio_transcription.completedDas 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“.
{
"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
modelstringErforderlichErforderlicher Abfrageparameter im WebSocket URL. Verwenden Sie die genaue öffentliche Modell-ID aus dem Echtzeitkatalog. Die Modelle ASR und TTS sind nicht austauschbar.
Beispiel/Einstellungasr-altair-v1-miniAuthorizationstringErforderlichVerbindungsheader: 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/EinstellungBearer <API_KEY>
Sitzung und Input
session.typestringErforderlichVerwenden Sie die Transkription nur zur Erkennung. Es gibt Text zurück, ohne eine Sprachantwort des Assistenten zu generieren.
Beispiel/Einstellung"transcription"session.audio.input.formatobjectErforderlichAudiokonfiguration: 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.modelstringErforderlichVerwenden Sie dieselbe öffentliche Modell-ID ASR wie die URL-Abfrage. Ersetzen Sie nicht den Modellnamen des Upstream-Anbieters.
Beispiel/Einstellungasr-altair-v1-minisession.audio.input.turn_detectionobject | nullOptionalDas 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/EinstellungnullaudiostringErforderlichBase64-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 ↗