错误码与限制
错误码、重试策略、请求频率限制与幂等键。
错误响应
{
"code": -1,
"message": "Voice not found",
"data": {
"error_code": "NOT_FOUND",
"retryable": false,
"request_id": "0b5e2f1a-…",
"voice_id": "…"
}
}error_code：稳定的错误码，请据此处理错误。retryable：为true时可以稍后用相同请求重试(建议指数退避)；为false时需要修改请求或账户状态后再试。request_id：本次请求的 ID，也在响应头X-Request-Id中，联系支持时请提供。- 其他字段为该错误的补充信息，例如
field(出错的参数)、index(批量中出错的条目)、required/available(所需与可用积分)。
错误码
| HTTP | error_code | 可重试 | 说明与处理 |
|---|---|---|---|
| 400 | INVALID_REQUEST | 否 | 参数缺失或不合法，见 field |
| 400 | CONSENT_REQUIRED | 否 | 克隆声音时未传 consent=true |
| 400 | SAMPLE_QUALITY_FAILED | 否 | 克隆样本未通过质量检查，见 issues |
| 400 | CONTENT_REJECTED | 否 | 输入内容未通过安全审核 |
| 401 | UNAUTHORIZED | 否 | 缺少 API 密钥，或密钥无效、已删除 |
| 402 | INSUFFICIENT_CREDITS | 否 | 积分不足，见 required 和 available，购买积分后重试 |
| 403 | API_ACCESS_REQUIRED | 否 | 当前套餐不含 API，请升级到标准版或以上 |
| 403 | UPGRADE_REQUIRED | 否 | 超出套餐限制(字数、文件大小、时长)，见 max_allowed 等字段 |
| 403 | VOICE_LIMIT_REACHED | 否 | 声音名额已满，删除不用的声音或升级套餐 |
| 404 | NOT_FOUND | 否 | 资源不存在或不属于你 |
| 409 | VOICE_NOT_READY | 否 | 声音尚未可用(voice_status 为当前状态) |
| 409 | IDEMPOTENCY_KEY_REUSED | 否 | 同一个幂等键用于了不同的请求 |
| 409 | IDEMPOTENCY_IN_PROGRESS | 是 | 使用同一幂等键的上一个请求仍在处理 |
| 413 | FILE_TOO_LARGE | 否 | 上传文件超过 30MB |
| 415 | UNSUPPORTED_AUDIO_FORMAT | 否 | 只支持 WAV、MP3、OGG、WEBM、M4A |
| 429 | RATE_LIMITED | 是 | 请求过于频繁，按 Retry-After 秒数等待后重试 |
| 500 | INTERNAL_ERROR | 是 | 服务器内部错误，稍后重试 |
| 503 | SYSTEM_BUSY | 是 | 系统繁忙，稍后重试 |
任务本身失败(而不是创建请求失败)时，任务对象的 error.code 为 SYNTHESIS_FAILED，已扣积分会自动退还，可以重新创建任务。
请求频率限制
按账号计算，同一账号的所有密钥共用额度：
| 套餐 | 每分钟请求数 |
|---|---|
| 标准版 | 60 |
| 高级版 | 120 |
每个响应都带有以下响应头：
| 响应头 | 说明 |
|---|---|
X-RateLimit-Limit | 每分钟上限 |
X-RateLimit-Remaining | 当前窗口剩余次数 |
X-RateLimit-Reset | 当前窗口重置时间(Unix 秒) |
Retry-After | 被限流时需要等待的秒数 |
此外，同时生成中的任务数受套餐并发上限限制(标准版 5 个、高级版 10 个)。超出的任务会自动排队，不会报错。
需要更高的限额请联系 [email protected]。
其他限制
| 项目 | 限制 |
|---|---|
| 单次文字转语音字数 | 按套餐，标准版及以上为 1,000 字 |
| 单次批量条数 | 100 条 |
| 上传文件大小 | 30MB，并受套餐上限约束 |
| 声音转换时长 | 5 分钟 |
| 列表每页条数 | 100(公共声音 50) |
具体数值以 GET /account 返回的 limits 为准。
幂等键
网络超时后重试创建请求，可能导致重复创建和重复扣费。为所有创建类请求(POST /tts、POST /tts/batches、POST /voice-conversion、POST /voices)加上 Idempotency-Key 请求头即可避免：
curl https://voiceailabs.com/api/v1/tts \
-H "Authorization: Bearer $VAL_API_KEY" \
-H "Idempotency-Key: 4f9a1c2e-order-1024" \
-H "Content-Type: application/json" \
-d '{"voice_id": "VOICE_ID", "text": "你好"}'- 幂等键为 1–255 个可见 ASCII 字符，建议使用 UUID 或你系统中的业务 ID。
- 24 小时内，用同一个键重复发送相同的请求，会直接返回第一次的结果(响应头
Idempotent-Replayed: true)，不会再次创建和扣费。 - 同一个键用于不同的请求内容时返回
IDEMPOTENCY_KEY_REUSED。 - 只有成功的请求会被记录。请求失败(如积分不足)后，可以用同一个键修正后重试。
- 如果持续收到
IDEMPOTENCY_IN_PROGRESS超过 1 分钟，请用GET /syntheses确认任务是否已创建，再决定是否换一个新键重试。