---
name: minimax-token-plan-api
description: MiniMax Token Plan 年度/月度套餐 API 调用规则、端点、错误码和配置指南
tags: [minimax, api, tts, text, image, video, token-plan]
---

# MiniMax Token Plan API 参考

> MiniMax Token Plan 年度/月度套餐的 API 调用规则。与旧版计费 API Key 完全不同。

## 核心概念区分

| | Token Plan Key | 计费 API Key（旧）|
|---|---|---|
| **来源** | Token Plan 套餐配套 | 账户余额充值 |
| **计费方式** | 配额制（请求次数/时间窗口） | 余额制（按量扣费）|
| **错误 1008** | 不会发生（配额耗尽→1002 rate limit） | `insufficient balance` → 余额耗尽 |
| **超额后** | 配额用完 → `rate limit (1002)`；可叠加 Credits | 余额耗尽后无法调用 |

**当前问题：** 用户的 `MINIMAX_CN_API_KEY` 是旧计费 Key，导致 `insufficient balance (1008)` 错误。已更新为国际版 Token Plan Key（sk-cp-BdZ...），但用户实际使用 **Plus极速版（中国大陆）**，与国际版 Hs_plus 是两套独立系统。

**重要区分（实测得出）：**

| | 中国大陆 Plus 极速版 | 国际版 Hs_plus |
|---|---|---|
| **平台** | platform.minimaxi.com | platform.minimax.io |
| **API 端点** | `api.minimaxi.com` | `api.minimaxi.com` |
| **M2.7-highspeed** | 1,500次/5小时 | 4,500次/5小时 |
| **TTS Speech 2.8** | 9,000字符/日 | 19,000字符/日 |
| **image-01** | 100张/日 | 200张/日 |
| **Music-2.6** | 100首/天（≤5分钟） | 100首/天（≤5分钟） |
| **可用 TTS 模型** | `speech-2.8-hd`（实测成功） | `speech-02-hd`（Hs_plus专属）|

> **注意：** 用户实际购买的是 **Plus 极速版**（非标准版），TTS 配额 **9,000字符/天**（非4,000）。Plus 极速版使用 `speech-2.8-hd` 模型；Hs_plus 使用 `speech-02-hd`/`speech-01-hd`。两者不要混淆。

**认证方式（实测验证）：**

所有 MiniMax API 统一使用以下 headers，**无需 GroupId**：
```
Authorization: Bearer <Token Plan Key>
Content-Type: application/json
```

> ⚠️ **关键发现：** `Content-Type: application/json` 是必须的！之前 curl 测试失败是因为：
> 1. 用占位符 Key 导致误判为需要 GroupId
> 2. 缺少 `Content-Type` header
>
> 用 Python `requests` 库 + 真实 Key + 正确 headers 测试全部成功。

**图片生成认证要点：**
- 必须 `Content-Type: application/json`
- `response_format`: `"base64"` 返回 base64，或 `"url"` 返回图片 URL

**音乐生成认证要点：**
- 必须 `Content-Type: application/json`
- 必须提供歌词（`lyrics` 参数）或设置 `lyrics_optimizer: true`
- 纯音乐模式需设置 `is_instrumental: true` + `prompt` 必填

**歌词生成端点：**
```
POST https://api.minimaxi.com/v1/lyrics_generation
```
- `mode: "write_full_song"` - 写完整歌曲
- `mode: "edit"` - 编辑/续写歌词
- `prompt` - 歌曲主题/风格描述

---

## Token Plan 配额（Plus 极速版）

| 资源 | 配额 | 刷新机制 |
|---|---|---|
| M2.7-highspeed | 1,500 请求/5小时 | 滚动 5 小时窗口 |
| Speech 2.8 | 9,000 字符/天 | 每日北京时间 00:00 刷新 |
| image-01 | 100 张/天 | 每日刷新 |
| Music-2.6 | 100 首/天（每首≤5分钟） | 每日刷新 |

**扣费顺序：** Token Plan 配额 → Credits（如果有）→ 不覆盖的资源需切换计费 Key

---

## API 端点总览

所有 API 均使用 `Authorization: Bearer <Token Plan Key>`

### 1. 文本模型（Text Chat）

**Anthropic 兼容端点（Hermes 当前使用）：**
```
POST https://api.minimaxi.com/anthropic/v1/messages
Headers:
  x-api-key: <Token Plan Key>
  Authorization: Bearer <Token Plan Key>
```

**OpenAI 兼容端点：**
```
POST https://api.minimaxi.com/v1/chat/completions
```

