本文档介绍如何使用魔芋 AI 的 MiniMax Speech 接口，包括语音合成（TTS）和语音识别（ASR）功能。

语音识别（ASR）

MiniMax 语音识别服务可将音频文件转换为文字，支持中英文等多种语言。

接口

POST /v1/audio/transcriptions
Content-Type: multipart/form-data

请求示例

curl -X POST https://your-domain/v1/audio/transcriptions \
  -H "Authorization: Bearer <令牌>" \
  -F "file=@/path/to/audio.mp3" \
  -F "model=asr-1.0"

请求参数

参数	类型	必填	说明
`file`	file	是	音频文件，支持 wav/aiff/flac/m4a/mp3/aac/opus/ogg 格式，最大 50MB，单次最长 500 秒
`model`	string	是	模型名称，目前支持 `asr-1.0`
`language`	string	否	语言代码，如 `zh`（中文）、`en`（英文），不填则自动检测
`prompt`	string	否	可选的上下文提示，帮助模型更准确识别特定词汇
`response_format`	string	否	响应格式：`json`（默认）/ `verbose_json` / `srt` / `vtt`
`temperature`	float	否	采样温度，范围 [0, 1]，默认 0

响应示例

JSON 格式（默认）：

{
  "text": "这是识别出的文字内容"
}

verbose_json 格式（包含说话人与分段时间轴）：

{
  "text": "这是识别出的文字内容",
  "duration": 5.2,
  "n_speakers": 1,
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 5.2,
      "speaker": "1",
      "text": "这是识别出的文字内容"
    }
  ],
  "trace_id": "xxxxx"
}

n_speakers 为识别出的说话人数；segments[] 按时间轴给出每段的起止时间、说话人与文本。

srt/vtt 格式：返回字幕文件格式（包含时间轴）

计费说明

语音识别按音频时长计费，单位为元/小时。

官方价格：2.5 元/小时（asr-1.0）
时长按整秒计费（小数部分截断，如 3.28 秒按 3 秒计）
示例：60 秒音频费用 = 60 ÷ 3600 × 2.5 = 0.042 元

语音合成（TTS）

MiniMax 语音合成服务可将文字转换为自然流畅的语音，支持同步合成、WebSocket 实时合成、异步长文本合成，以及音色管理功能。

鉴权

所有接口均需在请求头中携带令牌：

Authorization: Bearer <你的令牌>

一、同步语音合成（TTS）

接口

POST /v1/audio/speech
Content-Type: application/json

请求示例

curl -X POST https://your-domain/v1/audio/speech \
  -H "Authorization: Bearer <令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "speech-2.8-hd",
    "input": "今天是不是很开心呀(laughs)，当然了！",
    "voice": "male-qn-qingse",
    "response_format": "mp3"
  }' \
  --output output.mp3

请求参数

参数	类型	必填	说明
`model`	string	是	模型名称，见下方模型列表
`input`	string	是	待合成文本，最长 10000 字符
`voice`	string	是	音色 ID，系统音色见下方列表
`response_format`	string	否	音频格式：`mp3`（默认）/ `pcm` / `flac` / `wav` / `opus`
`speed`	float	否	语速，范围 [0.5, 2.0]，默认 1.0
`stream`	bool	否	是否流式返回，默认 false
`metadata`	object	否	扩展参数，见下方说明

metadata 扩展参数（可选，传入后会覆盖同名字段）：

