媒体指南
音频与 Realtime
生成语音、转写音频、翻译语音或建立实时会话
结果是音频文件或文字时,使用音频端点;需要双向实时语音时,使用 Realtime 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 前,请在所选模型的详情中确认是否支持 Realtime。
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,并调用 GET /v1/tasks/{id} 轮询至完成或失败。大文件应留足等待时间,并保留请求 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实时会话
打开 WebSocket 时,在查询参数中填写 model,在 Authorization 请求头中填写 API 密钥。请保持所选实时模型文档中的事件格式;会话结束时主动关闭 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 client secret、translation client secret、Calls 或旧版 beta session 管理 API。
运行下方服务器端示例前,安装 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 密钥、私有 URL 或账户密钥放进音频文本输入。