MiniMax Speech

curl --request POST \
  --url https://{api_domain}/v3/minimax/v1/t2a_v2

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{api_domain}/v3/minimax/v1/t2a_v2",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{api_domain}/v3/minimax/v1/t2a_v2"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://{api_domain}/v3/minimax/v1/t2a_v2")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

POST

minimax

t2a_v2

MiniMax Speech

curl --request POST \
  --url https://{api_domain}/v3/minimax/v1/t2a_v2

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{api_domain}/v3/minimax/v1/t2a_v2",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{api_domain}/v3/minimax/v1/t2a_v2"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://{api_domain}/v3/minimax/v1/t2a_v2")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

参数及使用方式已对齐官方，详细参数可直接参考官方文档。

一、概述

本文档说明如何通过 MiniMax Speech 原厂协议使用同步语音合成、异步长文本语音合成、文件管理、音色快速复刻和音色设计。同步接口在一次 POST 请求中直接返回音频或 SSE；异步接口先返回 task_id，调用方再查询任务状态，并通过 file_id 获取结果文件。

1.1 接口地址

能力	方法与路径
同步语音合成	POST /v3/minimax/v1/t2a_v2
创建异步语音任务	POST /v3/minimax/v1/t2a_async_v2
查询异步语音任务	GET /v3/minimax/v1/query/t2a_async_query_v2?task_id=
上传文件	POST /v3/minimax/v1/files/upload
查询文件	GET /v3/minimax/v1/files/retrieve?file_id=
下载文件	GET /v3/minimax/v1/files/retrieve_content?file_id=
音色快速复刻	POST /v3/minimax/v1/voice_clone
音色设计	POST /v3/minimax/v1/voice_design

完整地址为 https://{api_domain} 加上表中的路径，其中 {api_domain} 为您使用的 API 域名。

1.2 鉴权

所有请求都需要平台 API Key。JSON POST 请求还必须指定内容类型：

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

文件上传使用 multipart/form-data；GET 请求不需要 Content-Type。

1.3 响应与资源访问

接口保留 MiniMax 原厂响应字段与错误结构。JSON 响应通常包含 base_resp.status_code 和 base_resp.status_msg；HTTP 200 不一定表示业务成功，请始终检查 base_resp.status_code=0。 task_id 和 file_id 可能超过 JavaScript 安全整数范围，请使用无损整数或字符串保存。文件、任务和私有音色只能由创建它们的平台用户访问；查询时应使用创建资源时的同一个平台 API Key。

二、同步语音合成

官方参数说明：同步语音合成 HTTP

2.1 调用接口

POST https://{api_domain}/v3/minimax/v1/t2a_v2

常用请求字段：

字段	类型	必填	说明
model	string	是	speech-2.8-hd 或 speech-2.8-turbo
text	string	是	待合成文本，少于 10,000 字符；超过 3,000 字符建议流式输出
stream	boolean	否	是否返回原厂 SSE，默认 false
voice_setting	object	是	音色 ID、语速、音量、音调和情绪等设置
audio_setting	object	否	采样率、码率、格式和声道设置
language_boost	string	否	指定语言或 auto
output_format	string	否	hex（默认）或 url；流式仅支持 hex，URL 有效期为 24 小时
subtitle_enable	boolean	否	是否返回字幕，默认 false

pronunciation_dict、timbre_weights、voice_modify、stream_options 等原厂扩展字段会原样转发，详细约束以 MiniMax 官方文档为准。

2.2 调用示例

curl -X POST 'https://{api_domain}/v3/minimax/v1/t2a_v2' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "speech-2.8-hd",
    "text": "Welcome to our service.",
    "stream": false,
    "voice_setting": {
      "voice_id": "male-qn-qingse",
      "speed": 1,
      "vol": 1,
      "pitch": 0
    },
    "audio_setting": {
      "sample_rate": 32000,
      "bitrate": 128000,
      "format": "mp3",
      "channel": 1
    },
    "output_format": "url"
  }'

流式调用只需设置 stream=true 并使用支持流式读取的客户端，例如 curl -N。

2.3 响应说明

