submodel-minimax-h3-mcp

MiniMax H3 视频生成 API 的 MCP 服务器，让 Claude Desktop、Trae、Cursor 等 MCP 客户端直接创建、管理视频生成任务。

支持文生视频、图生视频（首/尾帧）、多模态参考（图片 + 视频 + 音频）、提示词优化（H3 Context-IR）以及 768P → 2K 超分辨率重生成。

功能

| 工具 | 说明 | |---|---| | h3_create_video_task | 创建视频生成任务（异步）。根据输入自动选择模式：纯文本 = 文生视频；首/尾帧图片 = 图生视频；参考素材 = 多模态参考 | | h3_query_task | 按 task_id 查询任务状态与结果（轮询进度，成功后返回视频 URL / 增强后提示词） | | h3_list_tasks | 分页列出近 7 天任务，支持按状态、模型、任务类型、任务 ID 过滤 | | h3_cancel_or_delete_task | 取消或删除任务：queued → 取消；succeeded / failed → 删除 | | h3_regenerate_video | 将 768P 视频重生成升级为 2K（通过 source_task_id 或源视频 URL） | | h3_create_context_task | 创建 H3 Context-IR 上下文理解任务，深度理解多模态输入并输出结构化增强提示词 |

支持的模型：MiniMax-H3（标准）、MiniMax-H3-Turbo（加速）。

Resources 与 Prompts

除工具外，服务器还提供静态资源与提示词模板：

| 类型 | 名称 | 说明 | |---|---|---| | Resource | h3://models | 模型清单与参数限制（时长/分辨率/比例、生成模式、重生成规则、任务生命周期） | | Resource | h3://media-rules | 媒体格式与大小限制、参考素材数量/时长上限、API 错误码对照表 | | Prompt | video_prompt_structuring | 把口语化的视频想法转成结构化 H3 提示词（镜头/主体/动作/环境/光线/风格），适合在创建任务前使用 |

快速开始

无需克隆仓库，在 MCP 客户端配置中直接使用 npx（要求 Node.js ≥ 18）：

{
  "mcpServers": {
    "minimax-h3": {
      "command": "npx",
      "args": ["-y", "submodel-minimax-h3-mcp"],
      "env": {
        "H3_API_KEY": "你的API Key",
        "H3_DEFAULT_MODEL": "MiniMax-H3"
      }
    }
  }
}

API Key 在 SubModel 的 Account Management > API Keys 获取，由每个使用者自行配置（用量计费归属各自账户）。

环境变量

| 变量 | 必填 | 默认值 | 说明 | |---|---|---|---| | H3_API_KEY | 是 | — | Bearer 认证 API Key。未配置时服务器启动即报错退出 | | H3_DEFAULT_MODEL | 否 | MiniMax-H3 | 所有工具的默认模型，单次调用可用 model 参数覆盖 | | H3_BASE_URL | 否 | https://h3.submodel.ai | API 地址（用于代理或测试环境） | | H3_MCP_BASE_PATH | 否 | — | 默认本地输出目录，视频下载到此处（各工具可用 output_directory 覆盖） | | H3_RESOURCE_MODE | 否 | url | url = 返回视频 URL；local = 任务成功后自动下载视频到本地（未配置目录时用 ./h3-output） |

其他客户端（Claude Desktop、Cursor 等）配置结构相同，将上面的 JSON 放入对应的 mcpServers 配置即可。

使用示例

配置好后，在客户端对话中直接用自然语言触发：

• 「用 MiniMax-H3 生成一段 5 秒、16:9 的雪山谷火车镜头视频」→ 调用 h3_create_video_task
• 「生成一段视频，等完成后直接告诉我结果」→ 调用 h3_create_video_task（缺省即同步等待，完成自动返回视频 URL，可配 output_directory 下载到本地）
• 「帮我查一下任务 428863236170174 的进度」→ 调用 h3_query_task
• 「列出我最近失败的生成任务」→ 调用 h3_list_tasks
• 「把任务 xxx 的 768P 结果升级成 2K」→ 调用 h3_regenerate_video
• 「根据这段文字和这张参考图，生成一个优化过的视频提示词」→ 调用 h3_create_context_task

典型工作流：h3_create_video_task 默认同步等待（内部每 5 秒轮询，最长 4 分钟，超时会返回 task_id 供后续查询）；传 async_mode: true 则立即返回 task_id，再轮询 h3_query_task 直到 succeeded，从结果中取 video_url。

参数速览

h3_create_video_task

| 参数 | 说明 | |---|---| | prompt（必填） | 文本提示词 | | model | MiniMax-H3 / MiniMax-H3-Turbo，默认取 H3_DEFAULT_MODEL | | duration | 时长 4–15 秒，默认 5 | | resolution | 480P / 768P / 2K，默认 768P | | ratio | adaptive / 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16；文生视频缺省自动用 16:9，图生视频由输入图推断 | | first_frame_url / last_frame_url | 首/尾帧图片 URL（图生视频），与参考素材互斥 | | reference_images / reference_videos / reference_audios | 参考素材 URL 数组（多模态参考模式） | | aigc_watermark | 是否添加 AIGC 水印，默认 false | | use_context_ir | 生成前先用 Context-IR 优化提示词（单独计费） | | callback_url | Webhook 回调地址 | | idempotency_key | 幂等键：相同键 + 相同请求复用已有 task_id，不同请求返回 409 | | async_mode | 默认 false（同步等待结果）；true = 立即返回 task_id，自行轮询查询 | | output_directory | 视频下载目录，完成后保存为 <task_id>.mp4；省略时用 H3_MCP_BASE_PATH，均未设置则只返回 URL |

媒体限制（API 规则，服务器会本地预校验）

• 图片：JPG/JPEG/PNG/WEBP，单文件 ≤ 30 MB，宽高 256–5760 px（不支持 HEIC/HEIF）
• 参考视频：MP4/MOV（H.264/H.265），单文件 ≤ 50 MB，每段 2–15 s，合计 ≤ 15 s
• 参考音频：WAV/MP3，单文件 ≤ 15 MB，每段 2–15 s，合计 ≤ 15 s
• 数量上限：首/尾帧各 1 张、参考图 9 张、参考视频 3 个、参考音频 3 个；音频参考必须至少搭配一个参考图或参考视频
• 首/尾帧与参考素材不能混用

h3_regenerate_video

• source_task_id 与 base_video_url 二选一（都传或不传都会报错）
• 源必须为 768P：任务需属于当前账户、近 7 天内创建且已 succeeded；或提供满足要求的 768P 视频 URL
• 输出固定为 2K（2520×1440）
• 同样支持 async_mode 与 output_directory（行为同 h3_create_video_task）

h3_query_task

• task_id（必填）：要查询的任务 ID
• output_directory：任务已 succeeded 时把视频下载为 <task_id>.mp4（受 H3_RESOURCE_MODE=local / H3_MCP_BASE_PATH 影响）

本地开发

git clone <本仓库地址> && cd H3_MCP
npm install
npm run build        # TypeScript 编译到 build/
npm run smoke        # 冒烟测试（MCP 握手 + 工具注册 + 错误链路）
node build/index.js  # 启动（需先设置 H3_API_KEY）

本地构建版的客户端配置：

{
  "mcpServers": {
    "minimax-h3": {
      "command": "node",
      "args": ["/绝对路径/H3_MCP/build/index.js"],
      "env": { "H3_API_KEY": "..." }
    }
  }
}

发布

npm login
npm publish          # 非公开 scope 包，默认公开发布
npm version patch && npm publish   # 后续更新

License

MIT