本文介绍网易云信大模型 API（简称 AIHub）与 MiniMax 厂商兼容 的同步文本转语音接口的使用说明。

AIHub 通过 MiniMax Provider-native 入口提供同步文本转语音能力。接口支持非流式 JSON 和 SSE 流式输出，请求参数与成功响应保持 MiniMax 原生结构；业务方使用 AIHub API Key 和 AIHub Logical Model，网关负责鉴权、模型授权、路由、上游凭证注入、用量解析和计费。

请求说明

AIHub 入口：

POST https://ai.yunxinapi.com/hub/minimax/v1/t2a_v2

• 请勿 将 MiniMax 原厂 API Key 发送到 AIHub。
• AIHub 根据 Logical Model 选择 MiniMax Channel，并在出站前注入对应的上游凭证和上游模型。

请求参数

Header 参数

参数	必填	说明	示例
Authorization	必填	AIHub API Key Bearer 鉴权	Bearer <AIHUB_API_KEY>
Content-Type	必填	请求体必须为 JSON	application/json
Accept	流式建议	stream: true 时可显式声明 SSE	text/event-stream

记录 AIHub Request ID 和响应中的 trace_id，不要 记录 API Key 或完整音频正文。

Body 参数

参数	类型	必填/默认值	说明	示例
model	string	必填	AIHub Logical Model，AIHub 校验授权后按路由配置改写为上游 MiniMax 模型	"speech-2.8-hd"
text	string	必填	待合成文本，必须 少于 10000 个字符；超过 3000 字符时建议使用流式输出	"真正的危险不是计算机开始像人一样思考。"
stream	boolean	可选，默认 false	false：返回 JSON；true：返回 text/event-stream	true
- stream_options	object	流式可选	控制最终 Chunk 是否携带聚合后的完整音频	{"exclude_aggregated_audio":true}
exclude_aggregated_audio	boolean	可选，默认 false	false：最终 status: 2 Chunk 包含完整聚合音频；true：最终 Chunk 不再重复完整音频。长音频建议设为 true 默认值为 false 时，不能 将前序增量音频与最终完整音频直接拼接，否则会得到重复内容。客户端应 只使用最终 Chunk 的完整音频，或设置 exclude_aggregated_audio: true 后拼接前序增量 Chunk。	true
- voice_setting	object	可选	音色合成配置。单音色需提供 voice_id；混合音色时将 voice_id 置空并传 timbre_weights	{"voice_id":"English_expressive_narrator"}
voice_id	string	单音色必填	系统音色、复刻音色或文生音色 ID；混合音色时置空	"English_expressive_narrator"
speed	number	可选，默认 1	语速范围 [0.5, 2]	1.05
vol	number	可选，默认 1	音量范围 (0, 10]	1
pitch	integer	可选，默认 0	音调范围 [-12, 12]，0 表示原音调	0
emotion	string	可选	happy、sad、angry、fearful、disgusted、surprised、calm、fluent、whisper。模型默认按文本自动选择，仅明确需要时传入 fluent 和 whisper 仅对 Speech 2.6 生效；Speech 2.8 不支持 whisper。其他 Emotion 是否达到预期取决于模型、音色和文本。	"happy"
text_normalization	boolean	可选，默认 false	中文/英文文本规范化，可改善数字朗读，但略微增加延迟	true
latex_read	boolean	可选，默认 false	朗读 $$...$$ 包裹的 LaTeX；仅支持中文，开启后 language_boost 被设为 Chinese	true
- audio_setting	object	可选	采样率、码率、封装格式、声道和流式 CBR 配置 编码说明：pcmu_raw/pcmu_wav：8 kHz G.711 mu-law 编码；前者为裸数据，后者封装在 WAV 容器中。opus：Ogg/Opus 编码。	{"sample_rate":32000,"format":"mp3"}
sample_rate	integer	可选，默认 32000	8000、16000、22050、24000、32000、44100	32000
bitrate	integer	可选，默认 128000	32000、64000、128000、256000；仅对 mp3 生效	128000
format	string	可选，默认 mp3	mp3、pcm、flac、wav、pcmu_raw、pcmu_wav、opus	"mp3"
channel	integer	可选，默认 1	1 单声道，2 双声道	1
force_cbr	boolean	可选，默认 false	恒定比特率编码；仅流式 mp3 输出时生效	true
pronunciation_dict	object	可选	自定义发音替换规则	{"tone":["处理/(chu3)(li3)"]}
timbre_weights	object[]	可选（旧字段）	混合最多 4 个音色；每项同时提供 voice_id 和 weight	[{"voice_id":"female-chengshu","weight":30}]
language_boost	string	可选，默认 null	增强指定语言或方言；语言未知时可传 auto	"Chinese,Yue"
- voice_modify	object	可选	变声参数和单个音效。仅支持非流式 mp3/wav/flac，或流式 mp3	{"pitch":10,"sound_effects":"spacious_echo"}
pitch	integer	可选	音高范围 [-100, 100]；负值更低沉，正值更明亮	10
intensity	integer	可选	强度范围 [-100, 100]；负值更有力量，正值更柔和	-10
timbre	integer	可选	音色范围 [-100, 100]；负值更浑厚，正值更清脆	5
sound_effects	string	可选	单次仅选一个：spacious_echo、auditorium_echo、lofi_telephone、robotic	"spacious_echo"
subtitle_enable	boolean	可选，默认 false	是否生成字幕下载链接；2.8、2.6、02、01 系列均支持	true
subtitle_type	string	可选，默认 sentence	字幕粒度：sentence、word、word_streaming；后者仅 stream: true 时有效	"word_streaming"
output_format	string	可选，默认 hex	hex 或 url。仅非流式支持 url（有效期 24 小时）；流式固定 hex	"url"

