先在网站注册并验证邮箱，再到 API 密钥创建密钥。完整密钥只展示一次，应保存在自己的服务端环境变量中。请求受保护接口和读取生成文件时，使用同一账号的 Bearer 密钥。
Authorization: Bearer utts_你的密钥
Content-Type: application/json| 接口 | 鉴权要求 |
|---|---|
| 模型查询、音色查询 | 公开读取，无需密钥 |
| 提交合成 | Bearer 密钥，账号须已验证邮箱 |
| 结果查询、结果文件、余额查询 | Bearer 密钥，只能读取所属账号的数据 |
使用 HTTPS 访问正式站。提交合成时使用 Content-Type: application/json 和 UTF-8 编码的 JSON 对象，不上传音频或 SSML 文件。JSON 正文最多 100,000 字节（十进制 100 KB），按编码后的字节数计算；文稿还受所选模型的原文字符上限约束。读取接口不要求发送 JSON 正文。
| 限制 | 当前规则 | 触发后如何处理 |
|---|---|---|
| POST 请求频率 | 同账号在 /api/v1 下的 POST 请求共用固定 60 秒窗口，每窗口最多 120 次；网页与 API 共用 | 429 RATE_LIMITED；稍后使用原幂等键重试 |
| 未完成任务 | 同账号最多 3 个 queued / running 任务，网页与 API 共用 | 429 CONCURRENCY_LIMIT；查询已有任务，待空出名额后提交 |
| Edge 免费用量 | 按账号每日额度，UTC 00:00 重置 | 429 DAILY_LIMIT；等待重置，或自行选择付费模型 |
| 付费额度 | 按任务预留资源包额度 | 402 INSUFFICIENT_BALANCE；先补充有效资源包 |
频率计数发生在鉴权通过后、正文和业务校验前，因此幂等重放及后续校验失败的 POST 请求也会计数。GET、PATCH 和 DELETE 不受上述 POST 计数器限制；这不代表所有网站操作都使用同一限速规则，也不构成吞吐或完成时间承诺。读取目录不会创建任务。
当前任务查询没有单独的应用层轮询限速。完整 Python 示例每次查询结束后等待 2 秒，最多查询 120 次；这是示例设置，不是服务端要求或性能保证。长时间未完成时可以逐渐延长间隔，避免重叠查询；completed、failed、cancelled 都应停止轮询。当前接口没有 Retry-After 响应头或任务结果回调通知。
每次新的合成意图生成一个唯一的 Idempotency-Key（例如 UUID，最长 128 字符）。网络中断、响应超时或服务暂不可用时，保留原键和完全相同的请求再次提交；服务端按账号识别同一规范化请求，返回已有任务，不重复预留额度。重放成功仍返回 HTTP 202，任务可能已经进入终态。
| 场景 | 建议 |
|---|---|
| 提交超时，不知道是否入队 | 保留原文案、模型、音色、参数和幂等键，退避后重试提交 |
| 已拿到 data.id | 持续查询这个任务，不重新 POST 创建任务 |
| 409 IDEMPOTENCY_CONFLICT | 同一键对应了不同请求；恢复原请求，或为新的合成意图使用新键 |
| 任务 status=failed / cancelled | 停止轮询。修正原因后如需重新合成，使用新幂等键，重新校验并预留额度 |
| 未发送 Idempotency-Key | 服务端为每次提交生成新键，可能重复创建任务；不适合重试结果未知的请求 |
Idempotency-Key 可省略，未提供或值为空时由服务端生成新键。安全重试时请主动提供并保存非空键。幂等不会绕过当前鉴权、POST 限速、邮箱验证、模型、音色、参数及语音服务配置校验；任一步骤不通过，可能先返回错误而不是旧任务。服务端不自动切换引擎；目录或参数规则已变化时，请先核对错误与原任务状态。
{
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "有效资源包额度不足，请查看资源包或使用 Edge 免费配音"
}
}按 error.code 判断业务原因，message 用于提示和排查，不要依赖中文文案匹配。HTTP 成功提交只表示任务已受理；上游合成失败通过任务 status 和 error 返回，不会把已经返回的 202 改成错误响应。
| HTTP | error.code | 处理建议 |
|---|---|---|
| 400 | INVALID_REQUEST / INVALID_JSON / INVALID_BODY | 检查必填字段、JSON 格式及 UTF-8 编码；音色查询不能重复 model 参数，合成不能多传未声明的顶层字段 |
| 400 | MODEL_NOT_SUPPORTED / VOICE_NOT_SUPPORTED | 重新查询目录，确认 model 与 voice 的组合 |
| 400 | INVALID_PARAMETERS / VOICE_PARAMETER_NOT_SUPPORTED | 按 parameterSchema 与该音色 styles / roles 修正参数 |
| 400 | TEXT_TOO_LONG / INVALID_IDEMPOTENCY_KEY | 缩短文案或幂等键，不把加权计费字符误当输入长度 |
| 401 | INVALID_API_KEY / UNAUTHENTICATED | 检查 Bearer 格式与密钥；已停用账号的 Bearer 鉴权也返回 INVALID_API_KEY，不要循环重试 |
| 403 | EMAIL_NOT_VERIFIED / ACCOUNT_DISABLED | 完成邮箱验证；操作期间账号被停用也可能返回 ACCOUNT_DISABLED，需联系支持 |
| 402 | INSUFFICIENT_BALANCE | 补充有效资源包后重试 |
| 404 | TASK_NOT_FOUND | 确认任务 ID 及所属账号；无权访问也按不存在处理 |
| 409 | IDEMPOTENCY_CONFLICT / PRICE_CHANGED | 核对原请求或最新价格；不要盲目更换幂等键 |
| 409 | NOT_READY | 文件尚未就绪或无此文件，先查询任务返回的结果链接 |
| 410 | RESULT_EXPIRED | 原文件已过期；如需新结果须重新合成 |
| 413 / 415 | BODY_TOO_LARGE / CONTENT_TYPE | 缩小请求正文，使用 application/json |
| 429 | RATE_LIMITED / CONCURRENCY_LIMIT / DAILY_LIMIT | 按上方限制分类处理，不立即密集重试 |
| 503 | MODEL_DISABLED / AZURE_NOT_CONFIGURED / MINIMAX_NOT_CONFIGURED | 模型暂不可用，等待恢复或由调用者选择其他模型 |
| 503 / 500 | DATABASE_BUSY / SETUP_REQUIRED / INTERNAL_ERROR | 退避后重试；提交时保留原幂等键，持续异常时联系支持 |
输入上限按去掉首尾空白后的 Unicode 码点数计算，不等于 JavaScript 字符串的 UTF-16 length。计费用量按每个模型的 metering 规则执行，任务响应中的 billableUnits 是已保存的计费用量。
当前 Edge、Azure 和 MiniMax 的站内规则均为汉字按 2、其他码点按 1，内部空格、换行及标点计入。例如“你好，世界。”为 6 个原文字符、10 个计费字符；不能用 UTF-8 字节数计费。系统添加的控制标签不向用户计费，用户输入的 MiniMax 标记按该模型规则计入。
金额计算使用微美元整数，1 USD = 1,000,000 微美元；每个任务费用向上取整到微美元。已有任务保留价格与计量快照，调价不重算历史。时间字段是带时区的 ISO 8601 字符串，尚未发生或不适用的时间字段可为 null；具体可空性见相应接口。展示时转换到用户本地时区。文件保留期限与资源包有效期独立，详见结果保留规则。