文字转语音

创建任务

POST /api/v1/tts
Content-Type: application/json

curl https://voiceailabs.com/api/v1/tts \
  -H "Authorization: Bearer $VAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: article-88-paragraph-1" \
  -d '{
    "voice_id": "VOICE_ID",
    "text": "今天的天气非常好，适合出门散步。",
    "language": "zh",
    "speed": 1.1,
    "mode": "balance",
    "title": "文章 88 第 1 段"
  }'

返回 202，data 是任务对象：

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "9a3e6b1c-…",
    "object": "synthesis",
    "type": "tts",
    "status": "pending",
    "voice_id": "VOICE_ID",
    "text": "今天的天气非常好，适合出门散步。",
    "language": "zh",
    "speed": 1.1,
    "mode": "balance",
    "audio_url": null,
    "credits_used": 16,
    "batch_id": null,
    "created_at": "2026-10-09T02:00:00.000Z"
  }
}

之后用 GET /syntheses/{id} 查询结果，或通过 Webhook 接收 synthesis.completed 事件。

提示

• 长文章请先按段落或句子拆分，每段不超过单次上限，再用批量接口提交。
• 网页版中设置的发音词典会自动应用于 API 合成。
• 数字、缩写和专有名词的读法不理想时，可以把它们写成希望的读法，或加入发音词典。

批量创建

一次提交最多 100 条文字，每条生成一个独立的任务和音频，单独计费。

POST /api/v1/tts/batches

curl https://voiceailabs.com/api/v1/tts/batches \
  -H "Authorization: Bearer $VAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: game-lines-v3" \
  -d '{
    "items": [
      { "voice_id": "VOICE_A", "text": "欢迎来到新手村。", "title": "npc_001" },
      { "voice_id": "VOICE_B", "text": "小心，前面有怪物！", "title": "npc_002", "speed": 1.2 }
    ]
  }'

items 中每一条的参数与单条创建相同。

• 全部成功或全部不创建：任一条参数错误、超出字数上限或积分不足时，整批都不会创建，也不扣积分。参数错误时 data.index 指出是第几条(从 0 开始)。
• 任务按套餐的并发上限排队生成，完成顺序不保证与提交顺序一致。

返回 202 和批量对象：

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "c41f…",
    "object": "batch",
    "status": "processing",
    "total": 2,
    "counts": { "pending": 2, "processing": 0, "completed": 0, "failed": 0 },
    "credits_used": 17,
    "created_at": "2026-10-09T02:00:00.000Z",
    "items": [ /* 任务对象，顺序与提交顺序一致 */ ]
  }
}

查询批量任务

GET /api/v1/tts/batches/{id}

返回同样的批量对象。与查询单个任务一样，查询时会顺带推进未结束的任务。所有任务都完成或失败后 status 为 completed。配置了 Webhook 时，批量结束会发送一次 batch.completed 事件。

失败的条目不会自动重试，可以用相同参数重新创建(使用新的 Idempotency-Key)。