Skip to main content
Glama

minimax-video-mcp

把 MiniMax Code 的视频生成能力接到第三方中转站上。

工具名、参数、调用流程对齐 MiniMax 内置的 matrix 视频连接器, Agent(MiniMax Code / Claude Code / Cursor)侧的写法基本不用改。

⚠️ 诚实说明:这是「第三方视频任务适配器」,不是官方视频能力的透明替换。 实测确认,官方视频能力里有一部分无法通过换服务商保留(生成工具的云端执行体、 Lucid 配音的 CLI 路径、Hub 编排、多媒体矩阵、Drive 资产)—— 详见 「与官方视频能力的差距」。

另:视频编辑能力(多轨剪辑 / 字幕 / 模板 / 剪映导出)本来就与服务商无关, 它是官方 minimax-video 插件自带的 OpenChatCut 改造版,保留官方插件即原样保留。

你只需要做一件事:把 API Key 写进 api.txt。 别的什么都不用改、什么都不用配。


三步接入

1. 拿仓库

git clone https://github.com/FlapPearLabs/minimax-video-mcp.git
cd minimax-video-mcp

2. 写 key

在中转站控制台「管理 API 密钥」创建一个 key,复制 api.txt.example 为 api.txt, 把 key 粘进第一行:

cp api.txt.example api.txt      # Windows: copy api.txt.example api.txt
sk-xxxxxxxxxxxxxxxx