{
  "data": {
    "audio": "https://example.com/audio.mp3",
    "status": 2
  },
  "extra_info": {
    "usage_characters": 26,
    "audio_length": 9900,
    "audio_format": "mp3"
  },
  "trace_id": "provider-trace-id",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

流式响应为原厂 SSE。最终成功事件的 data.status 为 2，用量位于 extra_info.usage_characters。

2.4 计费说明

按上游最终返回的 extra_info.usage_characters 计费，计费单位为每 10,000 字符。失败请求、原厂业务错误和没有成功终止事件的 SSE 不收费。具体单价以您所使用服务的价格页面为准。

三、异步长文本语音合成

官方参数说明：创建异步任务、查询异步任务

3.1 创建任务

POST https://{api_domain}/v3/minimax/v1/t2a_async_v2

字段	类型	必填	说明
model	string	是	speech-2.8-hd 或 speech-2.8-turbo
text	string	二选一	待合成文本，最长 50,000 字符；与 text_file_id 二选一
text_file_id	integer	二选一	通过文件上传获得；支持 txt 或 zip，单文件文本少于 1,000,000 字符
voice_setting	object	是	音色和语音参数
audio_setting	object	否	输出音频设置
language_boost	string	否	指定语言或 auto

3.2 创建示例

curl -X POST 'https://{api_domain}/v3/minimax/v1/t2a_async_v2' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "speech-2.8-turbo",
    "text": "A longer narration.",
    "voice_setting": {
      "voice_id": "audiobook_male_1",
      "speed": 1,
      "vol": 1,
      "pitch": 0
    }
  }'