{
  "voice_setting": {
    "voice_id": "male-qn-qingse",
    "speed": 1.0,
    "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
}

emotion 可选值：happy / sad / angry / fearful / disgusted / surprised / neutral

pronunciation_dict.tone 支持多种格式：

中文拼音注音：处理/(chu3)(li3)（数字代表声调，5 = 轻声）
IPA 音标：resume/(rɪˈzjuːm)
文本替换：omg/oh my god

文本特殊语法

停顿：<#1.5#> 表示停顿 1.5 秒
语气词（仅 speech-2.8 系列支持）：(laughs) 笑声，(sighs) 叹气，(coughs) 咳嗽等

响应

非流式时直接返回二进制音频数据（Content-Type 对应所选格式）。

流式（stream: true）时，服务端分块推送音频数据，客户端可边收边播。

二、WebSocket 实时语音合成

适合需要超低延迟、边输入边播放的场景，如实时对话、朗读助手等。

连接

GET /v1/ws/t2a_v2
Upgrade: websocket
Authorization: Bearer <令牌>

会话流程

客户端                        服务端
  │──── task_start ──────────────→│  发送合成参数（模型、音色等）
  │←─── task_started ────────────│  服务端确认，可以开始发送文本
  │──── task_continue ───────────→│  发送一段文本（可多次发送）
  │←─── task_continued ──────────│  返回对应音频（可能多条）
  │──── task_finish ─────────────→│  告知所有文本已发送完毕
  │←─── task_finished ───────────│  所有音频推送完成

task_start 消息

{
  "event": "task_start",
  "model": "speech-2.8-hd",
  "language_boost": "auto",
  "voice_setting": {
    "voice_id": "male-qn-qingse",
    "speed": 1.0,
    "vol": 1,
    "pitch": 0,
    "emotion": "happy"
  },
  "audio_setting": {
    "sample_rate": 32000,
    "bitrate": 128000,
    "format": "mp3",
    "channel": 1
  }
}

language_boost 可选值：auto（自动）/ zh（中文）/ en（英文）/ ja（日文）等。

task_continue 消息

{
  "event": "task_continue",
  "text": "这段文字会被合成为语音。"
}

可多次发送，文本会依序合成，音频按顺序推回。

task_finish 消息

{
  "event": "task_finish"
}

服务端返回的 task_continued 消息

{
  "data": {
    "audio": "<hex 编码的音频数据>",
    "status": 1
  },
  "is_final": false
}

is_final: true 表示本次 task 的最后一条音频。音频为 hex 编码，需在客户端解码为二进制后播放。

三、异步长文本语音合成

适合超长文本（最长 5 万字符）或通过上传文件（最大 100 万字符）批量合成。

建单

POST /v1/t2a_async_v2
Content-Type: application/json

curl -X POST https://your-domain/v1/t2a_async_v2 \
  -H "Authorization: Bearer <令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "speech-2.8-turbo",
    "text": "这是一段需要异步合成的长文本内容……",
    "voice_setting": {
      "voice_id": "male-qn-qingse",
      "speed": 1.0,
      "vol": 1,
      "pitch": 0
    },
    "audio_setting": {
      "audio_sample_rate": 32000,
      "format": "mp3",
      "channel": 1
    }
  }'

请求参数：

参数	类型	必填	说明
`model`	string	是	模型名称
`text`	string	text/text_file_id 二选一	待合成文本，最长 5 万字符
`text_file_id`	int	text/text_file_id 二选一	已上传的文本文件 ID
`voice_setting`	object	否	音色设置，同同步接口
`audio_setting`	object	否	音频设置，注意字段名是 `audio_sample_rate`
`language_boost`	string	否	语言增强，同 WebSocket 接口

建单成功响应：

{
  "id": "95157322514444",
  "task_id": "95157322514444",
  "status": "",
  "created_at": 1730000000
}

查询任务状态

GET /v1/t2a_async_v2/{task_id}

curl https://your-domain/v1/t2a_async_v2/95157322514444 \
  -H "Authorization: Bearer <令牌>"

响应示例：

{
  "code": "success",
  "data": {
    "task_id": "95157322514444",
    "status": "SUCCESS",
    "result_url": "https://...",
    "progress": "100%",
    "finish_time": 1730000060
  }
}

status 取值："" / SUCCESS / FAIL

result_url 在状态为 SUCCESS 时有值，有效期 9 小时，请及时下载保存。

四、音色管理

4.1 上传音频文件

上传音频，供快速复刻或音色设计使用。

POST /v1/tts/files/upload
Content-Type: multipart/form-data

curl -X POST https://your-domain/v1/tts/files/upload \
  -H "Authorization: Bearer <令牌>" \
  -F "purpose=voice_clone" \
  -F "file=@/path/to/audio.mp3"

参数	说明
`purpose`	`voice_clone`（复刻原始音频，10秒~5分钟，≤20MB）或 `prompt_audio`（示例音频，<8秒，≤20MB）
`file`	音频文件，支持 mp3 / m4a / wav

响应：

{
  "file": {
    "file_id": 123456789,
    "filename": "audio.mp3",
    "bytes": 1048576
  }
}

4.2 快速复刻音色

用自己的声音创建专属音色。

POST /v1/tts/voice_clone
Content-Type: application/json

curl -X POST https://your-domain/v1/tts/voice_clone \
  -H "Authorization: Bearer <令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": 123456789,
    "voice_id": "MyVoice001",
    "text": "这是试听文本",
    "model": "speech-2.8-hd"
  }'

参数	类型	必填	说明
`file_id`	int	是	上传音频返回的 file_id
`voice_id`	string	是	自定义音色 ID，长度 8~256，首字母须为英文字母，允许字母/数字/-/_
`text`	string	否	试听文本，有值时 `model` 必填
`model`	string	text 非空时必填	试听使用的合成模型