**支持的模型：**
- `MiniMax-M2.7`
- `MiniMax-M2.7-highspeed`
- `MiniMax-M2.5`
- `MiniMax-M2.5-highspeed`

**请求示例（Anthropic）：**
```bash
curl -X POST https://api.minimaxi.com/anthropic/v1/messages \
  -H "x-api-key: $MINIMAX_TOKEN_PLAN_KEY" \
  -H "Authorization: Bearer $MINIMAX_TOKEN_PLAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-M2.7",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

---

### 2. 文字转语音（TTS）

**国际版端点：** `https://api.minimaxi.com/v1/t2a_v2`（Hs_plus 用户）  
**国内版端点：** `https://api.minimax.cn/v1/t2a_v2`（Plus极速版用户，api.minimax.cn 国内可访问）

> **注意：** Plus 极速版 TTS 使用 `speech-2.8-hd` 模型，配额 **9,000字符/天**；Hs_plus 使用 `speech-02-hd`/`speech-01-hd`。Plus 极速版调用 `speech-02-hd` 会返回 2056（模型专属配额）。

**TTS 模型（实测验证）：**
- `speech-2.8-hd` → Plus 极速版可用 ✅（配额 9000字符/日）
- `speech-02-hd` → Hs_plus 专属，Plus 极速版调用返回 2056 ❌
- `speech-01-hd` → Hs_plus 专属，Plus 极速版调用返回 2056 ❌

**请求示例：**
```python
import requests

api_key = os.environ.get("MINIMAX_API_KEY")
url = "https://api.minimaxi.com/v1/t2a_v2"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}
payload = {
    "model": "speech-2.8-hd",  # 必须用这个，speech-02-hd 会返回 2056
    "text": "你好，欢迎使用 MiniMax TTS",
    "voice_setting": {
        "voice_id": "Chinese (Mandarin)_News_Anchor",
        "speed": 1,
        "vol": 1,
        "pitch": 0
    },
    "audio_setting": {
        "sample_rate": 32000,
        "format": "mp3",
        "bitrate": 128000
    }
}

resp = requests.post(url, headers=headers, json=payload)
audio_data = resp.json()["data"]["audio"]  # base64 编码的音频
```

**语音情感（emotion）选项：** `happy`, `sad`, `angry`, `fearful`, `disgusted`, `surprised`, `calm`, `fluent`, `whisper`（`fluent`/`whisper` 仅 `speech-2.8-hd` 支持）

---

### 3. 图片生成（实测成功）

**文生图端点：** `POST https://api.minimaxi.com/v1/image_generation`  
**图生图端点：** `POST https://api.minimaxi.com/v1/image_interior`（需参考文档确认）

**模型：** `image-01`

**请求示例（Python）：**
```python
import requests

api_key = os.environ.get("MINIMAX_API_KEY")
url = "https://api.minimaxi.com/v1/image_generation"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}
payload = {
    "model": "image-01",
    "prompt": "一个男人穿着白色T恤站在海边",
    "aspect_ratio": "16:9",
    "response_format": "base64"  # 或 "url"
}

resp = requests.post(url, headers=headers, json=payload)
images = resp.json()["data"]["image_base64"]  # base64 格式
# 或 image_urls（URL 格式）
```

> ⚠️ **之前失败原因：** curl 测试用占位符 Key，返回 1004 导致误判为需要 GroupId。实测用真实 Token Plan Key + `Content-Type: application/json` 即可成功。

**尺寸选项：** `1:1`(1024×1024), `16:9`(1280×720), `4:3`, `3:2`, `2:3`, `3:4`, `9:16`, `21:9`

---

### 4. 视频生成

**端点：** `POST https://api.minimaxi.com/v1/video_generation`

**模型：** `MiniMax-Hailuo-02`（2.3系列）, `T2V-01`, `I2V-01` 等

**⚠️ 必须附加 GroupId 查询参数（同图片生成）。**

---

### 4. 音乐生成（实测成功）

**端点：** `POST https://api.minimaxi.com/v1/music_generation`

**模型：** `Music-2.6`

**配额：** 100首/天（每首≤5分钟）

**请求示例（Python）：**
```python
import requests

api_key = os.environ.get("MINIMAX_API_KEY")
url = "https://api.minimaxi.com/v1/music_generation"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}
payload = {
    "model": "music-2.6",
    "prompt": "欢快的新年歌曲, 流行音乐, 开心",
    "lyrics": "[Verse]\n新年到真热闹\n烟花绽放天空照\n[Hook]\n恭喜恭喜恭喜你\n新年快乐每一天"
}

resp = requests.post(url, headers=headers, json=payload)
audio_data = resp.json()["data"]["audio"]  # base64 编码的音频
```

