音色克隆 API
通过一段短参考音频创建可复用的自定义音色。创建完成后，将它的 voice_id 直接用于现有的语音合成 API，用法与系统音色一致。
可以构建什么
三步创建并使用音色
1. 准备一段参考音频
你需要参考音频，以及已启用音色克隆能力的 API Key。原始音频时长须为 3–60 秒，文件不超过 20 MiB（20,971,520 字节），并且你必须已获得使用该音色的授权。
先设置 API 地址和 API Key。没有 Key 时，请参考获取 API Key。
export VUILABS_API_BASE_URL="https://api.vuilabs.ai"
export VUILABS_API_KEY="your-api-key"
支持的扩展名为 WAV、MP3、M4A、WebM、OGG。参考录音是本地文件时，先调用音频上传 API，
使用 scene=audio 并保留响应中的 data.object_key。上传会私有保存原始文件，
不会创建音色或消耗音色克隆次数。
curl --request POST \
--url "$VUILABS_API_BASE_URL/v1/files/upload" \
--header "X-API-Key: $VUILABS_API_KEY" \
--form "scene=audio" \
--form "file=@/path/to/reference.wav"
上传和创建音色使用同一个 API 环境及属于同一项目空间的 Key，对象键不能跨项目空间或环境 复用。如果已有公开音频 URL，可以跳过上传步骤。
2. 创建自定义音色
请选用一个简短、方便复用的 ID，并将 YOUR_UPLOAD_OBJECT_KEY 替换为上一步上传返回的 data.object_key。请求成功后保存音色 ID；后续合成时只需要通过它选择该自定义音色。
curl --request POST \
--url "$VUILABS_API_BASE_URL/v1/voice/save" \
--header "X-API-Key: $VUILABS_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"voice_id": "my_support_voice",
"ref_audio": "YOUR_UPLOAD_OBJECT_KEY"
}'
新建音色会使用当前音色克隆权益。每次成功创建自定义音色会优先消耗一次可用免费额度；免费额度不足时按当前音色克隆价格扣费，详见定价。每条新音色都应使用新的 voice_id；已有 ID 会被拒绝，避免误覆盖已有音色。
3. 使用自定义音色生成语音
将保存后的 voice_id 传给语音合成接口。你可以沿用其他音色的请求控制项，包括 speed，以及直接写入 text 的官方表达标签。
curl --request POST \
--url "$VUILABS_API_BASE_URL/v1/text-to-speech" \
--header "X-API-Key: $VUILABS_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"text": "您的预约已确认。",
"voice_id": "my_support_voice",
"language": "zh-CN",
"speed": 1
}' \
--output custom-voice.wav
请先用短句核对发音、语速和支持的标签，再生成更长内容。完整合成控制项和音频输出说明请见语音合成 API。
API 细节
接口概览
| 操作 | 接口 |
|---|---|
| 上传参考音频 | POST /v1/files/upload |
| 创建自定义音色 | POST /v1/voice/save |
| 查询自定义音色列表 | GET /v1/voice/list |
| 删除自定义音色 | DELETE /v1/voice/{voice_id} |
| 使用自定义音色合成语音 | POST /v1/text-to-speech |
音色管理接口使用 X-API-Key，并返回统一 JSON 响应结构：
{
"error_code": 0,
"error_message": "",
"succeed": true,
"data": {}
}
创建自定义音色
POST /v1/voice/save
| 请求头 | 必填 | 说明 |
|---|---|---|
X-API-Key | 是 | 已启用音色克隆能力的项目 API Key。 |
Content-Type | 是 | application/json |
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
voice_id | string | 是 | 去除首尾空白并转为小写后，新建音色 ID 长度为 1–30，仅可包含 a-z、0-9、_、-。 |
ref_audio | string | 是 | 音频上传 API 返回的 data.object_key、可公开访问的 HTTP/HTTPS 参考音频 URL 或现有可读取的对象键。上传对象键须属于当前 API Key 的组织和项目空间。 |
参考音频须为 WAV（.wav）、MP3（.mp3）、M4A（.m4a）、WebM（.webm）或 OGG（.ogg），时长必须在 3–60 秒之间，文件不超过 20 MiB。不支持 FLAC（.flac）、裸 AAC（.aac）和 .opus 文件。AAC 和 Opus 是编码：AAC 使用 M4A 容器，Opus 使用 OGG 或 WebM 容器。音频内容必须可读取；修改扩展名不会转换文件格式。
请提供单人清晰讲话的录音；纯静音或没有可用语音的音频无法创建音色。上传成功不代表符合克隆要求，上传接口没有克隆时长限制；若用于创建音色，建议上传前在本地检查时长。
超过 30 个字符的 ID 会被拒绝，返回 HTTP 400 和业务错误码
10001。此新建限制不会截短已有资源 ID：查询、删除或使用已有音色合成时，
请使用接口返回的原 ID。分页游标是不透明值。
请求成功时返回 HTTP 200；失败时返回非 2xx HTTP 状态码及相同的 JSON 响应结构。请同时检查 HTTP 状态码和 succeed/error_code，详见音色克隆错误。
错误码
error_code | 含义 | 处理方法 |
|---|---|---|
10018 | voice_id 已存在或被占用 | 更换 voice_id |
20010 | 参考音频文件过大 | 使用不超过 20 MiB 的文件 |
20012 | 参考音频格式不支持、无法读取、内容损坏或没有音频流 | 使用有效且受支持的音频文件 |
20015 | 参考音频超过 60 秒 | 使用 3–60 秒的录音 |
20016 | 参考音频不足 3 秒或没有足够的可用语音 | 使用更长、更清晰的录音 |
20017 | 录音中的停顿超过限制 | 使用更加连贯的录音 |
鉴权、限流、余额、超时、服务异常等通用错误请参见错误码。
管理自定义音色
GET /v1/voice/list 返回当前 API Key 所属组织可见的自定义音色。
| 查询参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
page_size | integer | 否 | 每页返回数量，范围为 1–20；默认值为 20。 |
voice_id | string | 否 | 上一页响应的 next_voice_id 不透明游标；首次查询不传。 |
curl --request GET \
--url "$VUILABS_API_BASE_URL/v1/voice/list?page_size=20" \
--header "X-API-Key: $VUILABS_API_KEY"
| 响应字段 | 类型 | 说明 |
|---|---|---|
data.list | array | 本页返回的自定义音色。 |
data.list[].voice_id | string | 用于语音合成的自定义音色 ID。 |
data.list[].voice_url | string | 该音色参考音频的临时签名地址。 |
data.list[].created_at | integer | 创建时间，Unix 秒级时间戳。 |
data.next_voice_id | string | 当 data.has_more 为 true 时，用于下一页的游标。 |
data.has_more | boolean | 是否还有更多结果。 |
data.total | integer | 本页返回的自定义音色数量。 |
data.remainingFreeCloneCount | integer | 当前账户剩余的免费音色克隆次数。 |
删除自定义音色时，调用 DELETE /v1/voice/{voice_id}。删除是幂等操作：删除已不存在的自定义音色也可能成功返回，且不会删除系统音色。
curl --request DELETE \
--url "$VUILABS_API_BASE_URL/v1/voice/my_support_voice" \
--header "X-API-Key: $VUILABS_API_KEY"