MiniMax TTS
更新时间: 2026/10/14 16:29:34
本文主要介绍云信大模型 API 服务(以下简称 AIHub)对 MiniMax TTS 相关能力的对接方式。
概述
AIHub 对 MiniMax TTS 相关能力进行了 Provider-native 封装。业务方使用 AIHub 下发的 Key 调用,网关负责鉴权、模型授权、路由、上游凭证注入、用量解析和计费;请求体和成功响应保持 MiniMax 原生结构。
服务地址
网易云信服务提供的公网入口为:https://ai.yunxinapi.com/hub
-
网关服务内部注册的数据面路径为:
/minimax/v1/{action}例如:
text
POST /minimax/v1/t2a_v2 POST /minimax/v1/files/upload POST /minimax/v1/voice_clone -
公网调用采用直连网关方式,对外路径:
https://ai.yunxinapi.com/hub/minimax/v1/*即,公网入口不挂额外前缀,直接使用
/minimax/v1/*。
请求信息
云信服务端 API 请求结构主要由下表所示三部分组成。
| 组成部分 | 说明 |
|---|---|
| URL | 指向具体的业务请求,遵循 RESTful 原则围绕资源定义接口路径。 |
| Header | 请求头,数据面统一使用 Bearer Key 鉴权。 |
| Body | 请求体,包含 API 对应的业务参数,具体参考各 API 文档的 请求信息 小节。 |
请求头
调用云信服务端 API 时,必须使用 AIHub Key 进行鉴权,不可使用 MiniMax 原始 API Key。
httpAuthorization: Bearer sk-xxxxx
常用请求头:
| Header | 必填 | 说明 |
|---|---|---|
Authorization |
是 | Bearer <sk-...> |
Content-Type |
POST 时是 |
建议固定为 application/json; charset=utf-8,避免中文 prompt 等 UTF-8 内容解析异常。 |
请求体
传入请求体(Body)的 具体业务参数。
网关不会重塑业务字段结构。
响应信息
成功响应保持 MiniMax 原生结构,通常包含 base_resp。
JSON{
"base_resp": {
"status_code": 0,
"status_msg": "success"
}
}
base_resp.status_code=0 表示上游业务成功。若 HTTP 状态码为 200 但 base_resp.status_code 非 0,AIHub 会按上游业务失败记录审计和计费失败事件,并将原始响应返回给业务方。
错误码
AIHub 网关层错误遵循错误响应格式与错误码。MiniMax 上游业务错误会保留原生 base_resp 返回体,业务方应同时检查 HTTP 状态码和 base_resp.status_code。
计费
- TTS HTTP 非流式、HTTP 流式、WSS 和触发试听合成的音色接口,均按 MiniMax 返回的
usage_characters计费。 - WSS 成功结束时,业务方会先收到
task_finished业务事件,随后收到 WebSocket 协议层1000正常关闭帧。
压缩
业务方不需要主动设置 Accept-Encoding。AIHub 会处理 MiniMax 上游 gzip 响应,避免压缩响应影响 base_resp 和 usage_characters 解析。
接口列表
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /minimax/v1/t2a_v2 |
同步语音合成 HTTP,支持非流式和 SSE 流式 |
| WSS | /minimax/ws/v1/t2a_v2 |
同步语音合成 WebSocket |
| POST | /minimax/v1/files/upload |
上传复刻音频或示例音频 |
| POST | /minimax/v1/voice_clone |
音色快速复刻 |
| POST | /minimax/v1/voice_design |
音色设计 |
| POST | /minimax/v1/get_voice |
查询可用音色 |
| POST | /minimax/v1/delete_voice |
删除音色 |
语音合成 HTTP
请求信息
POST /minimax/v1/t2a_v2
Authorization: Bearer sk-xxxxx
Content-Type: application/json; charset=utf-8
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | MiniMax TTS 模型,例如 speech-2.8-hd、speech-2.8-turbo。 |
| text | string | 是 | 待合成文本,小于 10000 字符。 |
| stream | boolean | 否 | 是否使用 SSE 流式输出,默认 false。 |
| stream_options.exclude_aggregated_audio | boolean | 否 | 最后一个 chunk 是否不包含聚合后的完整音频。 |
| voice_setting | object | 否 | 音色、语速、音量、音调、情绪等。 |
| audio_setting | object | 否 | 采样率、码率、格式、声道等。 |
| pronunciation_dict.tone | string[] | 否 | 发音替换规则。 |
| language_boost | string | 否 | 小语种/方言增强。 |
| subtitle_enable | boolean | 否 | 是否生成字幕文件链接。 |
请求示例
非流式:
curl -sS 'https://ai.yunxinapi.com/hub/minimax/v1/t2a_v2' \
-H 'Authorization: Bearer sk-xxxxx' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
"model": "speech-2.8-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
}
}'
流式:
curl -N -sS 'https://ai.yunxinapi.com/hub/minimax/v1/v1/t2a_v2' \
-H 'Authorization: Bearer sk-xxxxx' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
"model": "speech-2.8-turbo",
"text": "流式语音合成测试。",
"stream": true,
"voice_setting": {
"voice_id": "male-qn-qingse",
"speed": 1,
"vol": 1,
"pitch": 0
},
"audio_setting": {
"sample_rate": 32000,
"bitrate": 128000,
"format": "mp3",
"channel": 1
}
}'
响应信息
非流式(成功 HTTP 状态码 200):
JSON{
"data": {
"audio": "<hex-audio>",
"status": 2
},
"extra_info": {
"audio_length": 7349,
"audio_sample_rate": 32000,
"audio_size": 120372,
"bitrate": 128000,
"word_count": 28,
"invisible_character_ratio": 0,
"usage_characters": 54,
"audio_format": "mp3",
"audio_channel": 1
},
"trace_id": "06913742bcbf287cea848df6ee4d51d9",
"base_resp": {
"status_code": 0,
"status_msg": "success"
}
}
| 字段 | 类型 | 说明 |
|---|---|---|
| data.audio | string | hex 编码音频。 |
| data.status | integer | 2 表示合成结束。 |
| extra_info.usage_characters | integer | 计费字符数。 |
| extra_info.audio_length | integer | 音频时长,毫秒。 |
| extra_info.audio_sample_rate | integer | 音频采样率。 |
| extra_info.audio_size | integer | 音频文件大小,字节。 |
| extra_info.audio_format | string | 音频格式。 |
| trace_id | string | 上游 trace id。 |
| base_resp | object | 上游状态码与详情。 |
流式:
流式响应为 text/event-stream。每个 data: chunk 内部仍是 MiniMax 原生 JSON,最后一个包含 extra_info.usage_characters 的 chunk 用于计费。
语音合成 WebSocket
连接地址
textwss://ai.yunxinapi.com/hub/minimax/ws/v1/t2a_v2
Authorization: Bearer sk-xxxxx
鉴权方式:
- 服务端/SDK 客户端推荐使用
AuthorizationHeader。 - 浏览器直连 WebSocket 无法自定义
AuthorizationHeader 时,可在Sec-WebSocket-Protocol中携带aihub-insecure-api-key.<sk>作为兼容载体。 - 前置 Nginx/Ingress/LB/CDN/WAF/access log 必须像处理
Authorization一样对Sec-WebSocket-Protocol请求头脱敏或不记录完整值,避免 Key 在进入 AIHub Scrub 前泄漏。
事件流程
- 客户端发送
task_start,必须包含model。 - 服务端返回
task_started。 - 客户端发送一个或多个
task_continue。 - 客户端发送
task_finish。 - 服务端返回
task_finished。 - AIHub 发送 WebSocket
1000正常关闭帧并结束连接。
task_start
{
"event": "task_start",
"model": "speech-2.8-turbo",
"voice_setting": {
"voice_id": "male-qn-qingse",
"speed": 1,
"vol": 1,
"pitch": 0
},
"audio_setting": {
"sample_rate": 32000,
"bitrate": 128000,
"format": "mp3",
"channel": 1
}
}
task_continue
{
"event": "task_continue",
"text": "真正的危险不是计算机开始像人一样思考,而是人开始像计算机一样思考。"
}
task_finish
{
"event": "task_finish"
}
服务端事件
| 事件 | 说明 | 关键字段 |
|---|---|---|
| connected_success | 连接建立成功 | session_id、trace_id、base_resp |
| task_started | 任务开始成功 | session_id、trace_id、base_resp |
| task_continued | 返回音频 chunk 或最终 usage | data.audio、is_final、extra_info.usage_characters、base_resp |
| task_finished | 任务结束成功 | session_id、trace_id、base_resp |
| task_failed | 任务失败 | session_id、trace_id、base_resp |
task_continued.data.audio 是 Hex 编码音频片段。is_final=true 的 task_continued 通常包含 extra_info.usage_characters,AIHub 用该字段计费。
wscat 示例:
npx wscat -c wss://ai.yunxinapi.com/hub/minimax/v1/t2a_v2 \
-H 'Authorization: Bearer sk-xxxxx'
连接后依次发送 task_start、task_continue、task_finish 三类 JSON 消息。正常结束时,客户端应看到 task_finished,随后连接以 1000 正常关闭。
音频上传
/minimax/v1/files/upload 使用 multipart/form-data。
请求信息
上传复刻音频:
curl -sS 'https://ai.yunxinapi.com/hub/minimax/v1/files/upload' \
-H 'Authorization: Bearer sk-xxxxx' \
-F 'purpose=voice_clone' \
-F 'file=@/path/to/source.wav'
上传示例音频:
curl -sS 'https://ai.yunxinapi.com/hub/minimax/v1/files/upload' \
-H 'Authorization: Bearer sk-xxxxx' \
-F 'purpose=prompt_audio' \
-F 'file=@/path/to/prompt.wav'
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| purpose | string | 是 | voice_clone 或 prompt_audio。 |
| file | binary | 是 | 音频文件。 |
文件要求(以 MiniMax 原生规则为准):
- 格式:mp3、m4a、wav
- 大小:不超过 20 MB
voice_clone音频时长:通常要求 10 秒至 5 分钟prompt_audio示例音频时长:通常要求小于 8 秒
响应信息
{
"file": {
"file_id": 413270788837790,
"bytes": 93300,
"created_at": 1782450562,
"filename": "source.wav",
"purpose": "voice_clone"
},
"base_resp": {
"status_code": 0,
"status_msg": "success"
}
}
音色复刻
请求信息
POST /minimax/v1/voice_clone
Authorization: Bearer sk-xxxxx
Content-Type: application/json; charset=utf-8
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| file_id | integer | 是 | files/upload 返回的文件 ID。 |
| voice_id | string | 是 | 自定义音色 ID。 |
| clone_prompt.prompt_audio | integer | 否 | 示例音频文件 ID。 |
| clone_prompt.prompt_text | string | 否 | 示例音频文本。 |
| text | string | 否 | 复刻试听文本;传入后会触发试听合成并计费。 |
| model | string | 传 text 时是 |
试听合成使用的 TTS 模型。 |
| language_boost | string | 否 | 小语种/方言增强。 |
| text_validation | string | 否 | 音频预期文本。 |
| accuracy | number | 否 | 相似度阈值。 |
| need_noise_reduction | boolean | 否 | 是否开启降噪。 |
| need_volume_normalization | boolean | 否 | 是否开启音量归一化。 |
请求示例
{
"file_id": 413270788837790,
"voice_id": "custom_voice_001",
"text": "这是一段试听文本。",
"model": "speech-2.8-turbo"
}
响应信息
| 字段 | 类型 | 说明 |
|---|---|---|
| input_sensitive | object | 输入音频风控结果。 |
| demo_audio | string | 试听音频链接;未传试听文本时为空。 |
| extra_info | object | 试听合成 usage;仅触发试听时返回。 |
| base_resp | object | 上游状态码与详情。 |
音色设计
请求信息
POST /minimax/v1/voice_design
Authorization: Bearer sk-xxxxx
Content-Type: application/json; charset=utf-8
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| prompt | string | 是 | 音色描述。 |
| preview_text | string | 是 | 试听文本;会触发试听合成并计费。 |
| voice_id | string | 否 | 自定义生成音色 ID。 |
| aigc_watermark | boolean | 否 | 是否添加音频节奏标识。 |
请求示例
{
"prompt": "讲述悬疑故事的播音员,声音低沉富有磁性。",
"preview_text": "夜深了,古屋里只有他一人。"
}
响应信息
{
"voice_id": "generated_voice_001",
"trial_audio": "<hex-audio>",
"base_resp": {
"status_code": 0,
"status_msg": "success"
}
}
查询音色
请求信息
curl -sS 'https://ai.yunxinapi.com/hub/minimax/v1/get_voice' \
-H 'Authorization: Bearer sk-xxxxx' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{"voice_type":"all"}'
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| voice_type | string | 是 | system、voice_cloning、voice_generation、all。 |
响应信息
响应包含 system_voice、voice_cloning、voice_generation 等音色列表字段。
快速复刻得到的音色需要正式调用一次激活后,才会在查询结果中出现。
删除音色
仅支持删除通过音色快速复刻或音色设计生成的音色。删除后,该 voice_id 无法再次使用。
请求信息
curl -sS 'https://ai.yunxinapi.com/hub/minimax/v1/delete_voice' \
-H 'Authorization: Bearer sk-xxxxx' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
"voice_type": "voice_cloning",
"voice_id": "custom_voice_001"
}'
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| voice_type | string | 是 | voice_cloning 或 voice_generation。 |
| voice_id | string | 是 | 需要删除的音色 ID。 |




