媒體指南
音訊與即時通訊
建立語音、轉錄音訊、翻譯語音或開啟即時對話連線
當結果為檔案或文字時,請使用音訊端點。若需要即時、雙向的音訊體驗,請使用即時 WebSocket 端點。
選擇端點
| 需求 | 端點 | 使用時機 |
|---|---|---|
| 文字轉語音 | POST /v1/audio/speech | 您需要將文字轉換為音訊檔案。 |
| 轉錄 | POST /v1/audio/transcriptions | 您需要將音訊檔案轉換為文字。 |
| 音訊翻譯 | POST /v1/audio/translations | 您需要將音訊檔案翻譯為文字。 |
| 即時 WebSocket | WS /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 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'));安全地顯示進度
- 儲存生成的音訊檔案,而非在重新整理時重複執行相同的請求。
- 對於轉錄與翻譯,即使 API 呼叫是同步的,也應顯示上傳與處理狀態。
- 對於即時對話,請處理關閉事件,並僅在使用者開始新對話時才重新連線。
- 請勿將 API 金鑰、私人 URL 或帳戶密鑰放入音訊文字輸入中。