**纯音乐模式：**
```python
payload = {
    "model": "music-2.6",
    "prompt": "chill lo-fi hip hop beat",  # 必填
    "is_instrumental": True
}
```

**歌词自动生成（不提供歌词时）：**
```python
payload = {
    "model": "music-2.6",
    "prompt": "a cheerful pop song",
    "lyrics_optimizer": True  # 自动生成歌词
}
```

---

### 5. 歌词生成（Token Plan 包含）

**端点：** `POST https://api.minimaxi.com/v1/lyrics_generation`

**请求示例：**
```python
import requests

api_key = os.environ.get("MINIMAX_API_KEY")
url = "https://api.minimaxi.com/v1/lyrics_generation"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}
payload = {
    "mode": "write_full_song",
    "prompt": "一首关于夏日海边的轻快情歌"
}

resp = requests.post(url, headers=headers, json=payload)
data = resp.json()
song_title = data["data"]["song_title"]
style_tags = data["data"]["style_tags"]
lyrics = data["data"]["lyrics"]
```

**参数说明：**
- `mode`: `"write_full_song"` 写完整歌曲, `"edit"` 编辑/续写歌词
- `prompt`: 歌曲主题/风格描述（最大2000字符）
- `lyrics`: 现有歌词（仅 `edit` 模式）
- `title`: 指定歌曲标题

**返回的歌词结构标签：** `[Intro]`, `[Verse]`, `[Pre-Chorus]`, `[Chorus]`, `[Hook]`, `[Bridge]`, `[Solo]`, `[Interlude]`, `[Outro]`

---

### 6. 网络搜索路由策略

**默认搜索：** Tavily（`web.search_backend: tavily`，已验证可用）

**MiniMax Token Plan 搜索（备用）：**
```
POST https://api.minimaxi.com/v1/coding_plan/search
```
```python
payload = {"q": "搜索关键词"}
```

**路由规则：**
1. 正常英文/国际内容 → Tavily
2. 中文搜索、中国相关 → MiniMax `/v1/coding_plan/search`
3. 用户指定 MiniMax → MiniMax
4. Tavily 不可用 → MiniMax

### 7. 图片理解（Vision）

> ⚠️ **重要结论（实测 2026-05-21）：MiniMax M2.7 原生不支持图片输入。**
> Hermes 内置的 `vision_analyze` 工具在此配置下永远失败，只能用以下 workaround。

**✅ 推荐方案：MiniMax CLI (`mmx`)** — 稳定可用

```bash
# 安装（只需一次）
npm install -g mmx-cli

# 配置 API Key（只需一次）
mmx auth login --api-key <your-token-plan-key>

# 使用（无需每次配置）
mmx vision describe --image /path/to/image.jpg --prompt "描述图片内容"
```

`mmx` 是 MiniMax 官方 CLI，认证信息保存在 `~/.mmx/config.json`。安装配置一次后永久有效，后续调用无需再传 key。

**配额查看：**
```bash
mmx quota show
```
显示 `coding-plan-vlm: 150 次/周`（极速版）。标准版用户显示的数字可能不同，以实际返回为准。

**VLM 端点实测验证（2026-05-21）：**
- curl 直接调用 `/v1/coding_plan/vlm` 用同一 Token Plan Key 认证成功（返回 `invalid params` 而非 `login fail`）
- 说明 bug 不在 API Key 或 endpoint，在于 MCP server 内部发送请求时 Authorization header 传递有问题
- Bug 复现条件：只要通过 `minimax-coding-plan-mcp` 的 stdio 协议调用就触发，直接 curl 不触发

**⚠️ MCP 方案（有 bug，不推荐）：**

`minimax-coding-plan-mcp` v0.0.4 的 VLM 调用存在持久性 bug：
- 症状：`mcp_minimax_understand_image` 始终返回 `login fail`
- 原因：**不是**进程时序问题（进程已正常启动，env vars 正确传递）
- 验证：直接 curl 用同一 key 调用 `/v1/coding_plan/vlm` 成功（返回 `invalid params`，说明认证通过）
- 结论：MCP server 内部在发送请求时 Authorization header 传递有 bug

**MCP 故障表现：**
```
Failed to perform VLM analysis: API Error: login fail: Please carry the API secret key...
```
**不要做的事：**
- ❌ 不要反复重试（会触发 tool loop 警告）
- ❌ 不要改 .env 或 config.yaml（配置正确）
- ❌ 不要 kill MCP 进程尝试重建（进程正常，bug 在内部）
- ❌ 不要在 MCP 上花时间调试

