全部文档
当前文档
最近更新时间：2026-07-28 10:38:09
金山云speech-2.6-hd模型，提供高质量的文本转语音服务，支持多种音色、情感控制、流式输出、自定义发音词典等能力。本接口兼容 MiniMax speech-2.6 系列模型。
项目 | 说明 |
请求方式 | POST |
请求地址 | |
Content-Type | application/json |
认证方式 | Bearer Token — 请求头携带 Authorization: Bearer <KSC_API_KEY> |
在请求头中传入您的金山云 API Key：Authorization: Bearer KSC_API_KEY，将 KSC_API_KEY 替换为您在金山云控制台获取的实际 API Key。
参数名 | 类型 | 必填 | 默认值 | 说明 |
model | string | 是 | — | 模型版本。可选值：speech-2.6-hd、speech-2.6-turbo |
text | string | 是 | — | 待合成文本，最大 10000 字符。超过 3000 字符建议使用流式输出 |
stream | boolean | 否 | false | 是否启用流式输出 |
stream_options | object | 否 | — | 流式输出选项，详见 4.4 StreamOptions |
voice_setting | object | 否 | — | 音色设置，详见 4.2 VoiceSetting |
audio_setting | object | 否 | — | 音频设置，详见 4.3 AudioSetting |
pronunciation_dict | object | 否 | — | 自定义发音词典，详见 4.5 PronunciationDict |
timbre_weights | array | 否 | — | 混合音色权重，详见 4.6 TimbreWeights |
language_boost | string | 否 | null | 语言增强，详见 4.8 语言增强 |
voice_modify | object | 否 | — | 音色变换，详见 4.7 VoiceModify |
subtitle_enable | boolean | 否 | false | 是否启用字幕服务 |
subtitle_type | string | 否 | sentence | 字幕粒度。可选值：sentence、word、word_streaming（仅流式） |
output_format | string | 否 | hex | 非流式输出格式。可选值：url（返回下载链接，24h有效）、hex（返回十六进制数据） |
aigc_watermark | boolean | 否 | false | 是否在音频末尾添加 AIGC 水印标识（仅非流式） |
参数名 | 类型 | 必填 | 默认值 | 说明 |
voice_id | string | 是 | — | 音色 ID。支持系统预置音色、克隆音色。混合音色模式下留空，改用 timbre_weights |
speed | float | 否 | 1 | 语速，范围 [0.5, 2]，1 为正常语速 |
vol | float | 否 | 1 | 音量，范围 (0, 10]，1 为正常音量 |
pitch | integer | 否 | 0 | 音调偏移，范围 [-12, 12]，0 为原始音调 |
emotion | string | 否 | — | 情感控制。可选值：happy、sad、angry、fearful、disgusted、surprised、calm、fluent、whisper。不设置时模型自动识别 |
text_normalization | boolean | 否 | false | 是否启用中英文文本规范化（数字读法等），会略微增加延迟 |
latex_read | boolean | 否 | false | 是否朗读 LaTeX 公式（仅中文），公式用 $$ 包裹，反斜杠需转义为 \\ |
音色 ID | 性别 | 风格描述 |
male-qn-qingse | 男 | 青涩 |
male-qn-jingying | 男 | 精英 |
male-qn-badao | 男 | 霸道 |
male-qn-daxuesheng | 男 | 大学生 |
female-shaonv | 女 | 少女 |
female-yujie | 女 | 御姐 |
female-chengshu | 女 | 成熟 |
female-tianmei | 女 | 甜美 |
参数名 | 类型 | 必填 | 默认值 | 说明 |
sample_rate | integer | 否 | 32000 | 采样率（Hz）。可选值：8000、16000、22050、24000、32000、44100 |
bitrate | integer | 否 | 128000 | 比特率（bps）。可选值：32000、64000、128000、256000。仅 mp3 有效 |
format | string | 否 | mp3 | 音频格式。可选值：mp3、pcm、flac、wav、pcmu_raw、pcmu_wav、opus |
channel | integer | 否 | 1 | 声道数。1 = 单声道，2 = 双声道 |
force_cbr | boolean | 否 | false | 是否强制恒定比特率编码，仅流式 mp3 有效 |
参数名 | 类型 | 必填 | 默认值 | 说明 |
exclude_aggregated_audio | boolean | 否 | false | 设为 true 时，最后一个数据块不包含拼接的完整音频 hex 数据，减少传输量 |
参数名 | 类型 | 必填 | 默认值 | 说明 |
tone | string[] | 否 | — | 自定义发音规则列表，格式为 原词/替换发音。支持 IPA 音标、拼音带声调（1-5）、纯文本替换。多条规则同时生效 |
示例：
{
"tone": [
"处理/(chu3)(li3)",
"危险/dangerous"
]
}最多支持 4 种音色混合。
参数名 | 类型 | 必填 | 说明 |
voice_id | string | 是 | 参与混合的音色 ID |
weight | integer | 是 | 该音色的权重，范围 [1, 100]。权重越高，合成结果越接近该音色 |
示例：
[
{ "voice_id": "male-qn-jingying", "weight": 70 },
{ "voice_id": "female-shaonv", "weight": 30 }
]对合成后的音频进行二次处理。非流式输出支持 mp3/wav/flac 格式；流式输出仅支持 mp3。
参数名 | 类型 | 必填 | 默认值 | 说明 |
pitch | integer | 否 | — | 音高偏移，范围 [-100, 100]。负值 = 低沉，正值 = 明亮 |
intensity | integer | 否 | — | 力度偏移，范围 [-100, 100]。负值 = 有力，正值 = 柔和 |
timbre | integer | 否 | — | 音色偏移，范围 [-100, 100]。负值 = 浑厚磁感，正值 = 清脆 |
sound_effects | string | 否 | — | 音效，每次请求仅可选一种。可选值：spacious_echo、auditorium_echo、lofi_telephone、robotic |
language_boost 参数可增强指定语言/方言的识别准确度。常用值如下：
可选值 | 说明 |
Chinese | 中文（普通话） |
Chinese,Yue | 中文 + 粤语 |
English | 英语 |
Japanese | 日语 |
Korean | 韩语 |
French | 法语 |
German | 德语 |
Spanish | 西班牙语 |
Russian | 俄语 |
Arabic | 阿拉伯语 |
auto | 自动识别 |
完整支持列表：Arabic、Bulgarian、Catalan、Chinese、Chinese,Yue、Croatian、Czech、Danish、Dutch、English、Filipino、Finnish、French、German、Greek、Hebrew、Hungarian、Indonesian、Italian、Japanese、Korean、Malay、Nynorsk、Persian、Polish、Portuguese、Romanian、Russian、Slovak、Slovenian、Spanish、Swedish、Thai、Turkish、Ukrainian、Vietnamese、auto。
在文本中插入 <#x#> 实现指定时长的停顿，x 为秒数（范围 0.01–99.99，最多两位小数）。
今天天气不错<#0.5#>适合出去走走，停顿标记必须位于可发音文本之间，不可连续使用。
在文本中直接标注发音，支持拼音（声调 1-5）、IPA 音标、粤语拼音（声调 1-6），用括号包裹。
处理(chu3li3) 危险(dangerous)
注意：金山云当前仅支持 speech-2.6 模型，暂不支持情感标记。以下内容供模型升级后参考。
标记 | 说明 |
(laughs) | 笑声 |
(chuckle) | 轻笑 |
(coughs) | 咳嗽 |
(sighs) | 叹气 |
(breath) | 呼吸 |
(gasps) | 喘息 |
(clear-throat) | 清嗓子 |
(groans) | 呻吟 |
(sniff) | 嗅 |
(snorts) | 哼 |
Content-Type: application/json
{
"data": {
"audio": "<hex 编码的音频数据>",
"status": 2
},
"extra_info": {
"audio_length": 9900,
"audio_sample_rate": 32000,
"audio_size": 160323,
"bitrate": 128000,
"word_count": 52,
"invisible_character_ratio": 0,
"usage_characters": 26,
"audio_format": "mp3",
"audio_channel": 1
},
"trace_id": "01b8bf9bb7433cc75c18eee6cfa8fe21",
"base_resp": {
"status_code": 0,
"status_msg": "success"
}
}字段 | 类型 | 说明 |
string | 十六进制编码的音频数据，与请求的格式一致 | |
data.status | integer | 合成状态：1 = 合成中（流式中间态），2 = 合成完成 |
data.subtitle_file | string | 字幕文件下载 URL（JSON格式），仅在 subtitle_enable=true 时返回 |
extra_info.audio_length | integer | 音频时长（毫秒） |
extra_info.audio_sample_rate | integer | 采样率（Hz） |
extra_info.audio_size | integer | 文件大小（字节） |
extra_info.bitrate | integer | 比特率（bps） |
extra_info.audio_format | string | 音频格式：mp3、pcm、flac |
extra_info.audio_channel | integer | 声道数：1 或 2 |
extra_info.invisible_character_ratio | float | 非法字符占比。≤10% 可接受；>10% 返回错误 |
extra_info.usage_characters | integer | 计费字符数 |
extra_info.word_count | integer | 实际发音字符数（不含标点） |
trace_id | string | 会话追踪 ID，用于问题排查 |
base_resp.status_code | integer | 状态码，详见第 7 章 |
base_resp.status_msg | string | 状态描述 |
流式模式下，接口分多次返回数据块：中间数据块 status=1（合成中），包含部分 hex 编码音频；最后一个数据块 status=2（合成完成），包含 extra_info 完整信息。客户端需按序拼接所有音频片段。
错误码 | 含义 | 处理建议 |
0 | 请求成功 | — |
1000 | 未知错误 | 联系技术支持，提供 trace_id |
1001 | 请求超时 | 检查文本长度，超长文本建议使用流式 |
1002 | 触发频率限制 | 降低请求频率，必要时联系商务提升配额 |
1004 | 鉴权失败 | 检查 API Key 是否正确、是否过期 |
1039 | 触发 TPM 限流 | 降低单分钟文本量 |
1042 | 非法字符超过 10% | 检查文本内容，移除不支持的特殊字符 |
2013 | 输入参数异常 | 检查请求体参数格式与取值范围 |
出现问题时，请将响应中的 trace_id 提供给金山云技术支持以便排查。
curl -X POST https://kspmas.ksyun.com/v1/t2a_v2 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer KSC_API_KEY' \
-d '{
"model": "speech-2.6-hd",
"text": "今天是不是很开心呀(laughs),当然了",
"stream": false,
"voice_setting": {
"voice_id": "male-qn-qingse",
"speed": 1,
"vol": 1,
"pitch": 0,
"emotion": "happy"
},
"audio_setting": {
"sample_rate": 32000,
"bitrate": 128000,
"format": "mp3",
"channel": 1
},
"pronunciation_dict": {
"tone": [
"处理/(chu3)(li3)",
"危险/dangerous"
]
},
"subtitle_enable": false
} curl -X POST https://kspmas.ksyun.com/v1/t2a_v2 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer KSC_API_KEY' \
-d '{
"model": "speech-2.6-hd",
"text": "金山云语音合成服务，为您提供高质量的文本转语音能力。",
"stream": true,
"voice_setting": {
"voice_id": "female-shaonv",
"speed": 1,
"vol": 1,
"pitch": 0
},
"audio_setting": {
"sample_rate": 32000,
"bitrate": 128000,
"format": "mp3",
"channel": 1
}
} import requests
API_KEY = "your_ksc_api_key"
URL = "https://kspmas.ksyun.com/v1/t2a_v2"
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}"
}
payload = {
"model": "speech-2.6-hd",
"text": "今天是不是很开心呀，当然了！",
"stream": False,
"voice_setting": {
"voice_id": "male-qn-qingse",
"speed": 1, "vol": 1, "pitch": 0,
"emotion": "happy"
},
"audio_setting": {
"sample_rate": 32000, "bitrate": 128000,
"format": "mp3", "channel": 1
},
"pronunciation_dict": {
"tone": ["处理/(chu3)(li3)", "危险/dangerous"]
},
"subtitle_enable": False
}
response = requests.post(URL, headers=headers, json=payload)
result = response.json()
if result["base_resp"]["status_code"] == 0:
audio_hex = result["data"]["audio"]
audio_bytes = bytes.fromhex(audio_hex)
with open("output.mp3", "wb") as f:
f.write(audio_bytes)
print(f"合成成功，时长: {result['extra_info']['audio_length']}ms")
else:
print(f"合成失败: {result['base_resp']['status_msg']}") import requests, json
API_KEY = "your_ksc_api_key"
URL = "https://kspmas.ksyun.com/v1/t2a_v2"
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}"
}
payload = {
"model": "speech-2.6-hd",
"text": "金山云语音合成服务，支持流式输出。",
"stream": True,
"voice_setting": {
"voice_id": "female-shaonv",
"speed": 1, "vol": 1, "pitch": 0
},
"audio_setting": {
"sample_rate": 32000, "bitrate": 128000,
"format": "mp3", "channel": 1
}
}
audio_buffer = bytearray()
with requests.post(URL, headers=headers, json=payload, stream=True) as resp:
for line in resp.iter_lines():
if line:
line_str = line.decode("utf-8")
if line_str.startswith("data:"):
data = json.loads(line_str[5:].strip())
if "data" in data and "audio" in data["data"]:
audio_buffer.extend(bytes.fromhex(data["data"]["audio"]))
if data["data"].get("status") == 2:
print(f"合成完成，计费字符数: {data['extra_info']['usage_characters']}")
with open("output_stream.mp3", "wb") as f:
f.write(audio_buffer)Q: 文本长度有限制吗？
A: 最大支持 10000 字符。超过 3000 字符建议使用流式输出，避免超时。
Q: 如何实现停顿效果？
A: 使用 <#x#> 标记，x 为停顿秒数（0.01–99.99）。例如 <#0.5#> 表示 0.5 秒停顿。
Q: 如何混合多种音色？
A: 使用 timbre_weights 参数，最多可混合 4 种音色，通过 weight 控制各音色占比。此时 voice_setting.voice_id 应留空。
Q: 流式和非流式如何选择？
A: 非流式适合文本较短（<3000字）、对首字延迟不敏感、需要完整音频文件的场景；流式适合文本较长（>3000字）、需要低首字延迟、实时播放的场景。
Q: 字幕功能如何使用？
A: 设置 subtitle_enable: true，响应中会返回 data.subtitle_file 字段，为字幕 JSON 文件的下载链接（24小时有效）。使用 subtitle_type 可控制字幕粒度。
Q: output_format 的 url 和 hex 有什么区别？
A: hex — 音频数据直接以十六进制字符串形式包含在响应体中；url — 响应中返回音频文件的下载链接（24小时有效），适合大文件场景。
纯净模式