MiniMax 音频接口接入说明

语音合成、音色设计、音色克隆及音色资源管理

1. 概述

本接口用于语音合成、音色设计、音色克隆，以及异步任务和音色资源管理。

完整请求地址由 {baseUrl} 与接口路径拼接；请求和响应均使用 JSON。

分类 ER 地址 用途
生成及计费动作 POST {baseUrl}/audio/generations/{apiType} 语音合成、音色设计、音色克隆
资源动作 POST {baseUrl}/audio/resource-actions/{apiType} 异步任务、音色查询与删除

模型选择：请求体中的 model 填写已开通的 MiniMax 音频模型编码。

2. 接入前置条件

项 说明
api_key 访问密钥（控制台生成），用于 Bearer 鉴权。
model 已在平台开通的 MiniMax 音频模型编码。

3. 鉴权

HTTP 
Authorization: Bearer <api_key>
Content-Type: application/json
Accept: application/json

4. 生成及计费动作

POST {baseUrl}/audio/generations/{apiType}

4.1 {apiType} 枚举说明

{apiType} 区分大小写，且必须与访问的接口路径匹配。

apiType 能力
TextToAudio 同步语音合成
TextToAudioAsync 异步长文本语音合成
VoiceDesign 根据描述设计音色
VoiceClone 根据样本音频克隆音色

4.2 语音合成

TextToAudio 适用于同步返回音频；TextToAudioAsync 适用于长文本或离线合成。两者透传 text、voice_setting、audio_setting 等参数。

请求体参数

字段 类型 必填 说明
model string 是 已开通的 MiniMax 音频模型编码。
text string 同步必填 待合成文本，最长 10000 字符；异步合成与 text_file_id 二选一。
text_file_id integer 异步二选一 异步长文本合成的文本文件标识。
stream boolean 否 是否流式输出，默认 false。
voice_setting object 是 音色与发声设置，至少包含 voice_id。
audio_setting object 否 音频输出参数。
pronunciation_dict object 否 自定义发音字典。
language_boost string 否 小语种或方言增强；可传 auto 或指定语种。
voice_modify object 否 声音效果器设置。
subtitle_enable boolean 否 是否开启字幕，默认 false。
subtitle_type string 否 字幕粒度：sentence、word 或 word_streaming。
output_format string 否 非流式结果格式：hex（默认）或 url。
aigc_watermark boolean 否 是否添加 AIGC 音频水印，默认 false。

voice_setting 至少包含 voice_id；常用可选字段包括 speed、vol、pitch 和 emotion。audio_setting 可设置采样率、比特率、格式和声道。

对象字段 类型 必填 说明
voice_setting.voice_id string 是 系统、克隆或设计音色的标识。
voice_setting.speed number 否 语速，范围 [0.5, 2]，默认 1.0。
voice_setting.vol number 否 音量，范围 (0, 10]，默认 1.0。
voice_setting.pitch integer 否 语调，范围 [-12, 12]，默认 0。
voice_setting.emotion string 否 情绪控制，如 happy、sad、calm、whisper。
audio_setting.sample_rate integer 否 采样率，默认 32000。
audio_setting.bitrate integer 否 比特率，默认 128000。
audio_setting.format string 否 音频格式，如 mp3、wav、flac 或 pcm。
audio_setting.channel integer 否 声道数，1 为单声道，2 为双声道。

同步语音合成成功后，data.audio 返回音频 Hex 字符串；请按请求中的音频格式、采样率和声道解析。

JSON 
{
  "data": {
    "audio": "<音频 Hex 字符串>",
    "status": 2,
    "ced": ""
  },
  "extra_info": {
    "audio_length": 3636,
    "audio_sample_rate": 32000,
    "audio_size": 59892,
    "bitrate": 128000,
    "word_count": 14,
    "invisible_character_ratio": 0,
    "usage_characters": 26,
    "audio_format": "mp3",
    "audio_channel": 1,
    "usage_voice_count": 1
  },
  "trace_id": "06e0934dd24e4eecde3796afa2e5334e",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}
字段 类型 说明
data.audio string 生成的音频 Hex 字符串。
data.status integer 语音合成状态。
data.ced string 附加结果字段；无内容时为空字符串。
extra_info object 音频元信息，包含时长、采样率、文件大小、码率、词数、不可见字符比例、用量、格式、声道和音色使用次数。
trace_id string 本次请求的追踪标识。
base_resp.status_code integer 结果状态码；0 表示成功。
base_resp.status_msg string 结果说明。

4.3 音色设计

请求体参数

字段 类型 必填 说明
model string 是 已开通的 MiniMax 音频模型编码。
prompt string 是 目标音色的描述文本。
preview_text string 是 用于生成试听音频的文本，最长 500 字符。
voice_id string 否 自定义生成的音色标识；不传时由服务生成唯一标识。
aigc_watermark boolean 否 是否为试听音频添加 AIGC 音频水印，默认 false。

调用 POST {baseUrl}/audio/generations/VoiceDesign 成功后，响应会返回新建音色的标识和试听音频。

JSON 
{
  "voice_id": "test_voice_design_xwm101",
  "trial_audio": "<音色试听音频 Hex 字符串>",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}
字段 类型 说明
voice_id string 设计成功后生成的音色标识，可用于后续语音合成。
trial_audio string 音色试听音频的 Hex 字符串。
base_resp.status_code integer 结果状态码；0 表示成功。
base_resp.status_msg string 结果说明。

4.4 音色克隆素材

VoiceClone 请直接提供 sourceAudio；可选的 promptAudio 使用完全相同的结构。

请求体参数

