> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jiekou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MiniMax Speech

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

## 一、概述

本文档说明如何通过 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={task_id} |
| 上传文件 | POST /v3/minimax/v1/files/upload |
| 查询文件 | GET /v3/minimax/v1/files/retrieve?file\_id={file_id} |
| 下载文件 | GET /v3/minimax/v1/files/retrieve\_content?file\_id={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](https://platform.minimaxi.com/docs/api-reference/speech-t2a-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 调用示例

```bash theme={null}
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 响应说明

```json theme={null}
{
  "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 不收费。具体单价以您所使用服务的价格页面为准。

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

官方参数说明：[创建异步任务](https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-create)、[查询异步任务](https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-query)

### 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 创建示例

```bash theme={null}
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
    }
  }'
```

```json theme={null}
{
  "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 查询任务

```bash theme={null}
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；到达终态后停止轮询。

```json theme={null}
{
  "task_id": 95157322514444,
  "status": "Success",
  "file_id": 95157322514496,
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}
```

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

## 四、文件管理

官方参数说明：[文件上传](https://platform.minimaxi.com/docs/api-reference/file-management-upload)、[文件检索](https://platform.minimaxi.com/docs/api-reference/file-management-retrieve)、[文件下载](https://platform.minimaxi.com/docs/api-reference/file-management-retrieve-content)

### 4.1 上传文件

```bash theme={null}
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 查询与下载

```bash theme={null}
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 直接返回二进制文件。上传、查询和下载不收费。

## 五、音色快速复刻

官方参数说明：[音色快速复刻](https://platform.minimaxi.com/docs/api-reference/voice-cloning-clone)

### 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 调用示例与响应

```bash theme={null}
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
  }'
```

```json theme={null}
{
  "input_sensitive": false,
  "demo_audio": "",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}
```

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

## 六、音色设计

官方参数说明：[音色设计](https://platform.minimaxi.com/docs/api-reference/voice-design-design)

### 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 调用示例与响应

```bash theme={null}
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."
  }'
```

```json theme={null}
{
  "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 调用示例

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

```python theme={null}
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)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.