**临时应急方案（无 mmx 时）：**
直接 curl 调用 VLM 端点：
```bash
KEY=$(grep MINIMAX_API_KEY ~/.hermes/.env | cut -d'=' -f2)
curl -s -X POST "https://api.minimaxi.com/v1/coding_plan/vlm" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d "{\"prompt\":\"描述图片\",\"image_url\":\"data:image/jpeg;base64,$(base64 -w0 /path/to/image.jpg)\"}"
```

**OpenAI GPT-4o 方案**（需用户提供 OpenAI API Key）：
配置 `auxiliary.vision.provider: openai`, `auxiliary.vision.model: gpt-4o`。

### 8. Token Plan MCP 工具（⚠️ 有已知 bug）

通过 MCP 协议调用（需安装 `minimax-coding-plan-mcp`）：
```bash
uvx minimax-coding-plan-mcp --env MINIMAX_API_KEY=<Token Plan Key> --env MINIMAX_API_HOST=https://api.minimaxi.com
```
提供 `web_search` 和 `understand_image` 工具。

> ⚠️ **注意**：`understand_image` 工具有已知 bug（见上方"图片理解"章节），建议用 `mmx vision` 替代。

---

## Hermes 配置说明

**config.yaml 中的 MiniMax 相关配置：**

| 配置项 | 当前值 | 说明 |
|--------|--------|------|
| `model.provider` | `minimax-cn` | 主对话 provider |
| `tts.minimax.model` | `speech-2.8-hd` | TTS 模型（Plus 极速版正确） |
| `auxiliary.vision.provider` | `openai` | 已改为 OpenAI，需用户提供 API Key |
| `auxiliary.vision.model` | `gpt-4o` | 图像理解模型 |
| `web.search_backend` | `tavily` | 可用，也可切换到 MiniMax MCP |

**Hermes 内置图片/音乐生成：** Hermes 内置的图片生成走 FAL.ai/OpenAI/Codex，不是 MiniMax。如需 MiniMax 图片/音乐生成，需直接调用 API（见上方端点）。

> **注意：** Hermes 没有内置的 MiniMax 图片生成或音乐生成插件。这些功能需要通过对话让 Agent 直接调用 MiniMax API。

> **Vision 配置：** MiniMax M2.7 本身不支持图片输入，auxiliary.vision 无法用 MiniMax 作 provider。当前配置为 OpenAI GPT-4o，等待用户提供 API Key。

---

## 错误代码速查

| Code | 含义 | 处理方式 |
|---|---|---|
| 1002 | rate limit | 等 5 小时配额刷新，或用 Credits |
| 1004 | 认证失败 | 检查 Token Plan Key 是否正确 |
| 1008 | 余额不足 | **计费 Key 问题**，切换到 Token Plan Key |
| 1026/1027 | 内容敏感 | 修改输入内容 |
| 1039 | token 超限 | 减少输入 token 数 |
| 1041 | 连接数超限 | 降低并发 |
| 2045 | 增长限速 | 避免请求量突变 |
| **2056** | **TTS Speech 每日配额耗尽** | **等次日配额刷新**（Hs_plus: 4000字符/天）|

> **2056 错误示例（实测）：**
> `usage limit exceeded, 5-hour usage limit reached for Token Plan Hs_plus (0/0 used), resets at 2026-05-18T15:00:00+08:00`
> - TTS Speech 是**每日配额**，不是 5 小时窗口
> - `(0/0 used)` 表示配额计数未刷新，不影响实际限制
> - 文本对话（`/anthropic/v1/messages`）不受此限制影响

---

## Rate Limits（与 Token Plan 配额是两套不同的限制）

| 类别 | RPM | TPM |
|---|---|---|
| Text (M2.7/M2.5) | 500 | 20,000,000 |
| T2A (TTS) | 60 | - |
| Image | 10 | - |
| Video | 5 | - |
| Music | 120 | - |

---

## Credits 机制

- Token Plan 配额耗尽后自动抵扣 Credits
- Credits 1 年有效期，不可跨年滚动
- 可单独购买，不必须配 Token Plan
- 获取地址：https://platform.minimax.io/user-center/payment/balance

---

## 相关文档

- [用户配置状态（国内 Plus 标准版）](./references/plus-domestic-user-status.md)
- [API 认证方式差异（文本/TTS 不需要 GroupID，图片/音乐需要）](./references/api-authentication.md)