响应：

{
  "demo_audio": "https://..."
}

demo_audio 是试听音频的 URL。

注意：音色创建后需在 7 天内调用合成接口使用一次，否则音色将被自动删除。

4.3 音色设计

通过文字描述生成音色，无需提供音频样本。

POST /v1/tts/voice_design
Content-Type: application/json

curl -X POST https://your-domain/v1/tts/voice_design \
  -H "Authorization: Bearer <令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "讲述悬疑故事的播音员，声音低沉富有磁性，语速时快时慢，营造紧张神秘的氛围。",
    "preview_text": "夜深了，古屋里只有他一人……"
  }'

参数	类型	必填	说明
`prompt`	string	是	音色描述，越详细效果越好
`preview_text`	string	是	试听文本
`voice_id`	string	否	自定义音色 ID（格式同快速复刻），不填则系统自动生成

响应：

{
  "voice_id": "ttv-voice-xxxxxxxx",
  "trial_audio": "<hex 编码音频>"
}

trial_audio 是 hex 编码的试听音频，解码后可直接播放。

4.4 查询可用音色

POST /v1/tts/get_voice
Content-Type: application/json

curl -X POST https://your-domain/v1/tts/get_voice \
  -H "Authorization: Bearer <令牌>" \
  -H "Content-Type: application/json" \
  -d '{"voice_type": "all"}'

`voice_type`	说明
`all`	全部音色
`system`	系统预置音色（300+ 种）
`voice_cloning`	通过快速复刻创建的音色
`voice_generation`	通过音色设计创建的音色

4.5 删除音色

只能删除自己创建的音色（快速复刻或音色设计），系统音色不可删除。

POST /v1/tts/delete_voice
Content-Type: application/json

curl -X POST https://your-domain/v1/tts/delete_voice \
  -H "Authorization: Bearer <令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_type": "voice_cloning",
    "voice_id": "MyVoice001"
  }'

`voice_type`	说明
`voice_cloning`	快速复刻创建的音色
`voice_generation`	音色设计创建的音色

五、可用模型

模型	特点
`speech-2.8-hd`	最新 HD 模型，情绪渲染自然，支持语气词标签
`speech-2.8-turbo`	最新 Turbo 模型，极致速度，延迟更低
`speech-2.6-hd`	HD 模型，音质与韵律俱佳
`speech-2.6-turbo`	Turbo 模型，音质优异，响应迅速
`speech-02-hd`	经典 HD 模型，稳定性高
`speech-02-turbo`	经典 Turbo 模型

六、部分常用系统音色

音色 ID	描述
`male-qn-qingse`	青涩青年音色
`female-shaonv`	少女音色
`male-qn-jingying`	精英青年音色
`female-yujie`	御姐音色
`audiobook_male_1`	有声书男声1
`audiobook_female_1`	有声书女声1
`Chinese (Mandarin)_Lyrical_Voice`	普通话抒情女声

完整音色列表可通过查询可用音色接口获取。

七、错误码

错误码	说明
`model_not_found`	模型未找到或无可用渠道
`bad_response`	请求参数有误（如文本为空、音色不存在等）
`insufficient_user_quota`	账户余额不足
`invalid_token`	令牌无效

八、注意事项

语音模型限制：同步合成单次最长 10000 字符；WebSocket 支持多轮发送；异步合成最长 5 万字符（文件上传最大 100 万字符）。
流式合成：流式下音频格式仅支持 mp3；stream_format: "sse" 与 stream: true 效果相同。
自定义音色保活：通过快速复刻或音色设计创建的音色，7 天内必须调用合成接口使用一次，否则会被自动删除。
异步任务结果：异步合成完成后的下载链接有效期为 9 小时，请及时下载到自己的存储空间。
发音替换：pronunciation_dict 支持拼音、IPA、文本替换三种模式，多条规则同时生效，适合处理生僻字、品牌名等特殊词汇。

MiniMax Speech API 文档

目录

语音识别（ASR）

接口

请求示例

请求参数

响应示例

计费说明

语音合成（TTS）

鉴权

一、同步语音合成（TTS）

接口

请求示例

请求参数

文本特殊语法

响应

二、WebSocket 实时语音合成

连接

会话流程

task_start 消息

task_continue 消息

task_finish 消息

服务端返回的 task_continued 消息

三、异步长文本语音合成

建单

查询任务状态

四、音色管理

4.1 上传音频文件

4.2 快速复刻音色

4.3 音色设计

4.4 查询可用音色

4.5 删除音色

五、可用模型

六、部分常用系统音色

七、错误码

八、注意事项