发音与混合音色：

参数	类型	必填	说明	示例
pronunciation_dict.tone	string[]	可选	格式 原文/替换内容，支持拼音（带声调数字）、IPA、日语假名/罗马音；多条规则同时生效	["resume/(rɪˈzjuːm)","20日/はつか"]
timbre_weights[].voice_id	string	混合项必填	参与混合的音色 ID	"female-chengshu"
timbre_weights[].weight	integer	混合项必填	范围 [1, 100]，值越高越接近该音色；最多混合 4 个	70

混合音色示例：

json{
  "voice_setting": {
    "voice_id": ""
  },
  "timbre_weights": [
    {"voice_id": "female-chengshu", "weight": 30},
    {"voice_id": "female-tianmei", "weight": 70}
  ]
}

请求示例

非流式 Hex 输出

bashcurl -sS "https://ai.yunxinapi.com/hub/minimax/v1/t2a_v2" \
  -H "Authorization: Bearer <AIHUB_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "speech-2.8-hd",
    "text": "今天是不是很开心呀(laughs)，当然了！",
    "stream": false,
    "output_format": "hex",
    "language_boost": "Chinese",
    "voice_setting": {
      "voice_id": "Chinese (Mandarin)_Lyrical_Voice",
      "speed": 1,
      "vol": 1,
      "pitch": 0,
      "emotion": "happy"
    },
    "pronunciation_dict": {
      "tone": ["处理/(chu3)(li3)"]
    },
    "audio_setting": {
      "sample_rate": 32000,
      "bitrate": 128000,
      "format": "mp3",
      "channel": 1
    }
  }'

响应中的 data.audio 是十六进制字符串，每两个 Hex 字符表示一个字节。写文件前 必须先解码，不要 将字符串本身当作 MP3 文本直接保存。

非流式 URL 输出

json{
  "stream": false,
  "output_format": "url"
}

MiniMax 返回的 URL 有效期为 24 小时。调用方应及时下载并转存到自有受控存储，不要 依赖该 URL 作为长期资源地址。

SSE 流式输出

bashcurl --no-buffer -sS \
  "https://ai.yunxinapi.com/hub/minimax/v1/t2a_v2" \
  -H "Authorization: Bearer <AIHUB_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "speech-2.8-turbo",
    "text": "流式语音合成测试。第一段生成后即可开始播放。",
    "stream": true,
    "stream_options": {
      "exclude_aggregated_audio": true
    },
    "output_format": "hex",
    "voice_setting": {
      "voice_id": "English_expressive_narrator",
      "speed": 1,
      "vol": 1,
      "pitch": 0
    },
    "audio_setting": {
      "sample_rate": 32000,
      "bitrate": 128000,
      "format": "mp3",
      "channel": 1,
      "force_cbr": true
    }
  }'

非流式响应

响应参数

参数	类型	说明
data	object/null	合成结果。官网明确提示可能为 null，访问子字段前 必须判空
data.audio	string	Hex 编码音频；output_format: "url" 时为 URL 字符串
data.subtitle_file	string	字幕后返回的 JSON 字幕下载链接，时间戳单位为毫秒；句级字幕单句不超过 50 字
data.status	integer	1 合成中，2 合成结束；非流式成功通常为 2
extra_info.audio_length	integer	音频时长（毫秒）
extra_info.audio_sample_rate	integer	实际采样率
extra_info.audio_size	integer	音频大小（字节）
extra_info.bitrate	integer	实际比特率
extra_info.word_count	integer	已发音字符统计（含汉字、数字、字母，不含标点）
extra_info.invisible_character_ratio	number	非法字符占比；≤10% 时生成音频，>10% 时失败
extra_info.usage_characters	integer	本次计费字符数。AIHub 优先使用该值；缺失时按 text 估算并标记 usage_source: estimated
extra_info.audio_format	string	音频格式（mp3、pcm、flac）
extra_info.audio_channel	integer	1 单声道，2 双声道
trace_id	string	MiniMax 会话 ID，用于上游排障
base_resp.status_code	integer	MiniMax 业务状态码，0 表示成功
base_resp.status_msg	string	MiniMax 业务状态说明

成功响应示例

