跳到主要内容

声音设计 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

字段类型必填说明
voiceDescriptionstring是声音描述。去掉首尾空白后 1~200 个 Unicode 码点,不支持 emoji 表情。
previewTextstring否试听正文。去掉首尾空白后最多 300 个加权字符,不支持 emoji 表情;不传时自动生成。

除 previewText 外,文档中的文本长度限制均按 Unicode 码点计数,每个码点计 1。

previewText 加权计数:汉字、日文平假名/片假名、韩文 Hangul 和日文长音符(ー、ー)按 2 计算,其余 Unicode 码点按 1 计算,包括内部空格、标点及换行。例如,Hello! 为 6,你好 为 4。本规则与 TTS 计费字符规则不同。

响应字段类型说明
data.generationIdstring本轮生成 ID。
data.referenceTextstring三个候选实际使用的朗读正文。
data.candidatesarray三个候选。
data.candidates[].candidateNointeger候选编号:1、2、3。
data.candidates[].languagestring候选语言:zh、en、ja、ko。
data.candidates[].durationMsinteger候选音频时长,单位为毫秒。
data.candidates[].previewUrlstring候选 WAV 音频的临时签名 URL。
data.expiresAtintegerUnix 秒级时间戳,生成完成后 3 小时过期。

保存候选​

POST /api/tts/v1/voice-design/api/save

字段类型必填说明
generationIdstring是上一步返回的生成 ID。
candidateNointeger是1、2 或 3。
namestring是去掉首尾空白后 1~30 个 Unicode 码点,不支持 emoji 表情;组织内不区分大小写唯一。
languagestring是展示分类:zh、en、ja、ko,不影响音频。
descriptionstring是音色展示说明。去掉首尾空白后 1~200 个 Unicode 码点,不支持 emoji 表情。
avatarKeystring否通过控制台音色头像上传获得的对象键,支持 PNG/JPG/WEBP/SVG,文件不超过 5 MiB。音频上传接口的对象键不能用于头像。

服务自动分配正式音色 ID。

响应字段类型说明
data.savedVoiceIdstring正式音色 ID,后续作为 TTS 的 voice_id。
data.savedOrganizationIdstring保存组织 ID,十进制字符串。
data.deletedboolean该音色是否已被删除。
data.itemobject 或 null音色仍存在时返回展示资料;已删除时为 null。
data.item.voiceIdstring同一个正式音色 ID。
data.item.name、language、descriptionstring保存的展示资料。
data.item.avatarUrlstring临时头像 URL;未设置头像时为空字符串。
data.item.previewUrlstring参考音的临时 URL;URL 过期不等于音色 ID 过期。
data.item.sourceTypeinteger声音设计音色为 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展示名称已存在更换名称,在到期前重试同轮保存。
10003API 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。