音色清单与检索
本页印出的枚举值是快照。机器可读的真相源是 枚举清单 —— 两边若有出入，以那份为准。
拉取全部可用配音音色，或用一句自然语言描述题材，让服务端推荐合适的音色。
配音合成本身走声音克隆配音接口；本页两个接口只负责选音色。
音色清单
基本信息
| 项目 | 值 |
|---|---|
| 请求方法 | GET |
| 请求路径 | /task/tts/voices |
| 鉴权方式 | 无需鉴权 |
| 缓存 | Cache-Control: public, max-age=60 + ETag |
查询参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
engine | string | 否 | 只返回该引擎的音色 |
maturity | string | 否 | 只返回该成熟度的音色：stable / experimental |
返回字段
| 字段 | 类型 | 说明 |
|---|---|---|
voice_id | string | 音色标识，即合成接口的 speaker 取值 |
display_name | string | 展示名 |
gender | string | 性别 |
languages | string[] | 语种（BCP-47） |
dialect | string | 方言（如 sichuan、dongbei；无则为空） |
persona | string | 人设格位（如「男声沉稳厚重」） |
desc | string | 中文音色描述 |
tags | string[] | 标签（音质特征 / 气质 / 题材） |
topics | string[] | 适合的题材 |
not_suitable | string | 不适合的场景与原因 |
speed_range | object | 语速可调区间 {min, max, default}。逐音色不同；min 与 max 同为 1.0 表示该音色不支持调速 |
speech_rate_cpm | number | 挂钟语速估值（字/分钟）：稿件字符数 ÷ 合成音频总时长（含句间停顿），基线是该音色实际生效的默认合成参数，与 speed_range.default 无关。用来按音色估「一段稿子念出来多长」。估值，不参与计费。仅中文音色（zh-CN / zh-HK / yue-HK）才有，见下方说明 |
speech_rate_basis | string | speech_rate_cpm 的出处：measured（实测标定）/ derived（由声学测量推算）。与 speech_rate_cpm 同进同出 |
styles | string[] | 该音色支持的说话风格（部分引擎有） |
credits_per_kchar | integer | 单价（积分 / 千字符）——现行计费口径。与价格页「声音克隆配音」的分档逐档相等 |
credits_per_minute | integer | ⚠️ 已废弃（计费口径 2026-08 已由分钟改为千字符）。过渡期与 credits_per_kchar 双发，仅因旧文档教用户读它；公告期结束后移除。新接入请勿使用 |
audition_url | string | 试听样音，全部音色念同一句标语，便于横向比较 |
engine | string | 合成引擎 |
maturity | string | stable / experimental |
experimental | boolean | 实验性音色才有。见下方说明 |
internal_only | boolean | 仅内部成员可用的音色才有 |
available_to_you | boolean | 同上；表示当前身份能否使用 |
关于挂钟语速
speech_rate_cpm 让你按音色估算稿件篇幅或音频时长，例如目标时长 3 分钟、某音色 310 字/分钟，稿子约 930 字。
- 这是估值：实际时长还会受标点、数字读法和停顿参数影响，服务端不对它作时长承诺；它不参与计费，计费看
credits_per_kchar。 - 只有中文音色带这两个字段。英文、日文按「字」计的语速没有可比性，这些音色不返回它们。
- 缺数据时两个字段一并省略，不会出现
null。读不到时请用你自己的缺省值，也请不要把那个缺省值当作服务端口径转述给别人。 speech_rate_basis为derived表示由声学测量推算、尚未实测标定；日后完成实测标定的音色会变为measured，数值可能随之调整。- 基线是该音色实际生效的默认合成参数。部分自训音色的实际默认语速倍率并不等于
speed_range.default，请勿用speed_range.default去折算这个值。 - 语义检索的候选同样带这两个字段，挑音色时就能直接估篇幅。
关于实验性音色
带 experimental: true 的音色不保证服务稳定性，音色可能变动或下架，仅供测试使用。如果你的业务需要稳定性保障，用 ?maturity=stable 过滤掉它们。
关于内部音色
带 internal_only: true 的音色照常出现在清单里，但仅同合云内部成员可用。其他账号提交时会返回参数错误并明示原因，不会静默替换成其他音色——拿到一条声音不对的成片，比拿到一个明确的错误糟得多。
缓存
响应带 ETag。下次请求把上次拿到的值放进 If-None-Match，内容未变时返回 304 空体，不重复传输。
curl -i "https://api.ai-mcn.tv:10000/task/tts/voices?maturity=stable"
# 拿到 ETag 后
curl -i -H 'If-None-Match: "<上次的 ETag>"' "https://api.ai-mcn.tv:10000/task/tts/voices"
语义检索
用一句自然语言描述你要做的内容，返回最匹配的若干候选。
基本信息
| 项目 | 值 |
|---|---|
| 请求方法 | POST |
| 请求路径 | /task/tts/voices/search |
| Content-Type | application/json |
| 鉴权方式 | Authorization 请求头 |
请求参数（Body）
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
query | string | 是 | — | 自然语言的题材或气质描述 |
top_k | integer | 否 | 5 | 返回候选数，上限 20 |
filters | object | 否 | — | 收窄范围，键可取 engine / persona / gender / dialect；值可为单值或数组 |
返回
每条候选是清单接口的同一组字段，另加：
| 字段 | 类型 | 说明 |
|---|---|---|
score | number | 相似度 |
why | string | 命中理由（人设、关键标签、适合题材） |
返回的是候选不是判决。 音色是审美选择，最终选哪个由你决定；本接口不会依据分数替你剔除。
请求示例
{
"query": "讲历史的低沉男声，像老学者那样娓娓道来",
"top_k": 5,
"filters": { "gender": "男" }
}
描述得越具体越好。「男声」这种只说了性别的查询，不如「东北话吐槽风格，节奏快、有市井烟火气」有效——后者能同时命中方言、气质与语速三个维度。
使用限制
- 检索需要鉴权（它要跑一次向量化，有算力成本）；清单不需要。
- 音色清单会持续更新，调用前请以接口返回为准，不要硬编码音色列表。
🤝 加入同和新媒体矩阵，解锁内部成员权益：矩阵成员（internal）可使用 custom 域全库素材检索（视频 / 图片 / 音频，含概念素材与非商用素材，支持仅可商用过滤）与内部专属音色。前往 创作者网络 申请加入，审核通过后管理员将为你开通内部权限。