V3 时间戳对齐

让文字跟上声音

生成英文 MP3/WAV 时设置 return_timestamps: true，获取单词或实际测量词组的时间区间。排队任务也支持此选项。

时间戳仅支持英文。中文、日文及其他语言只生成音频，不使用时间戳对齐，也无需传入 return_timestamps。非英文请求若将此参数设为 true，会在生成与扣费前返回422 unsupported_timestamps。

可操作的真实示例

播放声音，文字同步跟上。

英文 · 实测时间区间0.00 s

播放录音，查看同步高亮。点击单词或词组，可跳到其实测起点。

实测词组整体高亮，静音间隔不高亮。下载 JSON ↓MP3 ↓

这是 2026 年 9 月 14 日保存的 API 结果。高亮将 audio.currentTime 与返回的实测区间比较，不按单词长度估算时间。原始输入： Every small step opens a new door. Listen, learn, and tell your own story.

JavaScript · 查找实测时间区间

const active = timestamps.status === 'aligned'
  ? timestamps.words.findIndex(({ start_time, end_time }) =>
      audio.currentTime >= start_time &&
      audio.currentTime < end_time)
  : -1;

// 静音间隔或时间戳不可用时，不高亮任何单词。
// 保留实测词组，不拆分估算；同时保留原始文本。

请求与读取

Code

# 在语音或排队请求的 JSON 中加入："return_timestamps": true
# 成功后用该请求的 ID 读取时间戳。
curl "https://voice.castreader.com/v1/requests/$REQUEST_ID/timestamps" \
  -H "Authorization: Bearer $CASTREADER_API_KEY" \
  --fail-with-body --output speech.timestamps.json

响应字段

Code

{
  "object": "speech.timestamps",
  "request_id": "req_EXAMPLE",
  "status": "aligned",
  "alignment_revision": "qwen-pcm-measured-groups-v3",
  "unit": "seconds",
  "granularity": "word_group",
  "duration_seconds": 1.6,
  "words": [
    {
      "word": "Hello from",
      "start_time": 0.1,
      "end_time": 0.8
    },
    {
      "word": "CastReader",
      "start_time": 0.9,
      "end_time": 1.4
    }
  ],
  "reason": null
}

上方为结构示例。start_time 与 end_time 的单位是秒，相对于本音频文件起点。不是字符偏移、毫秒或任务创建时间。区间有序、不重叠，静音处可能存在间隔。

granularity: word_group 表示部分相邻词无法可靠地拆开。请整体高亮这一组，不要平均分配时间来编造逐词边界。words[].word 保留对应源文字，部分边界标点可能省略，显示全文时请保留你提交的原文。

失败、保留与费用

先检查 status。aligned 表示有测量结果；unavailable 时 words 为空、粒度为 null，并提供 alignment_timeout 或 alignment_unavailable 原因。

时间戳不额外收费。若音频成功而可选对齐不可用，音频仍按正常字符费用计费。下载时间戳不重新生成，重复请求返回原有的对齐结果。

时间戳与音频共用保留期和授权。未请求时间戳返回 404，未完成返回 409，过期返回 410。删除声音或撤销授权会立即阻止访问。

多片段任务中的时间从每段音频的零点计算，sourceStart 与 sourceEnd 是字符位置，不能用作音频时间。当前没有独立句子对齐、SRT/WebVTT 导出或任意上传音频的转写接口。

查看排队任务 →