输入关键词搜索

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}

    例如:

    textPOST /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 客户端推荐使用 Authorization Header。
  • 浏览器直连 WebSocket 无法自定义 Authorization Header 时,可在 Sec-WebSocket-Protocol 中携带 aihub-insecure-api-key.<sk> 作为兼容载体。
  • 前置 Nginx/Ingress/LB/CDN/WAF/access log 必须像处理 Authorization 一样对 Sec-WebSocket-Protocol 请求头脱敏或不记录完整值,避免 Key 在进入 AIHub Scrub 前泄漏。

事件流程

  1. 客户端发送 task_start,必须包含 model。
  2. 服务端返回 task_started。
  3. 客户端发送一个或多个 task_continue。
  4. 客户端发送 task_finish。
  5. 服务端返回 task_finished。
  6. 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。
此文档是否对你有帮助?
有帮助
去反馈
  • 概述
  • 服务地址
  • 请求信息
  • 请求头
  • 请求体
  • 响应信息
  • 错误码
  • 计费
  • 压缩
  • 接口列表
  • 语音合成 HTTP
  • 请求信息
  • 请求示例
  • 响应信息
  • 语音合成 WebSocket
  • 连接地址
  • 事件流程
  • 服务端事件
  • 音频上传
  • 请求信息
  • 响应信息
  • 音色复刻
  • 请求信息
  • 请求示例
  • 响应信息
  • 音色设计
  • 请求信息
  • 请求示例
  • 响应信息
  • 查询音色
  • 请求信息
  • 响应信息
  • 删除音色
  • 请求信息