TokenLab

媒體指南

音訊與即時通訊

建立語音、轉錄音訊、翻譯語音或開啟即時對話連線

當結果為檔案或文字時,請使用音訊端點。若需要即時、雙向的音訊體驗,請使用即時 WebSocket 端點。

選擇端點

需求端點使用時機
文字轉語音POST /v1/audio/speech您需要將文字轉換為音訊檔案。
轉錄POST /v1/audio/transcriptions您需要將音訊檔案轉換為文字。
音訊翻譯POST /v1/audio/translations您需要將音訊檔案翻譯為文字。
即時 WebSocketWS /v1/realtime?model={model}您需要透過 WebSocket 進行雙向串流音訊。單純的 GET /v1/realtime 僅會回傳中繼資料。

選擇模型

請讀取目前的模型列表,而非將其寫死在程式碼中。在開啟 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"

音訊請求

語音功能會在 HTTP 回應中回傳音訊。轉錄與翻譯功能可能會回傳最終文字或已受理的任務。當主體(body)包含任務 ID 與狀態而非最終文字時,請儲存該 ID 並輪詢 GET /v1/tasks/{id} 直到完成或失敗。請為大型檔案預留足夠的時間,並保留 Request ID。

音訊結果 URL 為 TokenLab 媒體結果 URL,有效期為 30 天。media_retention.items 會回報每個項目的儲存狀態與 expires_at;當儲存狀態無法及時得知時,回應可能會省略 media_retention,但該 URL 仍然有效。內嵌或二進位音訊回應不在 URL 複製保留範圍內。請參閱 資料保留。

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 Sessions)

使用查詢字串中的模型與 Authorization 標頭中的 API 金鑰來開啟 WebSocket。請遵循所選即時模型的文件化事件格式,並在對話結束時關閉 socket。

對話連線最長持續 1 小時。之後伺服器會以代碼 1000 與原因 session_timeout 關閉 socket。單一訊息上限為 32 MiB;若訊息過大,socket 將以代碼 1009 關閉。部分即時模型(例如 grok-voice-think-fast-2.0)僅接受音訊影格與對話更新。文字輸入項目會回傳 unsupported_realtime_text_input 錯誤並以代碼 1008 關閉 socket。

本指南僅涵蓋 WebSocket 子集。TokenLab 目前不提供 OpenAI Realtime REST 用戶端密鑰、翻譯用戶端密鑰、Calls 或舊版 beta 對話管理端點。

對於下方的伺服器端範例,請安裝 ws 並將 TOKENLAB_REALTIME_MODEL 設定為詳細資訊中宣告 /v1/realtime 的當前模型。請在伺服器環境中提供 TOKENLAB_API_KEY;僅憑名稱無法建立即時支援。

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

安全地顯示進度

  • 儲存生成的音訊檔案,而非在重新整理時重複執行相同的請求。
  • 對於轉錄與翻譯,即使 API 呼叫是同步的,也應顯示上傳與處理狀態。
  • 對於即時對話,請處理關閉事件,並僅在使用者開始新對話時才重新連線。
  • 請勿將 API 金鑰、私人 URL 或帳戶密鑰放入音訊文字輸入中。

API 參考

主題參考
建立語音 (Create Speech)建立語音
建立轉錄 (Create Transcription)建立轉錄
建立翻譯 (Create Translation)建立翻譯
即時 WebSocket即時 WebSocket
列出模型列出模型
帳務與定價帳務與定價

本頁內容