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
| Bedarf | Endpunkt | Verwendung, wenn |
|---|---|---|
| Text-to-Speech | POST /v1/audio/speech | Sie eine Audiodatei aus Text benötigen. |
| Transkription | POST /v1/audio/transcriptions | Sie Text aus einer Audiodatei benötigen. |
| Audio-Übersetzung | POST /v1/audio/translations | Sie übersetzten Text aus einer Audiodatei benötigen. |
| Realtime-WebSocket | WS /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.mp3Realtime-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 wsimport 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
| Thema | Referenz |
|---|---|
| Sprache erstellen | Sprache erstellen |
| Transkription erstellen | Transkription erstellen |
| Übersetzung erstellen | Übersetzung erstellen |
| Realtime-WebSocket | Realtime-WebSocket |
| Modelle auflisten | Modelle auflisten |
| Abrechnung & Preise | Abrechnung & Preise |