# minimax-mcode-byok

**MiniMax（海螺 H3）视频生成 BYOK MCP Server，为 mcode（Minimax Code CLI）设计。**

把 mcode 内置 Matrix 的 `submit_video_generation` / `query_video_generation` 两个工具移植到**官方开放平台 V2 API**，用你自己的 API Key 鉴权（BYOK，Bring Your Own Key）——视频生成按开放平台计费（积分/按量），**不占用 mcode 订阅套餐（Token Plan）的视频条数和周限额**。

> 非官方社区工具，与 MiniMax 公司无隶属关系。接口以[开放平台文档](https://platform.minimax.cn/docs/api-reference/video-generation-v2-create)为准。

## 适用场景

- mcode 已登录（OAuth 订阅）状态下，内置 Matrix 视频工具与本项目**并存不冲突**（MCP 工具名自动带 server 前缀），可按需选择走订阅额度还是走 API Key
- 订阅的每日视频条数用完，还想继续生成
- 想把视频生成费用与订阅额度分开结算

## 工作方式

```
mcode (TUI/ACP) ──MCP stdio──> mcp-server.mjs ──HTTPS──> 官方开放平台 API
                                                    POST /v2/video_generation        （提交，得 task_id）
                                                    GET  /v2/query/video_generation/ （轮询，取结果 URL）
```

暴露两个工具（入参与内置 Matrix 版对齐）：

| 工具 | 作用 |
|---|---|
| `submit_video_generation` | 提交异步视频任务，立即返回 `task_id` |
| `query_video_generation` | 查询状态；`succeeded` 时自动把 mp4 下载到你指定的路径（签名 URL 约 9 小时有效，落盘不担心过期） |

## 请求标识：以 mcode 客户端身份发出

本 server 的所有 API 请求默认携带 `User-Agent: MiniMaxCode`——与 mcode 调用开放平台 API 时使用的客户端标识一致。因此即使走的是 API Key（BYOK）格式，请求在服务端遥测/风控视角也呈现为 mcode 客户端发出，与 mcode 自身的 BYOK 模式行为对齐。

- 鉴权与计费不受影响：仍用你自己的 API Key，费用归属 Key 所属账户（按量/积分），不动订阅额度
- 如需自定义，用环境变量 `MINIMAX_VIDEO_UA` 覆盖（设为 `""` 之外的任意值）

## 安装

**前置**：已安装 [mcode](https://www.minimaxi.com/)（Minimax Code CLI）；Node.js 18+（mcode 自带 runtime 也可）。

1. **获取 API Key**：[platform.minimax.cn](https://platform.minimax.cn)（国际站 [platform.minimaxi.com](https://platform.minimaxi.com)）→ 账户管理 → 接口密钥

2. **克隆本仓库**（路径任意，记住 `mcp-server.mjs` 的完整路径）：

   ```bash
   git clone https://github.com/Hylouis233/minimax-mcode-byok.git
   ```

3. **注册到 mcode**：编辑 mcode 用户级 MCP 配置 `~/.minimax/mcp.json`（Windows 为 `C:\Users\<你>\.minimax\mcp.json`；文件已存在则把条目合并进已有的 `mcpServers`）：

   ```json
   {
     "mcpServers": {
       "minimax-mcode-byok": {
         "command": "node",
         "args": ["C:\\path\\to\\minimax-mcode-byok\\mcp-server.mjs"],
         "env": {
           "MINIMAX_API_KEY": "你的开放平台APIKey",
           "MINIMAX_VIDEO_API_BASE": "https://api.minimax.cn"
         },
         "enabled": true,
         "description": "MiniMax 视频生成 BYOK（官方 V2 API，按 API Key 计费）"
       }
     }
   }
   ```

   - `node` 不在 PATH 时，可改用 mcode 自带 Node 的完整路径，如 `%USERPROFILE%\.minimax-code\runtime\node-v22.19.0-win-x64\node.exe`（版本号以本机为准）
   - 国际站账号把 `MINIMAX_VIDEO_API_BASE` 改为 `https://api.minimaxi.com`

4. **重启 mcode**，在 TUI 里直接说人话即可，例如：

   > 用 minimax-mcode-byok 生成一个 6 秒 2K 视频：夜晚的赛博朋克街道，霓虹雨幕，说一句"欢迎回家"

   模型、时长（H3 4–15 秒、H3-Max 5–15 秒）、分辨率（768P/2K）、比例它会先问你；任务完成后 mp4 自动保存到工作区。

## 支持的输入

- **模型**：`MiniMax-H3`（质量档，768P/2K）、`MiniMax-H3-Max`（极速档，480P/768P）
- **模式**：纯文生视频 / 首帧·尾帧·首+尾帧 / 多模态参考（参考图 ≤9、参考视频 ≤3、参考音频 ≤3，总数 ≤12）
- **媒体**：公网 HTTP(S) URL 与 `mm_file://` 直接透传；本地文件自动转 base64（受官方 64MB 请求体上限，大文件请用公网 URL）
- H3 原生同步出音：对白、环境音、音效写进 prompt 即可

## 限制

- `MiniMax-Hailuo-2.3` 走旧版 V1 接口，本工具不包装（调用会返回明确提示）——H2.3 请继续用 mcode 内置 Matrix 工具
- 任务查询窗口 7 天
- 计费按 API Key 走开放平台（参考价：国内站 2K ≈ ¥0.8/秒、768P ≈ ¥0.5/秒，以[价格页](https://platform.minimax.cn/docs/price)为准）

## 排障

| 现象 | 处理 |
|---|---|
| `1004 login fail` / 401 | API Key 错误，或 Key 与 `MINIMAX_VIDEO_API_BASE` 站点不匹配（cn 的 Key 别配 minimaxi.com） |
| 工具没出现在 mcode | 检查 `mcp.json` 是合法 JSON、`args` 路径正确、`node` 可用；重启 mcode |
| `credits_exhausted` / 402 | 开放平台余额不足，充值或换 Key |
| 大视频文件报超过 64MB | 改用公网 URL 引用 |

## License

[MIT](./LICENSE)