格式很宽松,下面这些都能认出来(# 开头是注释):

你可能写成这样

认不认

sk-abc123...

✅ 标准

Bearer sk-abc123...

✅

"sk-abc123..."

✅ 带引号

Authorization: Bearer sk-abc123...

✅ 整行粘

{"api_key": "sk-abc123..."}

✅ JSON

文件里有多行

✅ 取第一个 sk- 开头的

末尾有空格 / 空行 / 换行符是 CRLF

✅ 自动清理

文件开头有 BOM

✅ 自动清理

3. 跑一条命令

python install.py

它会:检查环境 → 装依赖 → 读 key → 验证 key 能不能用(只读,不花钱)→ 列出你能用的视频模型 → 跑完整测试 → 打印出 MCP 注册参数。

看到「准备就绪」就成了。


Related MCP server: vicsee-mcp-server

注册到 MiniMax Code

install.py 最后会打印一段 JSON。把它交给 Agent,Agent 调用 mavis 工具即可完成:

mcp create
  name        = minimax-video
  transport   = stdio
  command     = python
  args        = ["<仓库绝对路径>/server.py"]
  description = 第三方中转站 MiniMax 视频生成

env 不用传 —— server.py 会自己去读同目录的 api.txt。 想用环境变量的话,设 VIDEO_API_KEY 即可(优先级更高)。

注册完 mcp list 里能看到 minimax-video 就成了。

或者:直接把这段发给 Agent

仓库里的 接入提示词.md 是一段可以直接粘贴进 MiniMax Code 的提示词, Agent 读完会自己完成克隆、读 key、注册、验证。你也可以直接说:

帮我把 https://github.com/FlapPearLabs/minimax-video-mcp.git 这个项目接进 MiniMax Code。 key 在 api.txt 里。

要把这个项目分享给别人? 看 给同学的说明.md —— 里面有可以直接群发的文案, 和一段转发给同学自己 AI 助手的提示词。


提供的工具

工具

作用

对应官方

submit_video_generation

提交异步任务 → 返回 task_id

connector__matrix__submit_video_generation

query_video_generation

轮询 → status / video_url / error

connector__matrix__query_video_generation

list_video_tasks

分页列任务

—

list_video_models

列站点上可用的视频模型

—

regenerate_video_2k

768P 成品升 2K

—

delete_video_task

删除已结束的任务记录

—

describe_provider

适配器配置概览 + key 来源

—

download_video

手动把成片直链转存到本地

—

list_local_tasks

查本机台账,找回之前提交过的任务

—

resume_pending_tasks

续跑所有未到终态的任务

—


与官方视频能力的差距(实测,2026-10 复核)

完整取证(含路径、行号、原文)见 docs/官方视频能力边界-实测.md。

先纠正一个早期误判:早期版本把「视频编辑工程(openchatcut)」列为换服务商后的结构性缺口, 这是错的。minimax-video 插件就是 OpenChatCut v0.2.16(2e6f4a29,AGPL-3.0-or-later)的改造版, 官方补丁(161KB upstream.patch)里搜 baseURL|apiKey|minimax.cn|video_generation 零命中 —— 编辑层纯本地运行、与服务商完全无关,保留官方插件即原样保留。 同理,hub_* 属于另一个插件 minimax-h3-skills,minimax-video 全目录 grep hub_* 零命中。

官方视频能力的真实分层

层

由谁提供

与服务商的关系

视频编辑(多轨 / 字幕 / 特效 / 模板 / 剪映导出 / 草稿审阅)

minimax-video 插件内置 OpenChatCut,本机 127.0.0.1 MCP

无关,纯本地

视频生成

宿主 Agent 调 connector__matrix__submit_video_generation,执行体在 agent.minimax.cn

锁死在云端 ← 唯一要换的东西

Hub 编排(hub_*)

minimax-h3-skills 插件(另一个插件)

需 Hub 服务端

Drive 资产

MiniMax 云

云端专属

官方插件主动剥离了生成后端(miniapp.ts:2 "Mini App 只装配编辑/媒体能力;推理由宿主 Agent 承担"; miniapp-server.ts:9 "不导入 embedded-server:它会带入独立 Agent 与云生成后端";/api/keys 返回空), 所以生成必须借宿主的 connector 工具,而那个工具在云端执行。

换服务商后保不住的(修订版)

缺口

性质

证据

宿主 connector 工具的执行体

mcode-tools connector call → agent.minimax.cn/minimax-cloud/api/v1/connectors/tools/call,OAuth 认证,扣 MiniMax 账号额度。mcode-tools 只有 4 个子命令、无改指向入口;~/.minimax 无 connector 配置

cli.mjs:23235-23236

mcode-tools connector CLI 路径(Lucid 配音)

skill 直接 shell 调 mcode-tools connector tool connector__matrix__synthesize_speech,只到云端,本地替换不了

skills/lucid/capabilities/mcode/voice.md:7

Hub agent 运行时

服务端封闭组件;属于 minimax-h3-skills(9 个 skill 里 8 个依赖它),不属于 minimax-video

H3 skills frontmatter;minimax-video 内 grep hub_* 零命中

多媒体矩阵

本项目未实现;中转站是否支持未验证(GET /v1/skills 需真实 key 才能读)

mcode-tools connector tools 实测 19 个工具

Drive 资产生命周期

node_id + get_asset_url 是云端专属

官方连接器 schema

一条真实的协议落差(也是本仓库存在的理由)

上游 OpenChatCut 的 MiniMax provider base URL 可配(MINIMAX_BASE_URL,见 server/plugins/index.ts:130-134), 但走 V1(/v1/video_generation、/v1/query/video_generation?task_id=、/v1/files/retrieve?file_id=); 中转站 /v2/* 只有 MiniMax 官方 V2 格式,/v1/* 是 OpenAI 兼容的 chat/messages/skills, 不提供 MiniMax V1 视频路径(实测 404)。 → 直接把 MINIMAX_BASE_URL 指过去会 404,必须做 V1→V2 改写。这正是本仓库 server.py 在做的事。

换服务商后能原样保留的

  • 视频编辑全线:多轨剪辑、字幕、特效、模板、剪映草稿导出、草稿 → 预览 → 应用(官方插件自带,本机跑)

  • 代码动画:code-video / lucid 的本地 Python + Remotion 渲染

  • 视频生成的参数与异步流程(本项目已对齐官方 V2 同形,并多一层台账 / 防重复扣费)

已按审查意见修掉的(本仓库)

  • 工具名同时以 submit_video_generation 和 connector__matrix__submit_video_generation 暴露

  • list_video_tasks 的分页参数不再被配置默认值覆盖

  • 台账写失败时中止提交(而不是受理后丢 task_id)

  • 升 2K 补上提交前 attempt 记录

  • 回归测试:tests/test_review_fixes.py(7 个用例,逐条钉住上面的修复)

想真正达到"完全等价",得走哪条路

路线

达成度

说明

A 换官方上游

~35%

能换 connector 层,但宿主侧没有改指向入口(baseURL 硬编码 + 启动器清空环境变量);Hub 换不掉

B 自建完全兼容 MCP

~60%

补齐多媒体工具 + 返回契约;Hub 与 Drive 仍缺

C 改官方 skills

~10%

改工具名解决不了 canvas / 选择卡片这类运行时依赖

D 别名 + 宿主路由层

最合理

在宿主分发层同时接住 Connector 调用与 CLI 调用,把请求转进适配器;前提是找得到官方扩展点

F = 官方插件 + 本地适配器接管生成(= 本仓库当前形态)

~75%

编辑层用官方插件(不碰 AGPL 再分发义务),生成层走中转站;待验证宿主对 MCP 工具的命名与优先级

E 自建 openchatcut 集成

~70%

能补编辑能力,但要给上游 MiniMax provider 打 V1→V2 补丁 + 承担 AGPL 再分发义务;性价比低于 F

下一步该做的不是继续补工具名,而是这三件事: ① 用真实 key 读 GET /v1/skills,确认中转站覆盖哪些路由(不花钱); ② 在实机里确认宿主对 MCP 工具的命名规则,以及同名工具的优先级(内置 connector 工具是裸名 connector__matrix__*); ③ (可选)若要把"视频修改"完全对齐,补 /v2/video_regeneration 与 DELETE /v2/video_generation/{task_id}。

中转站已明确 H3-Context-IR 未开放(POST /v2/h3_context_ir → 400),官方 H3 的"上下文续写"这一项接不了。


三条铁律(代码里已实现,不只是文档约定)

铁律

实现

一、task_id 立刻落库

提交前先记一条「提交尝试」,拿到 task_id 后立刻写入台账 .video-tasks.jsonl。换会话、换窗口、隔天回来,用 list_local_tasks / resume_pending_tasks 就能找回任务,不必重新提交(重新提交 = 再扣一次钱)

二、终态不要自动重试

终态任务不进 pending,续跑跳过。创建类请求(提交、升 2K)永不重试、永不换域名重发 —— 上游一旦受理就计费,重试可能多出一个计费任务。提交前若失败,会留下「未决提交」记录,提醒你去平台任务列表查,而不是盲目重提

三、直链拿到就转存

任务成功时在后台把成片下载到 videos/,台账里出现 local_path。转存不阻塞 MCP 调用(否则客户端超时会诱发 Agent 重提)。下载失败会记进台账,resume_pending_tasks 会重试

台账 .video-tasks.jsonl 和 videos/ 都在 .gitignore 里,是本地状态,不进仓库。

MCP server 启动时如果发现未完成任务,会在 stderr 打一条提示 —— 看到它就先 resume_pending_tasks,别重新提交。


站点接口

项

值

Base URL

https://api.lk888.ai(备用 https://ai778.cc/houduan)

鉴权

Authorization: Bearer sk-xxx(兼容 x-api-key / x-goog-api-key / ?key=)

创建任务

POST /v2/video_generation

查询任务

GET /v2/query/video_generation/{task_id}

任务列表

GET /v2/query/video_generation?page_num&page_size(≤50,仅近 7 天)

删除任务

DELETE /v2/video_generation/{task_id}(仅已结束的)

升 2K

POST /v2/video_regeneration

推荐模型

MiniMax-H3(全形态,768P4K,415 秒,2K 有声)

请求体与 MiniMax 官方 V2 同形(model / content[] / resolution / duration / ratio / callback_url / extra / aigc_watermark),同一个模型、同样的参数。

但中转站不是官方,下面这些差异要知道:

与 MiniMax 官方的差异

#

差异

影响

1

不支持 mm_file://

素材只能传公网 URL 或 data: 内联

2

不支持只传 last_frame

必须与 first_frame 同传(客户端已前置拦截)

3

POST /v2/h3_context_ir 未接入,固定 400

多镜头分镜文本得自己写,不能靠 Context-IR 生成

4

多出 1080P / 4K

官方 H3 只有 480P/768P/2K;这是平台额外开放的,不是官方规格

5

usage 只给秒数与图片数,不给 token

从官方迁过来的成本统计会缺 token 账

6

报错 message 是中文,末尾不带数字错误码

官方是 OpenAI 风格 error.http_code + request_id

7

extra.prompt_expansion_mode 只对 MiniMax-H3-Max 生效

官方也是这样;传给 H3 不生效

8

DELETE 只能删已结束的任务

处理中的任务不能取消

9

升 2K 仅 model=MiniMax-H3 + resolution=2K,且 source_task_id 只认部分渠道出的 768P 成片

其他渠道的成片升不了 2K

所以准确的说法是:模型和参数与官方一致,接口行为有上述九处差异。


平台规则(提交前本地拦截,不白烧额度)

  1. resolution 与 duration 必填

  2. 文生视频必须给具体 ratio,且不能是 adaptive

  3. 图生视频 ratio 恒按 adaptive 处理

  4. 只传 last_frame 会 400,必须与 first_frame 同传

  5. 帧模式与参考模式互斥(first_frame/last_frame 不能与 reference_* 同传)

  6. POST /v2/h3_context_ir 平台未接入,固定 400

  7. 不支持 mm_file://;图片/音频可公网 URL 或 data: 内联;视频只收公网 URL

  8. failed 任务已自动退款,不要重复提交

  9. 轮询 5~10 秒一次;768P 通常 1~4 分钟,1080P/2K/4K 更久

这些写在 provider.json 的 rules 段,server.py 会在发出请求之前拦下违规组合。


跑测试

python -m unittest discover -s tests -t . -v

覆盖:key 解析的 30+ 种边界情况、content[] 组装、9 条平台规则、mock 端到端、 base_url 故障切换、真实 MCP stdio 协议握手、安装器行为、三条铁律的专项验证。


常见问题

现象

原因与处理

没找到 API key

api.txt 不在仓库根目录,或第一行不是 key。install.py 会打印它要找的绝对路径

401

key 抄错了,或用了 MiniMax 官方 key 而不是中转站的 key

403 ip_not_allowed

控制台给本机 IP 设了白名单,把本机公网 IP 加进去或清空白名单

402

余额不足,去控制台充值

连不上

网络/代理问题;也可改 provider.json 的 base_url

缺少依赖 mcp

python -m pip install -r requirements.txt;被系统 Python 限制时用虚拟环境

Agent 说工具没出现

mcp list 确认已启用,然后重启/重载 MCP

任务失败

已自动退款。看 task.error.message(中文),不要自动重试

虚拟环境(推荐,避免系统 Python 限制)

python -m venv .venv
.venv/Scripts/activate        # Windows
source .venv/bin/activate     # macOS / Linux
pip install -r requirements.txt
python install.py

安全

  • api.txt 已在 .gitignore 里,不要提交、不要贴进聊天

  • 密钥只走 api.txt 或环境变量 VIDEO_API_KEY,不进命令行参数

  • 中转站会留存你提交的 prompt 和素材。公开素材走中转站没问题;工作文档、商业机密建议仍走官方直连

许可

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers