零样本音色配音
上传一段参考音频或含人声的视频，再给一段文本，用参考里说话人的音色合成这段文本的配音。不需要预先训练音色，一段 3 秒以上的清晰人声就够。
与「声音克隆配音」的区别：那边用的是音色清单里预置的音色，这边用的是你自己给的参考。服务端会从参考媒体里自动选出 3–10 秒的干净单人声段作为克隆参考（含背景音乐时先分离人声），并在产物 report.ref 里如实报告选用了哪一段。
⚠️ 零样本克隆的相似度受参考质量影响很大：参考尽量选清晰、无混响、单人说话的片段。它的效果是「像」这个人，达不到预置音色那种逐字调过的稳定度。
创建任务
基本信息
| 项目 | 值 |
|---|---|
| 请求方法 | POST |
| 请求路径 | /task/audio_tts_zero_shot |
| Content-Type | application/json |
| 鉴权方式 | Authorization 请求头（直接传 API Key） |
请求参数（Body）
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
text | string | 是 | — | 待合成文本，非空，长度上限 5000 字（按 Unicode 码点计，一个中日韩字符算 1） |
ref_file_id | string | 是 | — | 参考媒体的文件 ID（已上传的音频或视频；视频只取其音轨）。总时长须在 3 秒到 30 分钟之间，其中至少要有 3 秒连续、清晰、单人说话的人声；含背景音乐时服务端会先分离人声再选段。发起本任务即视为您已按用户协议对被克隆声音的自然人取得单独同意，且不会将生成语音用于冒充等用途 |
ref_text | string | 否 | 服务端识别 | 参考段对应的文字。不传时服务端对选出的参考段做语音识别得到参考文字，识别失败或为空则任务失败（错误的参考文字会让克隆音色跑偏，宁失败不将就）。传了则原样采用、不做识别；参考媒体里说话内容明确时建议传。产物 report.ref.text_source 会标明来源 |
ref_lang | string | 否 | 同 text_lang | 参考段的语种，传标准地区语言码：zh-CN、zh-HK（粤语）、en-US、ja-JP、ko-KR 五种；zh-CHS / zh-CHT 按 zh-CN 处理 |
text_lang | string | 否 | zh-CN | 待合成文本的语种，传标准地区语言码，同上五种；传入其他语种返回参数错误、不建任务、不计费 |
output_format | string | 否 | wav | 输出音频格式：wav 或 mp3 |
speed | number | 否 | 1.0 | 语速倍率（1.0 = 原速），合法区间 [0.5, 2.0]，越界返回参数错误、不做静默钳位 |
fragment_interval | number | 否 | 引擎默认 | 句间停顿秒数，合法区间 [0.05, 1.0]（闭区间），越界返回参数错误、不做静默钳位 |
subtitle_format | string | 否 | 不生成字幕 | 传 srt 时，除音频外额外产出一份 .srt 字幕文件，时码取自本次合成的句级时码、与音频严格一致，不额外计费。语义与「声音克隆配音」一致 |
canvas | integer[] | 否 | [1080, 1920]（竖屏） | 成片画布 [宽, 高]，仅在传 subtitle_format 时可用（只传它会返回参数错误）。字幕按该画幅把过长的句子拆成多行；横屏成片请显式传 [1920, 1080] |
strip_punctuation | boolean | 否 | true | 字幕文本去标点开关，仅作用于附赠的 .srt 字幕文本，仅在传 subtitle_format 时可用。语义与「声音克隆配音」一致 |
计费说明
按输入文本的字符数计费，计量单位是千字符，口径与「声音克隆配音」逐字一致：
- 计费单位数 =
text字符数 ÷ 1000（保留小数），最终扣费向上取整到整积分，任何非空文本至少 1 积分 - 参考媒体的时长不参与计费：同一段文本配 5 秒参考和配 20 分钟参考，扣费相同
- 单价见价格页「声音克隆配音」家族下的「零样本音色配音」档（当前 6 积分 / 千字符，以价格页为准）
请求示例
curl -X POST https://api.ai-mcn.tv:10000/task/audio_tts_zero_shot \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "大家好，欢迎收听本期节目。",
"ref_file_id": "537489015178246",
"text_lang": "zh-CN",
"output_format": "wav",
"subtitle_format": "srt",
"canvas": [1920, 1080]
}'
成功响应示例
{
"code": 200,
"msg": "success",
"data": {
"task_id": "537489015178247",
"task_type": "audio_tts_zero_shot",
"status": "queued"
}
}
查询任务结果
基本信息
| 项目 | 值 |
|---|---|
| 请求方法 | GET |
| 请求路径 | /task/audio_tts_zero_shot/{task_id} |
| 鉴权方式 | Authorization 请求头（直接传 API Key） |
响应参数（output_result）
出参键名与「声音克隆配音」逐字一致，另加 report.ref。已经在读那个接口产物的代码可以直接复用。
| 参数名 | 类型 | 说明 |
|---|---|---|
file_id | string | 合成音频文件 ID |
download_url | string | 音频下载路径 |
speaker | string | 固定为 zero_shot（本接口没有预置音色代号，保留此键是为了与「声音克隆配音」出参同形） |
voice_id | string | 同 speaker |
engine | string | 合成引擎 |
sample_rate | integer | 音频采样率（Hz） |
duration_ms | integer | 音频实际时长（毫秒），与计费无关 |
segments_source | string | 句级时码的来源：assembled = 逐句合成累加得到；realigned = 合成后时码与音频出现偏差、已按成品音频重新对齐；none = 本次没有可用的句级时码（此时无 segments 键） |
segments | array | 句级时码 [{index, text, start_ms, end_ms}]：每句在音频里的起止毫秒，end_ms 含该句尾部的自然停顿，时间轴首尾相接无缝隙。segments_source 为 none 时不出现 |
subtitle_file_id | string | 字幕文件（.srt）ID。仅当请求传了 subtitle_format 时出现；生成失败时为空串，原因见 errors.subtitle |
subtitle_file_download_url | string | 字幕文件下载路径 |
errors | object | 仅在附赠产物降级时出现。字幕生成失败记在 errors.subtitle，任务仍是 completed、音频产物不受影响 |
report.ref | object | 参考段的选用报告（见下表）。用它判断该不该换一段参考、或自己传 ref_text |
report.ref 字段
| 字段 | 类型 | 说明 |
|---|---|---|
span_ms | integer[] | 实际采用的参考段在原参考媒体里的起止毫秒 [start, end]，可按它回原媒体截取核对 |
separated | boolean | 是否经过人声分离：true = 参考媒体里检测到背景音乐，选段来自分离后的人声；false = 纯人声，直接取原音 |
gain_db | number | 归一化时对参考段施加的增益（dB） |
text_source | string | 参考文字来源：user = 你传的 ref_text；asr = 服务端识别 |
asr_confidence | number | 参考段识别的置信度（0–1）；text_source 为 user 时为该段识别覆盖率的参考值 |
ref_text | string | 实际采用的参考文字 |
ref_lang | string | 实际采用的参考语种（标准地区语言码，如 zh-CN） |
成功响应示例
{
"code": 200,
"msg": "success",
"data": {
"task_id": "537489015178247",
"status": "completed",
"progress": 100,
"output_result": {
"file_id": "537489015178248",
"download_url": "/download/a1/output_tts.wav",
"speaker": "zero_shot",
"voice_id": "zero_shot",
"engine": "gpt_sovits",
"sample_rate": 32000,
"duration_ms": 5240,
"segments_source": "assembled",
"segments": [
{ "index": 0, "text": "大家好，欢迎收听本期节目。", "start_ms": 0, "end_ms": 2600 },
{ "index": 1, "text": "今天我们聊聊视频译制。", "start_ms": 2600, "end_ms": 5240 }
],
"subtitle_file_id": "537489015178249",
"subtitle_file_download_url": "/download/a1/output_tts.srt",
"report": {
"ref": {
"span_ms": [3120, 11040],
"separated": false,
"gain_db": 4.2,
"text_source": "asr",
"asr_confidence": 0.93,
"ref_text": "大家好欢迎收看今天的节目",
"ref_lang": "zh-CN"
}
}
},
"create_time": "2026-09-16T08:00:00Z",
"update_time": "2026-09-16T08:00:41Z"
}
}
错误码
| 错误码 | HTTP 状态码 | 说明 | 解决方案 |
|---|---|---|---|
6013 | 400 | 必填参数缺失（text / ref_file_id） | 补齐参数 |
6016 | 400 | 业务参数非法（text 为空或超长、text_lang / ref_lang 不在五种支持语种内、speed 或 fragment_interval 越界、output_format 非法、字幕相关参数非法、参考媒体时长不足 3 秒或超过 30 分钟等） | 按参数说明修正 |
6014 | 400 | 参考文件不是音频或视频 | 上传音频或视频文件 |
6004 | 404 | 参考文件不存在 | 检查 ref_file_id 是否正确 |
6502 | 401 | 鉴权失败 | 检查 Authorization 请求头 |
6201 | 402 | 额度不足 | 前往仪表盘充值 |
6202 | 402 | 余额不足 | 前往仪表盘充值 |
以上错误都发生在建单阶段：不建任务、不计费。参考预处理阶段的失败（例如整段媒体里选不出满足条件的 3 秒单人声、或参考段无法识别出文字）发生在任务执行期，任务状态为 failed，已预扣的积分退还，失败原因写在任务的错误信息里。
使用限制
- 参考媒体：3 秒到 30 分钟，音频或视频均可（视频只取音轨）。服务端只在其中挑 3–10 秒做参考，超长媒体不会带来更好的效果，反而拖慢预处理，建议截取含目标人声的片段上传。
- 参考段的选取判据：单人说话（无重叠语音）、识别置信度达标、段内无超过 0.6 秒的静音、时长 3–10 秒。四条都不满足时任务失败并说明未满足的判据；
report.ref.span_ms告诉你最终用了哪一段。 - 含背景音乐的参考会先分离人声，
report.ref.separated为true；纯人声参考直接取原音，避免分离带来的音色损失。 - 参考文字：说话内容明确时建议自己传
ref_text，比服务端识别更稳；传错会明显影响音色相似度。 - 语种：参考与目标文本都限
zh-CN/zh-HK/en-US/ja-JP/ko-KR五种标准码。跨语种（例如中文参考念英文）可以做，相似度会低于同语种。 - 每次都是新演绎：本接口不命中合成缓存（参考每次不同），相同请求重复提交会重新合成、照常计费。
- 单人音色：一次任务只克隆一个人的声音。参考里有多人对话时会挑出单人段；想分别克隆多个人，请各自截取参考分别提交。
- 单次合成文本上限 5000 字，与「声音克隆配音」的自研音色同一条合成队列，长文本按句合成再拼接，越长耗时越久。
- 生成的语音向公众发布或传播时，须依法以显著方式标识为 AI 生成内容。
🤝 加入同和新媒体矩阵，解锁内部成员权益：矩阵成员（internal）可使用 custom 域全库素材检索（视频 / 图片 / 音频，含概念素材与非商用素材，支持仅可商用过滤）与内部专属音色。前往 创作者网络 申请加入，审核通过后管理员将为你开通内部权限。