媒體指南
音訊與即時
為音訊應用選擇語音、轉寫、翻譯或即時 WebSocket 流程。
音訊工作負載分成兩類。文字轉語音、轉寫、音訊翻譯這類檔案式請求使用音訊端點；需要低延遲互動音訊或多模態事件時，使用即時 WebSocket 端點。
選擇流程
| 流程 | 端點 | 適用場景 |
|---|---|---|
| 文字轉語音 | POST /v1/audio/speech | 需要從文字生成音訊檔案。 |
| 轉寫 | POST /v1/audio/transcriptions | 需要從音訊檔案得到文字。 |
| 音訊翻譯 | POST /v1/audio/translations | 需要從音訊檔案得到翻譯後的文字。 |
| Realtime 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 回應中傳回音訊。轉寫與翻譯可能傳回最終文字，也可能傳回已受理的任務。若回應含任務 ID 與狀態而非最終文字，請保存 ID 並依 poll_url 輪詢至完成或失敗。大型檔案應保留足夠逾時時間與 Request ID。
curl -X POST "https://api.tokenlab.sh/v1/audio/speech" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "tts-1-hd",
"voice": "nova",
"input": "Welcome to TokenLab."
}' \
--output speech.mp3即時會話
開啟 WebSocket 時在查詢參數中傳 model，並在 Authorization header 中傳 API key。事件格式按所選即時模型文件發送；會話結束時主動關閉 socket。
本指南只涵蓋 WebSocket 子集。TokenLab 目前不提供 OpenAI Realtime REST client secret、translation client secret、Calls 或 legacy beta session 管理端點。
執行下方伺服器端範例前，安裝 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 key、私有 URL 或帳戶密鑰放進音訊文字輸入。