{
  "task_id": 95157322514444,
  "task_token": "provider-task-token",
  "file_id": 95157322514444,
  "usage_characters": 101,
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

请保存 task_id。异步任务创建成功时即按响应中的 usage_characters 收费；后续查询不重复收费。

3.3 查询任务

curl -X GET 'https://{api_domain}/v3/minimax/v1/query/t2a_async_query_v2?task_id=95157322514444' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

该查询接口每秒最多调用 10 次。状态包括 Processing、Success、Failed 和 Expired；到达终态后停止轮询。

{
  "task_id": 95157322514444,
  "status": "Success",
  "file_id": 95157322514496,
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

任务成功后使用 file_id 查询或下载文件。MiniMax 官方说明下载 URL 自生成起约 9 小时有效，请及时保存结果。

四、文件管理

官方参数说明：文件上传、文件检索、文件下载

4.1 上传文件

curl -X POST 'https://{api_domain}/v3/minimax/v1/files/upload' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -F 'purpose=voice_clone' \
  -F 'file=@voice.wav'

purpose	用途与格式
voice_clone	快速复刻原始音频；mp3、m4a、wav
prompt_audio	音色复刻示例音频；mp3、m4a、wav
t2a_async_input	异步长文本输入；txt、zip

请求必须且只能包含一个 purpose 和一个文件。单次平台请求体上限为 64 MiB，MiniMax 对各用途的格式、时长和大小限制仍然适用。

4.2 查询与下载

curl -X GET 'https://{api_domain}/v3/minimax/v1/files/retrieve?file_id=95157322514496' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

curl -X GET 'https://{api_domain}/v3/minimax/v1/files/retrieve_content?file_id=95157322514496' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  --output result.mp3

retrieve 返回文件元数据和 download_url；retrieve_content 直接返回二进制文件。上传、查询和下载不收费。

五、音色快速复刻

官方参数说明：音色快速复刻

5.1 调用接口与字段

POST https://{api_domain}/v3/minimax/v1/voice_clone

字段	类型	必填	说明
file_id	integer	是	purpose=voice_clone 上传所得文件 ID；音频 10 秒至 5 分钟且不超过 20 MB
voice_id	string	是	自定义音色 ID，长度 8–256，以字母开头，不得与已有 ID 重复
clone_prompt	object	否	示例音频；使用时 prompt_audio 和 prompt_text 都必填
text	string	否	试听文本，最多 1,000 字符
model	string	条件必填	传 text 时必填；使用 speech-2.8-hd 或 speech-2.8-turbo
text_validation	string	否	样本预期文本，最多 200 字符
accuracy	number	否	ASR 相似度阈值，0–1，默认 0.7

5.2 调用示例与响应

curl -X POST 'https://{api_domain}/v3/minimax/v1/voice_clone' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "file_id": 123456789,
    "voice_id": "MyVoice001",
    "need_noise_reduction": false,
    "need_volume_normalization": false
  }'

{
  "input_sensitive": false,
  "demo_audio": "",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

成功请求按一个音色计费。若请求中生成试听音频，平台不额外增加语音合成 SKU。MiniMax 官方说明，克隆音色若 7 天内未正式用于语音合成，可能被删除。

六、音色设计

官方参数说明：音色设计

6.1 调用接口与字段

POST https://{api_domain}/v3/minimax/v1/voice_design

字段	类型	必填	说明
prompt	string	是	目标音色描述
preview_text	string	是	试听文本，最多 500 字符
voice_id	string	否	自定义音色 ID；不传时由 MiniMax 生成
aigc_watermark	boolean	否	是否在试听音频结尾添加节奏标识，默认 false

6.2 调用示例与响应

curl -X POST 'https://{api_domain}/v3/minimax/v1/voice_design' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "A warm, clear adult narrator with a calm delivery.",
    "preview_text": "Welcome to our service."
  }'

{
  "voice_id": "ttv-voice-generated-id",
  "trial_audio": "hex-encoded-audio",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

成功请求按一个音色计费，试听音频包含在本次接口计费中，不额外增加语音合成 SKU。

七、常见错误和注意事项

现象	说明与处理建议
HTTP 200，但 base_resp.status_code!=0	MiniMax 业务错误；根据 status_msg 修正输入，不要按成功处理
HTTP 400	JSON、multipart、模型名、查询参数或必填字段不合法
HTTP 401/403	检查平台 API Key、余额和权限
HTTP 404	文件、任务或私有音色不存在，或不属于当前平台用户
HTTP 429	降低请求/查询频率并使用指数退避；异步查询不得超过每秒 10 次
HTTP 5xx	保留响应和平台 trace ID 后联系技术支持；非幂等创建请求不要无控制重试

原厂字段会尽量原样转发，但本服务只开放本文列出的八个路径。
单次请求体和单个 SSE 事件上限为 64 MiB。
客户端断开后，服务可能继续读取已开始的 SSE 以完成用量结算。
异步任务必须通过本文的 MiniMax 查询接口获取状态，不使用平台通用异步结果接口。
收到文件 URL 或成功文件 ID 后请及时下载；URL 和文件可能过期。

八、Python 调用示例

以下示例演示异步创建和轮询。生产环境请设置整体超时、指数退避和最大轮询次数。

import os
import time

import requests


api_domain = os.environ["API_DOMAIN"]
api_key = os.environ["PLATFORM_API_KEY"]
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

created = requests.post(
    f"https://{api_domain}/v3/minimax/v1/t2a_async_v2",
    headers=headers,
    json={
        "model": "speech-2.8-turbo",
        "text": "A longer narration.",
        "voice_setting": {"voice_id": "audiobook_male_1"},
    },
    timeout=60,
)
created.raise_for_status()
created_body = created.json()
if created_body["base_resp"]["status_code"] != 0:
    raise RuntimeError(created_body)
task_id = created_body["task_id"]

while True:
    response = requests.get(
        f"https://{api_domain}/v3/minimax/v1/query/t2a_async_query_v2",
        headers={"Authorization": f"Bearer {api_key}"},
        params={"task_id": task_id},
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()
    if task["base_resp"]["status_code"] != 0:
        raise RuntimeError(task)
    if task["status"] == "Success":
        print(task["file_id"])
        break
    if task["status"] in {"Failed", "Expired"}:
        raise RuntimeError(task)
    time.sleep(2)

最后修改于 2026年10月21日

API 基础

API Key 管理

大语言

图像

视频

音频

MiniMax Speech

一、概述

1.1 接口地址

1.2 鉴权

1.3 响应与资源访问

二、同步语音合成

2.1 调用接口

2.2 调用示例

2.3 响应说明

2.4 计费说明

三、异步长文本语音合成

3.1 创建任务

3.2 创建示例

3.3 查询任务

四、文件管理

4.1 上传文件

4.2 查询与下载

五、音色快速复刻

5.1 调用接口与字段

5.2 调用示例与响应

六、音色设计

6.1 调用接口与字段

6.2 调用示例与响应

七、常见错误和注意事项

八、Python 调用示例

​一、概述

​1.1 接口地址

​1.2 鉴权

​1.3 响应与资源访问

​二、同步语音合成

​2.1 调用接口

​2.2 调用示例

​2.3 响应说明

​2.4 计费说明

​三、异步长文本语音合成

​3.1 创建任务

​3.2 创建示例

​3.3 查询任务

​四、文件管理

​4.1 上传文件

​4.2 查询与下载

​五、音色快速复刻

​5.1 调用接口与字段

​5.2 调用示例与响应

​六、音色设计

​6.1 调用接口与字段

​6.2 调用示例与响应

​七、常见错误和注意事项

​八、Python 调用示例

一、概述

1.1 接口地址

1.2 鉴权

1.3 响应与资源访问

二、同步语音合成

2.1 调用接口

2.2 调用示例

2.3 响应说明

2.4 计费说明

三、异步长文本语音合成

3.1 创建任务

3.2 创建示例

3.3 查询任务

四、文件管理

4.1 上传文件

4.2 查询与下载

五、音色快速复刻

5.1 调用接口与字段

5.2 调用示例与响应

六、音色设计

6.1 调用接口与字段

6.2 调用示例与响应

七、常见错误和注意事项

八、Python 调用示例