API 概览
通过开放 API 在你的应用中调用声音克隆、文字转语音和声音转换。
开放 API 提供与网页版一致的语音能力：克隆声音、文字转语音(单条或批量)、声音转换，以及任务查询和 Webhook 回调。所有接口都在 /api/v1 下，返回 JSON。
基础地址
https://voiceailabs.com/api/v1认证
每个请求都要在 Authorization 请求头中携带 API 密钥：
curl https://voiceailabs.com/api/v1/account \
-H "Authorization: Bearer sk-your-api-key"- 密钥以
sk-开头，只在创建时显示一次，请保存在服务端，不要放到前端代码或公开仓库中。 - 密钥泄露后，请在 API 密钥 页面删除并重新创建。
- 同一账号的所有密钥共用积分、套餐限制和请求频率限制。
响应格式
所有接口都返回统一结构 { code, message, data }，并使用对应的 HTTP 状态码。
成功时 code 为 0：
{
"code": 0,
"message": "ok",
"data": { "id": "6f1c…", "object": "synthesis", "status": "pending" }
}失败时 code 为 -1，data 中包含错误码、是否可重试和请求 ID：
{
"code": -1,
"message": "Insufficient credits",
"data": {
"error_code": "INSUFFICIENT_CREDITS",
"retryable": false,
"request_id": "0b5e2f1a-…",
"required": 120,
"available": 30
}
}请根据 data.error_code 处理错误，不要依赖 message 的文字。完整列表见错误码与限制。联系支持时请提供 request_id(也在响应头 X-Request-Id 中)。
异步任务
文字转语音和声音转换都是异步任务：创建接口立即返回 202 和任务对象，生成完成后音频地址才可用。
创建任务：调用 POST /tts、POST /tts/batches 或 POST /voice-conversion，保存返回的 id。
等待完成：推荐配置 Webhook，任务结束时我们主动通知你；也可以每 2–5 秒调用 GET /syntheses/{id} 查询。
下载音频：status 为 completed 时下载 audio_url(MP3)。音频按你的套餐保留期保存，请及时转存。
任务状态：
| 状态 | 说明 |
|---|---|
pending | 已创建，正在排队或等待生成 |
processing | 已生成，正在保存音频 |
completed | 完成，audio_url 可下载 |
failed | 失败，已扣的积分会自动退还(见 refund) |
计费
- 创建任务时按计费规则预先扣除积分；任务失败时自动全额退还。
- 文字转语音按字数计费；如果你在网页版设置了发音词典，API 合成同样会应用，替换后文本更长时按替换后的文本计费。
- 声音转换按输入音频时长计费。
- 克隆声音不消耗积分，但占用套餐的声音名额。
接口列表
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /account | 账户、积分余额和套餐限制 |
GET | /voices | 我的声音列表 |
GET | /voices/public | 公共声音列表 |
GET | /voices/{id} | 声音详情 |
POST | /voices | 克隆声音 |
DELETE | /voices/{id} | 删除声音 |
POST | /tts | 创建文字转语音任务 |
POST | /tts/batches | 批量创建文字转语音任务 |
GET | /tts/batches/{id} | 查询批量任务 |
POST | /voice-conversion | 创建声音转换任务 |
GET | /syntheses | 任务列表 |
GET | /syntheses/{id} | 查询任务 |
版本与旧接口
- 当前版本为
v1。我们只会向v1增加字段、接口和错误码，不会删除字段或改变含义；请让你的代码忽略不认识的字段。 - 早期文档中的
/api/voice/*、/api/get-user-info等是网页内部接口，2026 年 11 月 30 日之后不再接受 API 密钥。请在此之前迁移到/api/v1。