声音接口

合成时用 voice_id 指定声音。可以使用两类声音：

我的声音：你克隆的声音，以及在声音广场“添加”的声音。
公共声音：声音广场中公开的声音，直接用 id 合成即可，不需要添加，也不占声音名额。

声音对象

{
  "id": "2d7c8f0e-5a1b-4c3e-9f7a-1b2c3d4e5f60",
  "object": "voice",
  "name": "温柔女声",
  "description": "适合有声书旁白",
  "status": "ready",
  "language": "zh",
  "gender": "female",
  "age_group": "youth",
  "tags": ["scenario.audiobook"],
  "avatar_url": "https://…",
  "preview_audio_url": "https://…",
  "is_public": false,
  "created_at": "2026-10-01T08:00:00.000Z",
  "updated_at": "2026-10-01T08:00:00.000Z"
}

字段	说明
`status`	`ready` 可以合成；`pending` 处理中；`failed` 克隆失败
`language`	声音的主要语言，可能为 `null`
`gender` / `age_group`	性别与年龄段，未设置时为 `null`
`preview_audio_url`	试听音频，可能为 `null`
`is_public`	`true` 表示公共声音(只读)；公共声音还会返回 `usage_count`，但不返回 `tags`、`created_at`、`updated_at`

我的声音列表

GET /api/v1/voices?page=1&limit=20&search=旁白

参数	说明
`page`	页码，从 1 开始
`limit`	每页条数，1–100，默认 20
`search`	按名称搜索

{
  "code": 0,
  "message": "ok",
  "data": { "object": "list", "items": [ /* 声音对象 */ ], "page": 1, "limit": 20, "total": 3, "has_more": false }
}

公共声音列表

GET /api/v1/voices/public?page=1&limit=20&search=新闻

按使用人数排序。limit 最大 50。返回中没有 total，用 has_more 判断是否还有下一页。

声音详情

GET /api/v1/voices/{id}

可以查询自己的声音或公共声音。声音不存在或无权访问时返回 404 NOT_FOUND。

克隆声音

上传一段录音创建你自己的声音。请求格式为 multipart/form-data。

curl https://voiceailabs.com/api/v1/voices \
  -H "Authorization: Bearer $VAL_API_KEY" \
  -H "Idempotency-Key: clone-host-anna" \
  -F "name=主播 Anna" \
  -F "language=zh" \
  -F "consent=true" \
  -F "[email protected]"

参数	必填	说明
`audio`	是	录音文件：WAV、MP3、OGG、WEBM、M4A；3 秒–5 分钟，推荐 10–30 秒；大小不超过套餐上限
`name`	是	声音名称，最多 100 字
`consent`	是	必须为 `true`，表示你拥有该声音或已获得声音所有者的授权
`description`	否	描述，最多 500 字
`language`	否	`zh`、`en`、`yue`、`ja`、`ja-asmr`、`ko`、`fr`、`es`、`pt`、`de`，默认自动识别
`gender`	否	`female`、`male`、`neutral`
`age_group`	否	`child`、`teen`、`youth`、`middle_aged`、`senior`

成功返回 201 和声音对象，通常 status 直接为 ready。

授权声明

只能克隆你本人的声音，或已获得明确授权的声音。禁止用于冒充、欺诈或误导性内容。

录音建议：单人说话、环境安静、不要背景音乐；音量适中，不要削波。样本未通过质量检查时返回 SAMPLE_QUALITY_FAILED，data.issues 中列出具体问题：

{
  "code": -1,
  "message": "The audio sample did not pass the quality check",
  "data": {
    "error_code": "SAMPLE_QUALITY_FAILED",
    "retryable": false,
    "request_id": "…",
    "issues": [{ "code": "too_short", "severity": "error" }]
  }
}

可能的错误：CONSENT_REQUIRED、VOICE_LIMIT_REACHED(声音名额已满)、UNSUPPORTED_AUDIO_FORMAT、UPGRADE_REQUIRED(文件超出套餐大小上限)、FILE_TOO_LARGE(超过 30MB)、SAMPLE_QUALITY_FAILED、INVALID_REQUEST(参数不合法，如 language、gender、age_group 不在可选值内)、SYSTEM_BUSY(克隆处理超时，可稍后重试)。

删除声音

DELETE /api/v1/voices/{id}

只能删除自己的声音，删除后释放声音名额，无法恢复。已经生成的音频不受影响。

{ "code": 0, "message": "ok", "data": { "id": "2d7c…", "object": "voice", "deleted": true } }