V3 时间戳对齐

让文字跟上声音

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

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

请求与读取

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

响应字段

{
  "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 导出或任意上传音频的转写接口。