json{
  "data": {
    "audio": "<HEX_ENCODED_AUDIO>",
    "status": 2
  },
  "extra_info": {
    "audio_length": 11124,
    "audio_sample_rate": 32000,
    "audio_size": 179926,
    "bitrate": 128000,
    "word_count": 163,
    "invisible_character_ratio": 0,
    "usage_characters": 163,
    "audio_format": "mp3",
    "audio_channel": 1
  },
  "trace_id": "01b8bf9bb7433cc75c18eee6cfa8fe21",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

SSE 流式响应

stream: true 时响应 Content-Type 为 text/event-stream。每个 data: 行后为 MiniMax 原生 JSON 对象（非 OpenAI Chat Completions Chunk，无 event: 事件名要求）。

textdata: {"data":{"audio":"<HEX_CHUNK_1>","status":1},"trace_id":"trace_example","base_resp":{"status_code":0,"status_msg":""}}

data: {"data":{"audio":"<HEX_CHUNK_2>","status":1},"trace_id":"trace_example","base_resp":{"status_code":0,"status_msg":""}}

data: {"data":{"audio":"","status":2},"extra_info":{"audio_length":5863,"usage_characters":45,"audio_format":"mp3"},"trace_id":"trace_example","base_resp":{"status_code":0,"status_msg":"success"}}

客户端处理规则

规则	说明
解析方式	按 SSE 行解析 data:，不要 假设一次网络读取恰好对应一个完整事件
增量音频（status: 1）	对 data.audio 做 Hex 解码并按顺序写入音频流
终止 Chunk（status: 2）	携带 extra_info.usage_characters 和最终 base_resp。处理完后 立即结束，不要 等待 [DONE] 或连接 EOF
exclude_aggregated_audio: true	以前序 Chunk 拼接结果为完整音频；最终 Chunk 的 data.audio 可为空
exclude_aggregated_audio: false（默认）	最终 Chunk 可能再次携带完整聚合音频；应在“使用最终完整音频”和“拼接前序增量音频”之间 二选一
异常处理	收到 base_resp.status_code != 0、连接异常或未收到终止 Chunk 时，不要 视为完整成功

文本控制

换行、停顿和行内发音

控制方式	说明	示例
换行符	段落切换	第一段\n第二段
停顿标记	<#x#>，x 范围 [0.01, 99.99] 秒，最多两位小数。必须位于两个可发音文本片段之间，不能 连续使用	请稍等<#0.8#>马上开始。
IPA/拼音	半角括号中写 IPA，或使用 1-5 表示普通话声调、1-6 表示粤语声调	(lɪv)、(he2)平、(sung3)

示例：

text请稍等<#0.8#>马上开始。
This word is pronounced (lɪv), not (laɪv).
这是(he2)平，不是(huo4)面。
去街市買啲(sung3)。

Speech 2.8 语气词标签

Speech 2.8 HD/Turbo 支持以下文本内标签：

(laughs)、(chuckle)、(coughs)、(clear-throat)、(groans)、(breath)、(pant)、(inhale)、(exhale)、(gasps)、(sniffs)、(sighs)、(snorts)、(burps)、(lip-smacking)、(humming)、(hissing)、(emm)、(sneezes)

这些标签是 文本内容的一部分，不要 放入 voice_setting.emotion。

language_boost 可选值

Chinese、Chinese,Yue、English、Arabic、Russian、Spanish、French、Portuguese、German、Turkish、Dutch、Ukrainian、Vietnamese、Indonesian、Japanese、Italian、Korean、Thai、Polish、Romanian、Greek、Czech、Finnish、Hindi、Bulgarian、Danish、Hebrew、Malay、Persian、Slovak、Swedish、Croatian、Filipino、Hungarian、Norwegian、Slovenian、Catalan、Nynorsk、Tamil、Afrikaans、auto

语言未知时使用 auto。Speech 01/02 暂不支持 Persian、Filipino、Tamil。

AIHub 行为与限制

行为	说明
Provider-native 路径	/minimax/v1/t2a_v2 为 MiniMax 原生路径。AIHub 保留请求字段和成功响应结构，不 转换为 OpenAI Audio API
模型改写	请求中的 model 用于授权和路由，出站时可改写为 Channel 配置的上游模型
业务成功判断	HTTP 200 不等于 业务成功。base_resp.status_code: 0 才表示 MiniMax 业务成功
常见业务错误码	1000 未知错误、1001 超时、1002 限流、1004 鉴权失败、1039 TPM 限流、1042 非法字符 >10%、2013 参数错误
响应处理	AIHub 处理 MiniMax 上游 Gzip 响应，调用方无需 设置 Accept-Encoding
请求体限制	JSON 请求体默认 32 MiB，普通 TTS 请求通常远低于此
SSE 行限制	每个 data: 行上限 10 MiB。长音频应设置 stream_options.exclude_aggregated_audio: true，避免最终 Chunk 超限
日志安全	data.audio Hex 内容、临时 URL、字幕 URL 和待合成文本均可能包含敏感信息。只记录 Request ID、trace_id、状态码和脱敏资源 ID

错误处理要点

• 非流式错误：使用 AIHub 统一错误响应。
• 流式错误：一旦开始发送，后续失败可能仅表现为 SSE 中断或 MiniMax 原生失败 Frame。客户端 必须同时处理 HTTP 状态、base_resp 和流是否完整结束。