声音设计 API
无需上传参考录音,通过文字描述设计音色,试听三个候选并保存最符合预期的一个。保存后,将返回的音色 ID 作为 voice_id 用于语音合成 API。
接口概览
| 操作 | 接口 |
|---|---|
| 生成三个候选 | POST /api/tts/v1/voice-design/api/generate |
| 保存一个候选 | POST /api/tts/v1/voice-design/api/save |
| 使用正式音色合成语音(语音合成 API) | POST /v1/text-to-speech |
开始之前
- 生成候选和保存音色需要项目 API Key 具备「声音复刻」权限。使用已保存音色合成语音需要「语音合成」权限。同一个 Key 要完成三步,项目需同时启用两项权限。所有请求通过
X-API-Key请求头鉴权。申请方法见获取 API Key。 - 生成候选和保存新音色均需有效付费订阅。
- 保存新音色需有可用的组织声音槽位,成功后占用一个与克隆音色共用的槽位。生成不检查或预占槽位。
请求头
| 请求头 | 必填 | 说明 |
|---|---|---|
X-API-Key | 是 | 项目 API Key。 |
Content-Type | 是 | application/json。 |
Accept-Language | 否 | 仅控制 error_message 的语言:en(默认)或 zh-CN。 |
计费
每轮生成(三个候选)计 1 次。优先使用组织可用的声音设计免费次数,耗尽后按 0.01 美元/次从账户余额扣费。免费次数耗尽时,账户余额须足够支付单轮费用。详见定价。
保存不额外收费。生成成功后,放弃保存、候选过期或保存失败均不退还原生成费用。
可在控制台查看当前组织的剩余免费次数,列表仅展示有剩余额度的项目。
以下示例使用 cURL。
export VUILABS_API_BASE_URL="https://api.vuilabs.ai"
export VUILABS_API_KEY="your-api-key"
1. 生成三个候选
生成接口同步返回结果。建议将客户端请求总超时设置为 60 秒或更长;文本较长或服务繁忙时,应适当延长等待时间。
每次提交生成请求都会创建新一轮,成功后会再次消耗免费次数或扣费。网络超时、连接断开或响应丢失时,请勿自动重发;服务可能已完成生成。结果无法确认时,保留请求时间及生成 ID(如有),并联系支持。
curl --request POST --max-time 60 \
--url "$VUILABS_API_BASE_URL/api/tts/v1/voice-design/api/generate" \
--header "X-API-Key: $VUILABS_API_KEY" \
--header "Content-Type: application/json" \
--header "Accept-Language: zh-CN" \
--data '{
"voiceDescription": "Read in English. A warm adult female narrator with a clear, calm and welcoming voice."
}'
previewText 可选;不传时,服务根据描述自动生成试听正文。
成功响应:
{
"error_code": 0,
"error_message": "",
"succeed": true,
"data": {
"generationId": "YOUR_GENERATION_ID",
"referenceText": "Welcome. Take a moment to settle in and make yourself at home.",
"candidates": [
{"candidateNo": 1, "language": "en", "durationMs": 7080, "previewUrl": "YOUR_SIGNED_PREVIEW_URL_1"},
{"candidateNo": 2, "language": "en", "durationMs": 7080, "previewUrl": "YOUR_SIGNED_PREVIEW_URL_2"},
{"candidateNo": 3, "language": "en", "durationMs": 7080, "previewUrl": "YOUR_SIGNED_PREVIEW_URL_3"}
],
"expiresAt": 1793013949
}
}
生成成功后,将响应中的 data.generationId 用于保存音色。三个候选的音频地址分别位于 data.candidates[].previewUrl。
2. 试听并保存一个候选
生成的候选音频及其试听链接有效期为 3 小时,截止时间见 expiresAt。建议生成后尽快试听并保存需要的音色;过期后需要重新生成,并按新一轮计费。
每个候选的 previewUrl 都是 WAV 音频地址,可直接用于播放器试听或下载,无需转码。不要向音频地址转发 API Key。
下载示例:
curl --fail "YOUR_PREVIEW_URL" --output design-candidate.wav
选择一个候选,将 data.generationId 和对应的 candidateNo 填入保存请求。以下示例保存第 2 个候选。首次保存新音色时会校验候选有效期、订阅、槽位和成员权限。
curl --request POST \
--url "$VUILABS_API_BASE_URL/api/tts/v1/voice-design/api/save" \
--header "X-API-Key: $VUILABS_API_KEY" \
--header "Content-Type: application/json" \
--header "Accept-Language: zh-CN" \
--data '{
"generationId": "YOUR_GENERATION_ID",
"candidateNo": 2,
"name": "Welcome narrator",
"language": "en",
"description": "A calm narrator for welcome messages."
}'
候选音频不超过 15 秒时,保存完整音频及原朗读正文;超过 15 秒时,可能提取可用语音片段,因此保存后的参考音试听可能与原候选不同。音频处理被明确拒绝时,不创建音色、不占槽位。
3. 用正式音色合成新文本
保存成功后,将响应中的 data.savedVoiceId 作为 TTS 的 voice_id,合成新的文本:
curl --fail-with-body --request POST \
--url "$VUILABS_API_BASE_URL/v1/text-to-speech" \
--header "X-API-Key: $VUILABS_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model_id": "luna-tts-1.5",
"voice_id": "YOUR_SAVED_VOICE_ID",
"text": "Hello again. This sentence checks the saved voice.",
"language": "en-US",
"audio_format": "wav"
}' \
--dump-header design-speech.headers \
--output design-speech.response || { cat design-speech.response >&2; exit 1; }
if ! grep -Eiq '^content-type:[[:space:]]*audio/wav([[:space:];]|$)' design-speech.headers || [ ! -s design-speech.response ]; then
cat design-speech.response >&2
echo 'Expected a non-empty audio/wav response' >&2
exit 1
fi
mv design-speech.response design-speech.wav
合成成功返回 WAV 二进制,请检查 HTTP 状态与音频 Content-Type。本流程使用 luna-tts-1.5,后续合成另按 TTS 规则计费;完整输出和错误处理见语音合成 API。
要查看已保存设计音色的名称和描述,请在音色查询 API中传入 source=personal。删除音色请参见自定义音色管理。
怎么写好声音描述
在 voiceDescription 中写清用途、语言及最重要的音色特征,例如年龄感、音高、音质、语速和情绪。选择两到四个主要特征,避免互相矛盾的要求。
反例:“语速很快,同时语速很慢”让目标不明确;可改为“语速中等,语气舒缓”。
| 用途 | 描述示例 |
|---|---|
| 中文绘本旁白 | 中文绘本旁白,年轻女性,嗓音清亮柔和,语速中等,语气亲切。 |
| 英文产品介绍 | English narration. An adult male voice with a warm, low tone, a steady pace, and a calm delivery. |
| 日语故事朗读 | 日本語の朗読。落ち着いた成人女性の声で、自然な速さと柔らかい語り口。 |
先用简洁描述试听,再逐次调整一个特征进行比较。需要固定朗读内容时,在 previewText 中填写实际要试听的文本。
请求与响应字段
生成候选
POST /api/tts/v1/voice-design/api/generate
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
voiceDescription | string | 是 | 声音描述。去掉首尾空白后 1~200 个 Unicode 码点,不支持 emoji 表情。 |
previewText | string | 否 | 试听正文。去掉首尾空白后最多 300 个加权字符,不支持 emoji 表情;不传时自动生成。 |
除 previewText 外,文档中的文本长度限制均按 Unicode 码点计数,每个码点计 1。
previewText 加权计数:汉字、日文平假名/片假名、韩文 Hangul 和日文长音符(ー、ー)按 2 计算,其余 Unicode 码点按 1 计算,包括内部空格、标点及换行。例如,Hello! 为 6,你好 为 4。本规则与 TTS 计费字符规则不同。
| 响应字段 | 类型 | 说明 |
|---|---|---|
data.generationId | string | 本轮生成 ID。 |
data.referenceText | string | 三个候选实际使用的朗读正文。 |
data.candidates | array | 三个候选。 |
data.candidates[].candidateNo | integer | 候选编号:1、2、3。 |
data.candidates[].language | string | 候选语言:zh、en、ja、ko。 |
data.candidates[].durationMs | integer | 候选音频时长,单位为毫秒。 |
data.candidates[].previewUrl | string | 候选 WAV 音频的临时签名 URL。 |
data.expiresAt | integer | Unix 秒级时间戳,生成完成后 3 小时过期。 |
保存候选
POST /api/tts/v1/voice-design/api/save
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
generationId | string | 是 | 上一步返回的生成 ID。 |
candidateNo | integer | 是 | 1、2 或 3。 |
name | string | 是 | 去掉首尾空白后 1~30 个 Unicode 码点,不支持 emoji 表情;组织内不区分大小写唯一。 |
language | string | 是 | 展示分类:zh、en、ja、ko,不影响音频。 |
description | string | 是 | 音色展示说明。去掉首尾空白后 1~200 个 Unicode 码点,不支持 emoji 表情。 |
avatarKey | string | 否 | 通过控制台音色头像上传获得的对象键,支持 PNG/JPG/WEBP/SVG,文件不超过 5 MiB。音频上传接口的对象键不能用于头像。 |
服务自动分配正式音色 ID。
| 响应字段 | 类型 | 说明 |
|---|---|---|
data.savedVoiceId | string | 正式音色 ID,后续作为 TTS 的 voice_id。 |
data.savedOrganizationId | string | 保存组织 ID,十进制字符串。 |
data.deleted | boolean | 该音色是否已被删除。 |
data.item | object 或 null | 音色仍存在时返回展示资料;已删除时为 null。 |
data.item.voiceId | string | 同一个正式音色 ID。 |
data.item.name、language、description | string | 保存的展示资料。 |
data.item.avatarUrl | string | 临时头像 URL;未设置头像时为空字符串。 |
data.item.previewUrl | string | 参考音的临时 URL;URL 过期不等于音色 ID 过期。 |
data.item.sourceType | integer | 声音设计音色为 2。 |
重试与幂等
| 请求 | 重试行为 |
|---|---|
| 生成 | 不幂等。再次提交会新建一轮,成功后再次计费。 |
| 保存 | 幂等。响应丢失或保存结果未知时,重试同一轮保存可读取原结果,不会额外创建音色。已成功保存的轮次,只要仍有访问权限,即使订阅到期也可取回保存结果。 |
每轮最多保存一个音色。成功后重复保存,即使更换 candidateNo,也返回第一次的结果,不更新资料。候选过期后仍可读取已经保存的结果。
原音色删除后,重复保存返回原 savedVoiceId、deleted: true 和 item: null,同轮不能重新创建音色。
请求限制
默认生成、保存各 每 60 秒 10 次,分别计数。同一组织内,同一用户的页面操作和 API Key 共享对应操作的请求频率限制。
每个用户最多同时进行 2 轮生成。该并发额度由此用户跨组织的页面操作和所有 API Key 共享;不同用户分别计数。保存音色不占用生成并发。达到请求频率或生成并发限制时返回 10005;因频率或并发达到限制而被拒绝的请求不会生成候选或扣费。限流响应及扩容方式见请求限制。
错误与恢复
两个声音设计接口都返回统一 JSON 包络。业务拒绝可能返回 HTTP 200 与 succeed: false,必须检查 succeed、error_code,同时处理网络错误和非 2xx 响应。未设置 Accept-Language 时,错误提示默认英文。传入 Accept-Language: en 返回英文,传入 Accept-Language: zh-CN 返回中文。该请求头仅控制 error_message 的语言。
声音设计错误响应的 data 为 null,保存新音色时的槽位不足按 error_code: 12903 判断。
声音槽位不足的中文错误响应示例(传入 Accept-Language: zh-CN):
{
"error_code": 12903,
"error_message": "声音槽位不足,请升级订阅或释放槽位。",
"succeed": false,
"data": null
}
声音设计接口的错误及处理方式如下。
error_code | 含义 | 处理方法 |
|---|---|---|
10001 | 参数无效,或缺少 X-API-Key / Content-Type: application/json 请求头 | 检查请求头、必填字段、长度及语种枚举。 |
12934 | 声音名称、描述或试听文本不支持表情 | 移除输入中的表情后重试。 |
10024 | 展示名称已存在 | 更换名称,在到期前重试同轮保存。 |
10003 | API Key 无效 | 检查 API Key 和 API 环境。 |
10004 | 缺少项目权限,或没有轮次或资源的访问权限 | 确认项目已启用「声音复刻」。保存时使用与生成时同一组织、同一所属用户的 Key。 |
12931 | 需要付费订阅 | 开通有效付费订阅后再生成或保存新音色。 |
12903 | 保存新音色时组织声音槽位不足 | 释放槽位或升级套餐,在候选到期前重试保存;候选过期后需要重新生成。 |
20003 | 账户余额不足 | 充值后再提交生成请求。 |
10002 | 轮次或资源不存在 | 检查生成 ID 和 API 环境。 |
12932 | 候选已经过期 | 重新生成,按新一轮计费。 |
12933 | 生成结果暂未确认 | 请勿自动重发生成请求,保留请求时间及生成 ID(如有),联系支持。 |
20016 | 没有可用于保存的语音片段 | 在有效期内尝试其他候选,或重新生成音色。 |
20017 | 音频停顿超过 3 秒 | 在有效期内尝试其他候选。 |
12913 | 音色与模型不兼容 | 更换为支持当前模型的音色。 |
12914 | 无法识别参考语音的语种 | 尝试有效期内的其他候选。 |
12915 | 参考语音的语种不受支持 | 仅使用中文、英语、日语或韩语候选。 |
10005 | 请求频率或生成并发达到限制 | 等待后再尝试,注意生成请求不幂等。 |
10006 | 请求超时 | 有效期内可重试同轮保存;生成结果未知时请勿自动重发。 |
20002 | 模型或依赖服务暂时不可用 | 有效期内可重试同轮保存;生成结果未知时请勿自动重发。 |
其他 API 错误见错误处理。联系支持时提供接口、含时区的请求时间、生成 ID(如有)和错误码,不要提供 API Key 或签名试听 URL。