Panduan media

Audio dan realtime

Buat ucapan, transkripsikan audio, terjemahkan ucapan, atau buka sesi realtime

Gunakan endpoint audio jika hasilnya berupa file atau teks. Gunakan endpoint WebSocket realtime untuk pengalaman audio dua arah secara langsung.

Pilih endpoint

KebutuhanEndpointGunakan saat
Text to speechPOST /v1/audio/speechAnda memerlukan file audio dari teks.
TranskripsiPOST /v1/audio/transcriptionsAnda memerlukan teks dari file audio.
Terjemahan audioPOST /v1/audio/translationsAnda memerlukan teks terjemahan dari file audio.
Realtime WebSocketWS /v1/realtime?model={model}Anda memerlukan streaming audio dua arah melalui WebSocket. GET /v1/realtime biasa hanya mengembalikan metadata.

Pilih model

Baca daftar model saat ini alih-alih melakukan hard-coding. Periksa detail model yang dipilih untuk dukungan realtime sebelum membuka socket.

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"

Permintaan audio

Speech mengembalikan audio dalam respons HTTP. Transkripsi dan terjemahan dapat mengembalikan teks akhir atau tugas yang diterima. Jika body berisi ID tugas dan status alih-alih teks akhir, simpan ID tersebut dan lakukan polling pada GET /v1/tasks/{id} hingga selesai atau gagal. Berikan waktu yang cukup untuk file besar dan simpan Request ID.

URL hasil audio adalah URL media-result TokenLab yang tetap valid selama 30 hari. media_retention.items melaporkan status penyimpanan setiap item dan expires_at; respons dapat menghilangkan media_retention jika status penyimpanan tidak diketahui tepat waktu, dan URL tersebut tetap berfungsi. Respons audio inline atau biner berada di luar retensi salinan URL ini. Lihat Retensi data.

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

Sesi Realtime

Buka WebSocket dengan model di query string dan API key di header Authorization. Simpan format event yang didokumentasikan untuk model realtime yang dipilih, dan tutup socket saat sesi selesai.

Sesi berlangsung paling lama 1 jam. Setelah itu, server akan menutup socket dengan kode 1000 dan alasan session_timeout. Satu pesan dapat berukuran hingga 32 MiB; pesan yang lebih besar akan menutup socket dengan kode 1009. Beberapa model realtime, seperti grok-voice-think-fast-2.0, hanya menerima frame audio dan pembaruan sesi. Item input teks akan mengembalikan error unsupported_realtime_text_input dan menutup socket dengan kode 1008.

Panduan ini hanya mencakup subset WebSocket. TokenLab saat ini tidak menyediakan OpenAI Realtime REST client secret, translation client secret, Calls, atau endpoint manajemen sesi beta lama.

Untuk contoh sisi server di bawah, instal ws dan atur TOKENLAB_REALTIME_MODEL ke model saat ini yang detailnya menyatakan /v1/realtime. Sediakan TOKENLAB_API_KEY di lingkungan server; nama tersebut saja tidak menetapkan dukungan realtime.

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'));

Tampilkan progres dengan aman

  • Simpan file audio yang dihasilkan alih-alih memutar ulang permintaan yang sama saat refresh.
  • Untuk transkripsi dan terjemahan, tampilkan status unggah dan pemrosesan meskipun panggilan API bersifat sinkron.
  • Untuk realtime, tangani event penutupan dan lakukan koneksi ulang hanya setelah pengguna memulai sesi baru.
  • Jangan masukkan API key, URL pribadi, atau rahasia akun ke dalam input teks audio.

Referensi API

TopikReferensi
Create SpeechBuat Speech
Create TranscriptionBuat Transkripsi
Create TranslationBuat Terjemahan
Realtime WebSocketWebSocket Realtime
List ModelsList Models
Billing & PricingBilling & Pricing

Di halaman ini