Medienleitfäden

Audio und Realtime

Erstellen Sie Sprache, transkribieren Sie Audio, übersetzen Sie Sprache oder öffnen Sie eine Realtime-Sitzung

Verwenden Sie die Audio-Endpunkte, wenn das Ergebnis eine Datei oder Text ist. Verwenden Sie den Realtime-WebSocket-Endpunkt für ein direktes, bidirektionales Audioerlebnis.

Wählen Sie einen Endpunkt

BedarfEndpunktVerwendung, wenn
Text-to-SpeechPOST /v1/audio/speechSie eine Audiodatei aus Text benötigen.
TranskriptionPOST /v1/audio/transcriptionsSie Text aus einer Audiodatei benötigen.
Audio-ÜbersetzungPOST /v1/audio/translationsSie übersetzten Text aus einer Audiodatei benötigen.
Realtime-WebSocketWS /v1/realtime?model={model}Sie bidirektionales Streaming-Audio über WebSocket benötigen. Ein einfaches GET /v1/realtime gibt nur Metadaten zurück.

Wählen Sie ein Modell

Lesen Sie die aktuelle Modellliste, anstatt sie fest zu kodieren. Überprüfen Sie die Details des ausgewählten Modells auf Realtime-Unterstützung, bevor Sie einen Socket öffnen.

curl "https://api.tokenlab.sh/v1/models?recommended_for=tts" \
  -H "Authorization: Bearer sk-your-api-key"

curl "https://api.tokenlab.sh/v1/models?recommended_for=stt" \
  -H "Authorization: Bearer sk-your-api-key"

Audio-Anfragen

Speech gibt Audio in der HTTP-Antwort zurück. Transkription und Übersetzung können entweder den finalen Text oder eine akzeptierte Aufgabe zurückgeben. Wenn der Body eine Aufgaben-ID und einen Status anstelle des finalen Textes enthält, speichern Sie die ID und fragen Sie GET /v1/tasks/{id} ab, bis die Aufgabe abgeschlossen oder fehlgeschlagen ist. Planen Sie für große Dateien genügend Zeit ein und behalten Sie die Request ID bei.

Audio-Ergebnis-URLs sind TokenLab-Medien-Ergebnis-URLs, die 30 Tage lang gültig bleiben. media_retention.items meldet den Speicherstatus und expires_at jedes Elements; die Antwort kann media_retention weglassen, wenn der Speicherstatus nicht rechtzeitig bekannt ist, wobei die URL weiterhin funktioniert. Inline- oder binäre Audioantworten fallen nicht unter diese URL-Kopien-Aufbewahrung. Siehe Datenaufbewahrung.

curl -X POST "https://api.tokenlab.sh/v1/audio/speech" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-tts",
    "voice": "eve",
    "input": "Welcome to TokenLab."
  }' \
  --output speech.mp3

Realtime-Sitzungen

Öffnen Sie einen WebSocket mit dem Modell im Query-String und dem API-Key im Authorization-Header. Halten Sie das Ereignisformat für das ausgewählte Realtime-Modell ein und schließen Sie den Socket, wenn die Sitzung beendet ist.

Eine Sitzung dauert maximal 1 Stunde. Danach schließt der Server den Socket mit dem Code 1000 und dem Grund session_timeout. Eine einzelne Nachricht kann bis zu 32 MiB groß sein; eine größere Nachricht schließt den Socket mit dem Code 1009. Einige Realtime-Modelle, wie z. B. grok-voice-think-fast-2.0, akzeptieren nur Audio-Frames und Sitzungsaktualisierungen. Ein Texteingabeelement gibt den Fehler unsupported_realtime_text_input zurück und schließt den Socket mit dem Code 1008.

Dieser Leitfaden behandelt nur die WebSocket-Teilmenge. TokenLab stellt derzeit keine OpenAI Realtime REST-Client-Geheimnisse, Übersetzungs-Client-Geheimnisse, Anrufe oder Legacy-Beta-Sitzungsverwaltungs-Endpunkte bereit.

Für das folgende serverseitige Beispiel installieren Sie ws und setzen Sie TOKENLAB_REALTIME_MODEL auf ein aktuelles Modell, dessen Details /v1/realtime deklarieren. Geben Sie TOKENLAB_API_KEY in der Serverumgebung an; der Name allein begründet keine Realtime-Unterstützung.

npm install ws
import WebSocket from 'ws';

const model = process.env.TOKENLAB_REALTIME_MODEL;
const apiKey = process.env.TOKENLAB_API_KEY;
if (!model || !apiKey) throw new Error('Set TOKENLAB_REALTIME_MODEL and TOKENLAB_API_KEY');

const url = new URL('wss://api.tokenlab.sh/v1/realtime');
url.searchParams.set('model', model);
const socket = new WebSocket(url, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
socket.on('message', (event) => console.log(event.toString()));
socket.on('error', (error) => console.error(error.message));
process.once('SIGINT', () => socket.close(1000, 'Client stopped'));

Fortschritt sicher anzeigen

  • Speichern Sie generierte Audiodateien, anstatt dieselbe Anfrage bei einer Aktualisierung erneut auszuführen.
  • Zeigen Sie bei Transkription und Übersetzung Upload- und Verarbeitungsstatus an, auch wenn der API-Aufruf synchron erfolgt.
  • Behandeln Sie bei Realtime Schließungsereignisse und stellen Sie die Verbindung erst wieder her, nachdem der Benutzer eine neue Sitzung gestartet hat.
  • Geben Sie keine API-Keys, privaten URLs oder Kontogeheimnisse in die Audio-Texteingabe ein.

API-Referenz

ThemaReferenz
Sprache erstellenSprache erstellen
Transkription erstellenTranskription erstellen
Übersetzung erstellenÜbersetzung erstellen
Realtime-WebSocketRealtime-WebSocket
Modelle auflistenModelle auflisten
Abrechnung & PreiseAbrechnung & Preise

Auf dieser Seite