字段 类型 必填 说明
model string 条件必填 请求 text 生成试听音频时必填。
voice_id string 是 自定义克隆音色标识；以字母开头，仅允许字母、数字、- 和 _。
sourceAudio object 是 源音频内容，具体结构见下表。
promptAudio object 否 用于提高相似度和稳定性的示例音频。
prompt_text string 条件必填 传入 promptAudio 时必填，且与示例音频文本完全一致。
text string 否 试听合成文本，最长 1000 字符；传入后返回试听音频。
language_boost string 否 特定语言或方言增强，可传 auto。
text_validation string 否 源音频预期转写文本，最长 200 字符。
accuracy number 否 与 text_validation 配合使用的识别相似度阈值，范围 [0, 1]，默认 0.7。
need_noise_reduction boolean 否 是否对源音频降噪，默认 false。
need_volume_normalization boolean 否 是否启用音量归一化，默认 false。
aigc_watermark boolean 否 是否为试听音频添加 AIGC 音频水印，默认 false。
字段 类型 必填 说明
sourceAudio.data string 是 音频 Base64 字符串，或 data:audio/<format>;base64,... Data URL
sourceAudio.fileName string 否 原始文件名，例如 speaker.wav
sourceAudio.contentType string 否 MIME 类型，例如 audio/wav
promptAudio object 否 用于提高相似度和稳定性的示例音频，结构同 sourceAudio
prompt_text string 条件必填 使用 promptAudio 时必须传入，且须与该音频内容完全一致

调用 POST {baseUrl}/audio/generations/VoiceClone 成功后，会返回试听音频地址及音频元信息。

JSON 
{
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  },
  "demo_audio": "<试听音频 URL>",
  "extra_info": {
    "audio_length": 3312,
    "audio_sample_rate": 32000,
    "audio_size": 41404,
    "bitrate": 96900,
    "usage_characters": 26,
    "word_count": 14
  },
  "input_sensitive": false,
  "input_sensitive_type": 0
}
字段 类型 说明
base_resp.status_code integer 结果状态码；0 表示成功。
base_resp.status_msg string 结果说明。
demo_audio string 克隆音色的试听音频 URL。
extra_info object 试听音频的元信息，包含时长、采样率、大小、码率、用量字符数和词数。
input_sensitive boolean 输入内容是否命中敏感检测。
input_sensitive_type integer 输入敏感检测类型。

5. 资源动作

使用 POST {baseUrl}/audio/resource-actions/{apiType}。该类请求用于读取或删除资源，不创建新的合成任务。

5.1 {apiType} 枚举说明

{apiType} 区分大小写，且必须与访问的接口路径匹配。

apiType 能力
QueryTextToAudioTask 查询异步合成任务
QueryVoice 查询系统、克隆或设计音色
DeleteVoice 删除克隆或设计音色

voice_type 可取 system、voice_cloning、voice_generation 或 all（删除音色时仅使用可删除的克隆或设计音色类型）。

5.2 音色查询

POST {baseUrl}/audio/resource-actions/QueryVoice

请求体参数

字段 类型 必填 说明
model string 是 已开通的 MiniMax 音频模型编码。
voice_type string 否 音色类型筛选：system、voice_cloning、voice_generation 或 all；省略时返回该模型可用音色。
JSON 
{
  "model": "MiniMax/speech-2.8-hd"
}

成功响应中按音色类型返回列表；系统音色记录包含名称，克隆和设计音色记录包含创建时间与描述。

字段 类型 说明
system_voice array 系统预置音色列表。
system_voice[].voice_id string 音色标识，可填入 voice_setting.voice_id。
system_voice[].voice_name string 音色展示名称。
system_voice[].description array 音色描述，可为空数组。
system_voice[].created_time string 创建时间。
voice_cloning array 克隆音色列表。
voice_generation array 设计音色列表。
base_resp.status_code integer 结果状态码；0 表示成功。
base_resp.status_msg string 结果说明。

6. 请求与响应约定

  • 所有接口均使用 Authorization: Bearer <api_key> 认证，租户编码固定为 00000000。
  • apiType 为路径的一部分，区分大小写；请使用上表列出的固定值。
  • 音频二进制应以 Base64 或 Data URL 传递，避免将大体积音频内容写入日志。
  • 响应为 JSON；可根据响应中的 usage_characters 获取用量信息。
  • 异步合成先从创建响应读取任务标识，再以 QueryTextToAudioTask 轮询任务终态。

7. 调用示例

7.1 同步语音合成

JSON 
{
  "model": "<租户已开通的音频模型编码>",
  "text": "您好，欢迎使用语音合成服务。",
  "stream": false,
  "voice_setting": {"voice_id": "male-qn-qingse", "speed": 1, "vol": 1},
  "audio_setting": {"sample_rate": 32000, "format": "mp3", "channel": 1}
}

请求路径：POST {baseUrl}/audio/generations/TextToAudio。

7.2 音色克隆

JSON 
{
  "model": "<租户已开通的音频模型编码>",
  "voice_id": "my-custom-voice-001",
  "sourceAudio": {
    "data": "data:audio/wav;base64,<音频Base64内容>",
    "fileName": "speaker.wav",
    "contentType": "audio/wav"
  },
  "need_noise_reduction": true,
  "need_volume_normalization": true
}

请求路径：POST {baseUrl}/audio/generations/VoiceClone。

7.3 查询异步任务与音色

JSON 
// 查询异步合成任务
{"model": "<租户已开通的音频模型编码>", "task_id": "<任务ID>"}

// 查询全部可调用音色
{"model": "<租户已开通的音频模型编码>", "voice_type": "all"}

对应路径分别为 .../resource-actions/QueryTextToAudioTask 和 .../resource-actions/QueryVoice。