媒体指南

音频与 Realtime

生成语音、转写音频、翻译语音或建立实时会话

结果是音频文件或文字时,使用音频端点;需要双向实时语音时,使用 Realtime WebSocket。

选择端点

需要什么端点适合
文本转语音POST /v1/audio/speech需要从文本生成音频文件。
转写POST /v1/audio/transcriptions需要从音频文件得到文本。
音频翻译POST /v1/audio/translations需要从音频文件得到翻译后的文本。
Realtime WebSocketWS /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 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 密钥、私有 URL 或账户密钥放进音频文本输入。

API 参考

主题参考
创建语音创建语音
创建转写创建转写
创建翻译创建翻译
实时 WebSocket实时 WebSocket
列出模型列出模型
计费与价格计费与价格

本页内容