media-gen-mcp
> Claude Code 的「图像全家桶」—— 造图、画想法、看懂图,一句话搞定,全免费。
**给 Claude Code 装一次,以后所有图像活儿都是一句话。** 设计师出图、程序员画架构图、运营做分享卡、财务抠发票表格 —— 生图 / 视频 + 识别 + 画图 / 卡片 / 二维码全覆盖,**全免费**(免费服务方 + 本地引擎,装上即用)。
每周做几次图、装 N 个工具记 N 套参数很烦?这里只装一次,所有图像场景都丢给 Claude。
**简体中文** | [English](README.en.md)
## 目录
- [你说一句话,得到什么](#你说一句话得到什么)
- [60 秒上手](#60-秒上手)
- [能力全家桶](#能力全家桶)
- [配置详解](#配置详解)
- [常见问题](#常见问题)
- [这是给谁的](#这是给谁的)
- [支持作者](#支持作者)
- [License](#license)
---
## 你说一句话,得到什么
| 你说 …… | 你得到 |
|---|---|
| "画只赛博朋克猫,霓虹辉光" | AI 写实图,落盘到 `output/` |
| "生成 5 秒海边日落视频" | AI 视频 MP4(后台生成,完成通知你) |
| "画个架构图:客户端 → API 网关 → 订单服务 + 支付服务" | 矢量架构图 |
| "把这组销售数据画成柱状图" | 高清数据图表 |
| "做个指向 github.com 的二维码" | 矢量二维码 |
| "把 E=mc² 渲染成高清公式" | 矢量公式 |
| "做张深色渐变分享卡,标题 七月新品 🚀" | 排版好的分享卡(中文 + emoji 自动) |
| "识别这张发票截图里的表格" | 可粘贴的 HTML/Markdown 表格 |
| "把这张柱状图读成数据点" | 结构化 JSON 数据 |
| "描述一下这张图里有什么" | 自然语言回答 |
| "把这份 20 页 PDF 报告的文字全抠出来" | 整篇文本 / Markdown / JSON(数字版秒出,扫描件自动逐页 OCR) |
| "把这份合同扫描件提文字,水印和红章忽略掉" | 干净文本(自动剔除水印 / 红章 / 页眉页脚区域) |
| "这份双栏论文按阅读顺序合并成一段" | 单栏连续文本(多栏阅读序自动还原,不再串行错位) |
| "我现在能识别表格吗?中文 OCR 配好了吗?" | 当前能力清单 + 路由建议(哪个能用 / 哪个没配 / 该用什么) |
> 不用学工具名,不用装系统依赖,**Claude 自动挑最合适的方式完成**。
---
## 60 秒上手
核心思路:**画图 / 卡片 / 二维码 / 公式是本地引擎,识图(OCR 文字识别)也默认进程内兜底——默认路径不调 AI、不连网,装上即用**(例外:卡片非默认字体 / 彩色 emoji、架构图 `icon:` 图标首次会从 CDN 取资源;离线自动降级 —— emoji 变纯文本、图标省略、字体可经 fontPath 本地化)。只有 AI 写实图 / 视频才需要免费 API Key —— 把"第一张图"和"第一次读图"都提前到注册之前。
### 30 秒｜一行接入(零 Key)
```bash
# 一行装上(不带 Key,30 秒)
claude mcp add media-gen-mcp npx media-gen-mcp-server
# 重启 Claude Code → 输入 /mcp → 看到 media-gen-mcp ✓ Connected 即成功
```
### 30 秒｜免 Key 立刻出第一张图
直接对 Claude 说一句:
```
做张深色科技风的分享卡,标题:Claude Code 图像全家桶
```
→ 矢量图自动落盘到 `output/`,打开就能用。**你还没注册任何 API Key,已经拿到结果。**
下面这些也都是零 Key 零联网即时出:
- 「做个指向 github.com 的二维码」
- 「把 E=mc² 渲染成高清公式」
- 「画个架构图:客户端 → 网关 → 订单服务 + 支付服务 → 数据库,深色科技风」
- 「识别这张验证码图片里的数字」(OCR,默认进程内,不装任何东西)
- 「把这张截图里的英文文字提取出来」
### 想要中文 SOTA 识图 / 看图问答?配一行智谱 GLM Key(零部署,可选)
默认轻量引擎对英文 / 数字够用,中文准确率一般。**不想自建 PaddleX / vLLM,又想要中文 SOTA + 复杂表格 + 看图问答?** 配一行智谱 GLM Key 即可 —— 云端 **GLM-4.6V-Flash 永久免费**,零部署、零本地资源:
```bash
# ① 到 https://open.bigmodel.cn/console/apikey 注册免费账号 + 申请 api_key(格式 {id}.{secret})
# 注意:只接受 open.bigmodel.cn 标准 key;Code Plan key(ZAI_API_KEY)不可用 —— 它绑定 Z.ai 端点 + 白名单工具,违规调用会封号
# ② 写到 ~/.media-gen-mcp/config.json
{
"providers": {
"glm-vision": { "apiKey": "你的{id}.{secret}" }
}
}
# ③ 回 Claude Code 说:"识别这张中文发票截图里的表格" / "这张图里有几个人?在做什么?"
# → 中文 SOTA 识别 + 看图问答,落盘 / 直接回答
```
> 配好后 MCP 自动纳入 fallback 链:**paddle → glm-vision → vlm → tesseract**;哪一档临时挂掉自动降级,你无感。详见[配置详解 · 档位 2](#档位-2智谱-glm-46v-flash云端免费零部署中文-sota--vqa)。
### 想要 AI 写实图 / 视频?再加免费 API Key(可选)
```bash
# ① 拿免费 API Key(推荐 Agnes,默认服务方)
# https://platform.agnes-ai.com/ → 注册 → API Keys → 复制 sk-xxx
# (智谱 cogview-3-flash / cogvideox-flash 也永久免费,可二选一或都配)
# ② 写到 ~/.media-gen-mcp/config.json(只配一家也行)
{
"providers": {
"agnes": { "apiKey": "sk-你的agnes-key" }
}
}
# ③ 回 Claude Code 说:"画只赛博朋克橙猫,写实风"
# → AI 写实图落盘。视频同理:"生成 5 秒海边日落视频"
```
> 不想用 npx?全局装也行:先 `npm i -g media-gen-mcp-server`,再 `claude mcp add media-gen-mcp -s user "$(which media-gen-mcp-server)"`。
---
## 能力全家桶
> 直接对 Claude 说你想干嘛,它自动挑最合适的方式完成。下面按「你想做的事」分组 —— 你不用知道背后叫什么。
### 造一张图(从无到有)
**画一张写实照片或插画**
> 你:"画只赛博朋克橙猫,霓虹辉光,写实风"
> 得到:写实图落盘到 `output/`(也支持插画 / 产品概念图 / Logo 草稿 / 科幻场景)
**把一句话或一张图变成短视频**
> 你:"生成 5 秒海边日落视频"
> 得到:MP4 视频(3–18 秒;长视频后台生成,完成后通知你取片)
**抓一个图标或品牌 Logo**
> 你:"抓一个 GitHub 的 Logo,128 像素"
> 得到:20 万+ 图标库里的矢量 Logo,即下即用(GitHub / Twitter / Material / Lucide / Font Awesome 等)
**逆向 AI 生成图的提示词与参数**
> 你:"这张图是用什么 prompt、什么参数生成的?能复现吗?"
> 得到:结构化参数 —— 正向 / 负向 prompt、模型、采样步数、CFG、种子、尺寸(从 PNG 嵌入的 ComfyUI / A1111 元数据本地解析;Agnes 生成的图自带完整生成参数,拿到 prompt 可用 generate_image 一键复现)
### Google Flow 渠道(Veo 3.1 / Nano Banana,免 API Key)
> 🔴 **渠道状态(2026-09-10 定谳)**:Google 账号地区门禁(L3,`flow.google.com/unsupported-country`)导致本渠道当前**不可用**——登录与会话正常、更换网络节点仍被拒,恢复无时间表。代码与配置面保留,下文保留为契约说明(完整 wire 契约存档 `doc/flow-api-contract.md`)。
**是什么**:接入你已登录 Google Flow 的本机 Chrome,把 Flow 的生成能力变成工具 —— 免 API Key,生图 **0 积分**,视频按积分计费(7-100/条,提交前必经**计费确认门**:第一次调用只返回积分预估+确认令牌,你确认后才真提交)。
**前置**(只需一次;跨机器通用,lasso 非必需):一台开了调试端口的 Chrome 并登录 labs.google/fx —— `lasso launch-chrome --port 9223 --idle-ms 0`(推荐,静默),或裸 Chrome `--remote-debugging-port=9223 --user-data-dir=~/.media-gen-mcp/chrome-profile` 后在窗口登录;MCP 自动经 CDP 直连,不依赖 lasso 进程。
**一句话能干什么**:
| 你说 …… | 得到 |
|---|---|
| "用 Flow 画一张 ……"(或配置链让生图自动走 Flow)| 0 积分 AI 图(Nano Banana 2/Pro/Lite,含 2K 放大)|
| "用 Flow 把这张图动起来 / 生成 8 秒视频" | Veo 3.1 / Omni Flash 视频(文生/图生/参考图一致性/首尾帧/延长/编辑/1080p 超分,超分 0 积分)|
| "Flow 还剩多少积分?/ 把这条视频下载下来 / 删掉这批废图 / 生成分享链接" | `flow_status` 全套资产管理,全程 0 积分 |
> 视频积分明细与各会员档价目随 `flow_status` 实时可查;渠道优先级配置(让"生图"自动走 Flow)见[配置详解](#配置详解)。
### 看懂一张图 / 一份 PDF(把图和文档变数据)
**从截图里抠出文字**
> 你:"把这张验证码里的数字读出来"
> 得到:纯文本(验证码 / 发票号 / 扫描文档 / 聊天记录都能抠)
**把表格图变成 HTML / Markdown**
> 你:"识别这张发票截图里的表格"
> 得到:可直接粘贴的 Markdown 表格(发票 / 报表 / 扫描件不用再手动重打)
**从图表反推原始数据点**
> 你:"把这张柱状图读成数据"
> 得到:JSON 结构化数据(柱状 / 折线 / 饼图都行;glm-vision/vlm 走 prompt 抽取,paddle 的 chart 字段是占位、真实数据在 markdown 描述里)
**让它用大白话讲讲这张图**
> 你:"这张图里一共有几个人?在做什么?"
> 得到:自然语言回答(看图问答 / 手写 / 公式 / 复杂场景理解)
**把整份 PDF 的文字抠出来**
> 你:"把这份 20 页 PDF 报告的文字全抠出来,导出 Markdown"
> 得到:整篇文本 / Markdown / JSON —— 数字版 PDF 直接抽文字层秒出,扫描件自动逐页渲染 + OCR;支持指定页码范围(`3` / `1-10` / `odd` / `last`)、忽略水印 / 页眉页脚区域、多页合并或分页输出;长文档后台跑,完成通知你取结果(发票 / 合同 / 财报 / 论文 / 扫描书都行)
**让识图 / 读 PDF 结果更干净、更顺读**
> 你:「把这份合同扫描件提文字,**水印和红章忽略掉**」「这份双栏论文**按阅读顺序合并**成一段」
> 得到:干净、连续的文本 —— 两个开关在识图 / PDF 提取里可用(**tesseract 完整支持;glm-vision/vlm 不返回 blocks,两开关会被跳过并提示;paddle 的块无坐标,忽略区域仅告警级**):
> - **忽略区域**:圈出水印 / 红章 / 页眉页脚 / 表头区域,识别结果自动剔除,合同 / 证书 / 扫描件不再被水印糊住
> - **多栏阅读序**:论文 / 报刊 / 简历 / 双栏 / 三栏排版,自动按人类阅读顺序合并成单栏连续文本,不再串行错位
**先问一句"我装的识别服务都能干啥"**
> 你:"我现在能识别表格吗?中文 OCR 配好了吗?手写识别能用吗?"
> 得到:当前能力清单 —— 四档识别服务哪个已配置 / 哪个没配 / 哪个正在冷却或出错,以及"要做表格识别该走哪个、手写识别该走哪个"的路由建议;**先问一句再动手,避免直接调用才发现报错**
### 把想法画清楚(免 Key,装上就能用)
**画结构图**
> 你:"画个架构图:客户端 → API 网关 → 订单服务 + 支付服务 → 数据库"
> 得到:矢量架构图(也支持流程图 / 时序图 / 类图 / ER 图 / 思维导图)
**画交互式 / 动态 HTML 图**(浏览器打开可交互,边数据流 + 节点动画,主题跟随系统深/浅色)
> 你:"画个架构图,浏览器打开能交互、能动、主题跟着系统走"
> 得到:单文件 HTML(D2 双调色板默认开箱即反色 + viewer 平移/缩放/主题切换/导出 SVG + 边数据流/依次高亮/节点入场三种动画,Motion Governor 自动守无障碍)
**画可下钻的嵌套架构图**(浏览器打开点层进入子架构,面包屑回溯任意层)
> 你:"把这套系统画成嵌套架构图:顶层 5 大模块,点'订单服务'进它的内部架构,再点进创建订单的时序图"
> 得到:单文件 HTML(点某层 → 切到那层内部架构,层级可任意嵌套,每层可以是架构图 / 时序图 / 类图 / ER 图 / 流程图;面包屑或 Esc 回任意祖先层;URL 深链分享到某一层;主题跟随系统深/浅色)
**把数据画成图表**
> 你:"把这组销售数据画成柱状图"
> 得到:高清数据图表(柱状 / 折线 / 饼图 / 面积 / 散点,丢一串数字或一份 CSV 都行)
### 做卡片 / 海报 / 二维码(发出去好看)
**做分享卡 / OG 图 / 引言卡 / 封面 / 海报**
> 你:"做张深色渐变分享卡,标题 七月新品 🚀"
> 得到:排版精美的卡片(标题、副标题、渐变色、辉光、彩色 emoji、Logo 内嵌全自动,中文与日文汉字不乱码)
**生成二维码**
> 你:"做个指向 github.com 的二维码"
> 得到:矢量二维码(URL / 文本都行,海报印刷也清晰)
**把数学公式渲染成高清图**
> 你:"把 E=mc² 渲染成高清公式"
> 得到:矢量公式(LaTeX、复杂分式、化学方程式都支持)
### 做酷炫动效 / 科技感图形(同输入永远同输出)
**把 SVG 渲染成高清 PNG**
> 你:"画一个带辉光、星场、景深的科技感背景"
> 得到:酷炫 PNG,自动选最佳渲染方式保真不失真
**把 HTML / CSS 动画变成视频**
> 你:"做一个 3 秒的产品片头动画,渐变色 + 粒子"
> 得到:MP4 / GIF / WebM 视频(产品片头 / 品牌动画 / 动效演示,逐帧渲染,同输入永远同输出)
> **渲染浏览器依赖**:动效视频与滤镜 SVG 的 100% 保真渲染推荐 **lasso 渲染档**(确定性旗标内置、空闲 10 分钟自动回收、与本工具的日常 Chrome 完全隔离)——`npm i -g lasso-mcp` 后跑一次 `npx -y lasso-mcp render-chrome --ensure` 即装;`MEDIA_GEN_RENDER_MODE=attach` 钉死该档(CI/验收)。未装 lasso 时滤镜 SVG 自动降级 resvg(~92% 保真),动效视频返回带修复指引的结构化错误(legacy 自管池已退役,2026-09-03)。
> **小提示**:造图 / 读图走联网 AI;画图 / 卡片 / 二维码 / 动画是本地引擎 —— **装上就能用、矢量高清、同样的输入永远出同样的图**。
---
## 配置详解
> 一句话:**结构化能力(画图 / 图表 / 卡片 / 二维码 / 公式)零配置开箱即用;AI 生成配一行 API Key;识图默认零配置,要中文 SOTA / 表格 / 图表才自托管。** 你想用的能力决定要配什么 —— 不用全配。
### 按「我想干什么」查配置
| 你想干什么 | 要配什么 | 配了立刻能用 |
|---|---|---|
| 画架构图 / 数据图表 / 卡片 / 二维码 / 公式 | **什么都不用配** | 本地引擎,装完即用 |
| 酷炫动效视频 / 滤镜 SVG 100% 保真(`render_video` / `render_svg` Chrome 后端) | 推荐装 **lasso 渲染档**:`npm i -g lasso-mcp` 后跑一次 `npx -y lasso-mcp render-chrome --ensure`(空闲 10 分钟自动回收) | 装上即用;未装 lasso 时滤镜 SVG 自动降级 resvg(~92% 保真),动效视频返回带修复指引的结构化错误(legacy 自管池已退役) |
| AI 写实图 / AI 视频(文生图、文生视频) | 配一家免费 API Key(Agnes 或智谱,二选一) | 联网生成,落盘到 `output/` |
| 用 Google Flow 生图(0 积分)/ 管理生成资产 | **不用配 Key**:本机 Chrome 登录 Flow 即可(`lasso launch-chrome` 启动) | 生图 / 放大 / 上传 / 删除 / 分享 / 取消 / 查询全 0 积分;视频按积分计费(7–100 积分/条)。🔴 2026-09-10 起 L3 账号地区门禁不可用,恢复无时间表 |
| 用 PixVerse 订阅池生图 / 生视频(一个订阅聚合 25 个视频 + 14 个图像模型) | 需 PixVerse 订阅 + CLI 登录一次(`npx pixverse login`;**opt-in 渠道,不进默认链**,须点名 `provider="pixverse"`(0.22.0 起点名即用) | 按订阅积分计费,提交前必经**两段式计费确认门**(预估+确认令牌);各模型价格经 `list_models` 的 costCatalog 可查(实测价 > 静态估 > 未发布) |
| 用 Gemini 网页生图(Nano Banana 2)/ 生视频(Omni = Veo 3.1 系) | 本机 Chrome CDP 9225 + Google AI 订阅登录(`lasso launch-chrome --port 9225 --idle-ms 0` 后在窗口登录一次;**opt-in 渠道**,点名 `provider="gemini"`(0.22.0 起点名即用) | 消耗 Google AI 订阅**算力配额**(5 小时滚动窗 + 周上限;视频单条实测 ≈15-20% 窗口,每次提交带配额警示);文生图 / 文生视频 MVP(8s 16:9 固定档) |
| 用硅基流动 SiliconFlow 生图 / 生视频(**国内直连零代理的 HTTP API**) | 注册 siliconflow.cn(手机/微信/邮箱,免费模型需实名)→ cloud.siliconflow.cn/account/ak 建 API key → config `providers.siliconflow.apiKey`(**opt-in 渠道**,点名 `provider="siliconflow"`) | **Kolors 永久免费**(IPM 2/IPD 400 量级)+ 注册赠 ¥14 代金券可抵付费模型(Z-Image-Turbo ¥0.10/张 / Qwen-Image(-Edit) ¥0.30/张 / Wan2.2 视频 ¥2/条);图生图走 Qwen-Image-Edit(-2509 ≤3 张);视频固定 5s/720P,无首尾帧;产物 URL 1h TTL 工具内自动立即落盘;每次付费模型调用带价格警示 |
| 用 PixAI 生动漫图(**每日 10,000 积分免费;🔴 实测单张 2,100 积分 ≈ 4 张/日**;仅生图,API 无视频) | 注册 pixai.art + **邮箱验证**(不验证无每日积分)→ 凭证三选一:①浏览器 DevTools → Local Storage → `api.pixai.art:token` 复制 → config `providers.pixai.token`(最稳)②`providers.pixai.email/password`(自动 recaptcha 登录,脆弱)③官方 API key:profile/edit/api → `providers.pixai.apiKey`(**opt-in 渠道**,点名 `provider="pixai"`) | **选型定位=低量动漫+IP 最干净**(产出归你+私有,可商用);实测单张价 tsubaki2=2,100 积分(≈4 张/日)、haruka2=4,100(≈2 张/日),×4 批次 800/张折扣仅 UI 不可编程;每日配额自动 claim+余额告警;图生图仅公网 URL;13-29s/张;产物不永久保留已自动即时落盘 |
| 用 Cloudflare Workers AI 生图(**每日 10,000 neurons 免费续杯**;仅生图,零视频) | 注册 dash.cloudflare.com(免费计划即可,无需信用卡)→ Workers AI 页 → Use REST API → 建 API Token + 复制 Account ID → config `providers.cloudflare.apiToken` / `providers.cloudflare.accountId`(**opt-in 渠道**,点名 `provider="cloudflare"`) | **10k neurons/日 ≈ 173 张 flux-schnell 或 95 张 flux-2-klein 多参考编辑**;SDXL 双 $0 Beta 零费;8 模型(Leonardo 系 lucid/phoenix 独家 API 可达);premium 档逐张 neuron 警示(dev 3,750/张!);Workers Free 超额硬停零扣费/Paid 超额自动计费 $0.011/1k neurons;输出归用户商用无碍 |
| 用 HF 全能力工具箱(**hf_tts 语音克隆配音 / hf_remove_bg 抠图 / hf_upscale 超分 / hf_lipsync 对口型**;ZeroGPU 免费配额) | 与 hfspaces 渠道同一 token(免费 5min GPU/天);克隆 = Chatterbox(MIT 可商用),提供参考音频即克隆该音色;抠图 = BiRefNet;超分 = Tile-Upscaler;对口型 = LatentSync(商用前核许可) | 零本地部署,单端点即用(**前置:enabledProviders 白名单加入 hfspaces,出厂默认不含**);配额与视频共享(超分最吃配额) |
| 用 HF Spaces 免部署生视频(**ZeroGPU 免费配额跑开源 Wan2.2**;仅视频,免 Key 匿名即用) | 先在 config 的 enabledProviders 加入 hfspaces(出厂默认不含,未启用=点名被拒);启用后匿名即开箱用(2min GPU/天,共享出口易耗尽);建议 huggingface.co 免费注册 → Settings → Access Tokens 建 token → config `providers.hfspaces.token`(**opt-in 渠道**,点名 `provider="hfspaces"`) | 免费 HF 号 **5min GPU/天 ≈3-5 条**/PRO $9/月 40min;4 模型:wan22-i2v(≤5s 图生视频)/wan22-relay(**≤10s 首末帧接力**)/minimax-h3(**≤14s 开源 H3 Turbo:t2v/i2v/首尾帧+seed,官方 API 同款模型零成本跑**)/cogvideox(t2v 兜底 480p 无音轨);匿名 GPU 拒(SSE data:null)时换模型或配 token;产出归用户(Wan=Apache2.0 商用安全) |
| 用 ImagineArt 生图/生视频(**🔴 免费层生成实际被锁**——实测 2026-09-23,解锁需 Basic $13/月) | 注册 imagine.art → 终端一次性 `npx -y @imagineartofficial/mcp@0.10.0 login --no-browser` 复制 URL 浏览器授权(**opt-in 渠道**,点名 `provider="imagineart"`) | 🔴 官方 MCP 文档称免费 100 credits/日同池,但实测图像报「模型不在 plan」、视频明文要订阅——credits 可见不可花;**订阅 Basic $13/月(年付 $9)后渠道即用**(31 图+44 视频聚合模型,z-image-turbo 5cr/张、wan-2-2 视频 30cr/条);未订阅勿选本渠道 |
| OCR 文字识别(英文 / 验证码 / 数字 / 简单文档) | **什么都不用配** | 默认走进程内轻量引擎,装完即用 |
| 中文 OCR / 发票表格 / 图表读数 / 看图问答 / 手写 / 公式 | **配一行智谱 GLM Key**(零部署,云端永久免费)**或** 自托管 PaddleX / vLLM | 配 GLM Key 即开即用;自托管服务跑起来后填一行 baseUrl |
| **PDF 文字提取**(数字版 / 扫描件 / 多页) | 装两个依赖 `npm i pdfjs-dist @napi-rs/canvas`(首次用 PDF 时装) | 数字版 PDF 秒出;扫描件按上面 OCR 档位走(默认零配置也能跑) |
| **去水印 / 红章 / 页眉页脚、多栏阅读序还原** | **什么都不用配** | 调识图 / PDF 工具时直接说"Claude,忽略水印"或"按阅读顺序合并",自动应用 |
| **查当前识别能力**(哪个能用 / 哪个没配) | **什么都不用配** | 直接问,Claude 回一份当前能力清单 + 路由建议 |
---
### 一、生成类配置(AI 生图 / 视频)
**配一家免费 Key 就够**(推荐 Agnes,默认服务方;智谱备选,中文场景原生优化):
```json
{
"providers": {
"agnes": { "apiKey": "sk-你的agnes-key" },
"zhipu": { "apiKey": "你的智谱-key" }
}
}
```
- **Agnes**(推荐):https://platform.agnes-ai.com/ → 注册 → API Keys → `sk-xxx`
- **智谱**:[open.bigmodel.cn](https://open.bigmodel.cn/) → API Keys(免费模型 `cogview-3-flash` / `cogvideox-flash` 永久免费)
- 配两家更稳:任一家限流/波动,另一家自动顶上,零感知零重复扣费
- 配置文件:`~/.media-gen-mcp/config.json`(Windows:`%USERPROFILE%\.media-gen-mcp\config.json`);**没有也不崩** —— 结构化能力与默认 OCR 照常工作
**渠道路由(0.22.0:优先级链已废弃,选择权交给调用方)**——渠道选择是业务决策(免费试稿 → 付费定稿),由调用时点按工具描述的选型对比面自主点名:
- **缺省 = 免费池**:省略 `provider` → 免费渠道自动容灾互备(agnes 失败自动切 zhipu,反之亦然,60 秒熔断),零成本试稿首选
- **opt-in 渠道点名即用**(前置:先加入下方 enabledProviders 白名单):`gemini`(订阅配额制高质量)/`pixverse`(订阅积分制多模型)/`siliconflow`(国内直连 API,Kolors 免费+代金券付费线)/`pixai`(动漫垂直,每日 10,000 积分免费跟账号走,仅生图)/`cloudflare`(Workers AI,每日 10,000 neurons 免费续杯,仅生图)/`imagineart`(聚合舰队,🔴 免费层生成被 plan 墙锁,订阅 $13/月后可用)/`hfspaces`(免部署跑开源 Wan2.2 视频,ZeroGPU 免费配额)经 `provider` 显式点名(`provider="gemini"` / `provider="pixverse"` / `provider="siliconflow"` / `provider="pixai"` / `provider="cloudflare"` / `provider="imagineart"` / `provider="hfspaces"`)即用且钉死(失败直抛结构化错,绝不静默换渠道);费用安全由各自机制兜底(gemini 每次提交带配额警示;pixverse 两段式计费确认门 —— 首次只返回 `{needConfirm, estimatedCost, confirmToken}`,原参数 + confirmToken 复调才真提交,令牌 10 分钟有效与全部计费参数绑定;siliconflow 每次付费模型调用带价格警示,¥14 代金券先扣;pixai 免费积分池+每日 claim 告警;cloudflare premium 档逐张 neuron 警示,免费计划超额硬停零扣费)
- **渠道启用白名单(2026-09-24 起唯一开关)**:`"enabledProviders": ["agnes", "zhipu"]`(出厂默认)—— **生成渠道不在名单 = 未启用**,任何 `provider` 点名在路由层结构性拒绝(零网络,报错附启用指引);想用哪家电哪家:把渠道名加进名单即启用,如 `["agnes","zhipu","siliconflow","cloudflare","hfspaces","pixverse","gemini"]`(名单顺序在 ordered 策略下即使用顺序);env `MEDIA_ENABLED_PROVIDERS` 逗号分隔同语义。识别链(tesseract/paddle/vlm/glm-vision)不受白名单管辖,永远可用
- **渠道选择策略 `"providerStrategy"`**:`"caller"`(默认)—— 未点名 `provider` 时走免费池容灾,选择权在调用方(opt-in 渠道仍须显式点名);`"ordered"` —— 未点名时按 enabledProviders 名单顺序级联:第一个已配置且具备所需能力的渠道承接,失败顺延到下家;计费确认门(如 pixverse 两段式)在任何策略下照常生效。env `MEDIA_PROVIDER_STRATEGY` 同语义
- 🔴 **旧的 `imageProviderPriority` / `videoProviderPriority` 配置已废弃**:读到即打警告并忽略(可从 config.json 删除);渠道选择知识已内置于 generate_image / create_video 的 `provider` 参数描述(`provider` 选型对比:免费池 / gemini 高质量 / pixverse 多模型),`list_models` 同步透出路由说明
**Flow 资产管理(全 0 积分)**:`flow_status` 支持查积分/查状态/下载,以及分享(`shareMediaIds`)/取消(`cancelMediaIds`)/批量删除(`deleteMediaIds`)。配套 `"flow": { "toolDeadlineMs": 110000 }` 为 Flow 长操作设工具级截止(防卡死,超时转 `[flow] S410`,底层不取消,稍后经 `flow_status` 复查)。
**PixVerse 渠道(第 4 生成渠道,订阅积分池)**:spawn 官方 CLI(`pixverse --json`)接入你已登录的订阅池 —— 一个订阅聚合 25 个视频模型 + 14 个图像模型。**opt-in 语义(0.22.0)**:不进默认路由(省略 `provider` 永远免费池),显式 `provider="pixverse"` 点名即用且钉死;一切 image/video 提交必经**两段式计费确认门**(与 Flow 同款:首次只返回积分预估+确认令牌,原参数+令牌复调才真提交;令牌 10 分钟有效且单次消费)。各模型价格在 `list_models` 的 costCatalog 三态可查(实测落账 > 静态估算 > 未发布)。配置段 `"pixverse": { "confirm": true, "confirmTtlMs": 600000, "pinnedVersion": "1.4.3" }`;CLI 版本锁定 + 启动自检,漂移响亮告警。详见 `doc/PixVerse-provider集成.md`。
**Gemini 网页渠道(第 5 生成渠道,订阅算力配额)**:CDP UI 驱动 gemini.google.com 网页(「制作图片」= Nano Banana 2 /「制作视频」= Omni = Veo 3.1 系),零 API Key —— 用你已登录 Google AI 订阅的本机 Chrome。**opt-in 语义(0.22.0)**:不进默认路由(缺省永远免费池),显式 `provider="gemini"` 点名即用且钉死。
前置一次性(3 步):①`lasso launch-chrome --port 9225 --mode visible --idle-ms 0` ②在窗口里登录 Google(gemini.google.com 显示账号徽章)③`lasso chrome-hide` 收回后台;此后日常拉起用 hidden 档即可(`--idle-ms 0` 防回收,登录态在 profile)。端口可配(`GEMINI_CDP_PORT` / `providers.gemini.cdpPort`)。
用法:
- 生图:`generate_image(prompt="…", provider="gemini")`(模型固定 nano-banana-2;仅文生图,`images`/`aspect`/`size`/`seed`/`quality` 不消费,逐项 warning 告知;产物 JPEG)
- 生视频:`create_video(prompt="…", provider="gemini")`(模型 omni;**固定 8s / 24fps / 16:9**,`numFrames`/`frameRate`/`ratio` 等异值自动忽略并 warning)→ 返回伪 handle,`get_video(taskId=…, provider="gemini")` 轮询至 completed(MP4 直链自动落盘)
限制与纪律:
- **计费 = 订阅算力配额**(5h 滚动窗 + 周上限,无按次积分、无确认门):视频单条实测 ≈15-20% 5h 窗口,每次提交带配额警示 warning;图像消耗少量。配额读数唯一入口 = 网页 设置 → 用量限额;耗尽时页面报错转结构化 `[gemini] S400`(终态,等窗口刷新;**切 VPN 不重置**——配额绑账号,IP 只影响地区可用性)
- 🔴 **单 live 会话纪律**:一个 attach 页同时只驱动一个生成 —— 前一条 gemini 视频未 `get_video` 取件前,新提交被 `[gemini] S303` 拒绝(文案指路先取件;防导航走产物页导致配额沉没)
- 错误码族 `[gemini]`:S100 CDP 不可连 / S101 无页面或菜单入口缺失(附 UI 诊断)/ S102 未登录 / S103 页面执行异常 / S200 产物下载失败 / S300 模型 / S301 视频仅文生 / **S303 交错守卫** / S400 页面报错(含配额耗尽)/ S410 轮询超时(会话保留可重试)
- MVP 边界:文生图/文生视频(图生图、宽高比/风格参数化、视频图生视频未接,后续增强)
调研与实现全录:`doc/Gemini渠道调研-2026-09-22.md` + `doc/Gemini渠道落地-飞轮计划.md`。
---
### 二、识别类配置(识图 / OCR / 表格 / 图表 / 视觉理解)
识别能力分 4 档,**按需选装,默认档位 1 零配置即用**:
| 档位 | 能干什么 | 要配什么 | 费用 |
|---|---|---|---|
| **1 默认**(进程内)| 英文/数字/验证码/简单文档 OCR | **零配置** | 免费 |
| **2 智谱 GLM-4.6V-Flash** | 中文 SOTA + 复杂表格 + 图表读数 + 看图问答(全 4 task)| **一行 Key**(推荐,零部署)| **永久免费** |
| **3 PaddleX** | 中文 SOTA + 发票表格 + 版面分析 | 自托管(GPU 12GB 或 CPU 8GB 起)| 免费开源 |
| **4 vLLM Qwen2.5-VL** | 看图问答/手写/公式/复杂场景 | 自托管(GPU 16-24GB)| 免费开源 |
> 大多数用户:**档位 1 + 配一行档位 2 的 GLM Key 就齐了**;档位 3/4 给有 GPU、想全离线的用户(部署细节/CUDA 要求/Unlimited-OCR 长文档进阶见 [doc/自托管部署指南](doc/自托管部署指南.md))。
**档位 2 配置(最常用)**:
```json
{
"providers": {
"glm-vision": { "apiKey": "你的{id}.{secret}" }
}
}
```
- Key 申请:[open.bigmodel.cn](https://open.bigmodel.cn/console/apikey)(免费注册,格式 `{id}.{secret}`)
- ⚠️ 只接受标准 api_key;**Code Plan key(ZAI_API_KEY)不可用**(绑定 Z.ai 端点+白名单工具,违规调用会封号);多 key 轮换技术上支持但智谱协议禁止多账号,请自担合规风险
- 默认模型 `glm-4.6v-flash`(可经 `providers["glm-vision"].model` 换 `glm-4v-flash` 或付费视觉模型)
**档位 3/4 自托管**(服务跑起来后各填一行 baseUrl,细节见部署指南):
```json
{
"providers": {
"paddle": { "baseUrl": "http://127.0.0.1:8080" },
"vlm": { "baseUrl": "http://127.0.0.1:8000" }
}
}
```
---
### 三、自动兜底机制(配了就不用管)
- **生成侧**:Agnes ↔ 智谱,任一家失败自动切另一家(60 秒内连续失败触发软切换,你不用重启、不用改配置)
- **识别侧**:默认轻量引擎(进程内兜底)→ 按能力自动降级(fallback 按 tier 序:paddle(10)→ glm-vision(9)→ vlm(8);tesseract 是默认头兼最后兜底)
- **唯一例外**:视频轮询取片时**不切换**(避免拿到错的结果)
- 你要做的:配两家生成 API Key + 可选装一档识别服务,剩下的交给 Claude
> 你机器跑不动 PaddleX 或 vLLM?**继续用默认轻量引擎即可**,MCP 不会因为没装本地服务而报错 —— 只是中文 SOTA / 表格 / 看图问答 这几项能力不可用,其它全照常。
---
## 常见问题
**Q:不装任何东西能用吗?**
A:能。装上 MCP 就有画图 / 卡片 / 二维码 / 公式 / 数据图表 + 英文 / 验证码 OCR,全部本地跑,零联网。
**Q:识别中文乱码吗?**
A:默认轻量引擎对英文 / 数字 / 简单文档够用,中文准确率一般。要中文 SOTA 自托管 PaddleX(GPU 12GB 或 CPU 4 核 8GB),详见上方[配置详解](#配置详解)。
**Q:AI 视频要等多久?**
A:5 秒视频约 1–3 分钟,18 秒视频可能 5–10 分钟。后台异步生成,完成后自动通知你取片;预估 ≤60 秒的会同步等。
**Q:我的 RTX 3060 能跑表格识别吗?**
A:能。PaddleX GPU 模式最低 12GB VRAM(RTX 3060 12GB 正好),CPU 模式 4 核 + 8GB 内存也能跑(慢 3–5 倍)。详见[配置详解](#配置详解)。
**Q:中文 / emoji / 渐变能正常出吗?**
A:能。分享卡通过内置中文字体 + 排版引擎全自动支持中文、日文汉字、彩色 emoji、渐变标题、辉光效果,无需额外字体配置。
**Q:支持 Mermaid 吗?**
A:不支持(需要浏览器)。用 D2 或 Graphviz 代替,能力等价且更稳,矢量输出。
**Q:踩限流(429)?**
A:免费层有每分钟请求数限制。配两家服务方(Agnes + 智谱)后自动切换,基本无感。
**Q:视频帧数限制?**
A:随分辨率递减 —— 1080p ≤ 241 帧(约 10 秒),720p 可达 441 帧(约 18 秒)。可问 Claude 查实时约束。
**Q:npx 连不上 / 启动慢?**
A:全局装也行:先 `npm i -g media-gen-mcp-server`,再 `claude mcp add media-gen-mcp -s user "$(which media-gen-mcp-server)"`。
**Q:能用敏感词 / 武器 / 战争题材吗?**
A:真实武器词会触发内容过滤。改用科幻设定词(如"未来战甲"、"机甲")可绕过,效果等同。
**Q:Claude 会不会选错工具?(比如「做张分享卡」时去调生图)**
A:这类模糊请求的路由已经做过校准 —— 「做卡片 / 海报 / OG 图」「把图表里的数据读出来」「做产品片头动画」「画架构图 / 流程图」「把这组数据画成柱状图」等会自动落到合适的专用工具,无需手动纠正。当然你也可以在请求里直接点名某个工具。
---
## 这是给谁的
- **Claude Code 重度用户** —— 每周都要做几次图像任务,不想为每件事装一个 MCP、记一套参数。
- **写技术文档 / 博客的开发者** —— 反复需要架构图、时序图、ER 图、数据图、公式,不想离开工作流。
- **个人开发者 / 独立产品** —— 关注成本(全免费)与可控(同输入同输出),不想为图像任务单独搭后端。
- **数据 / 财务 / 法务** —— 双向场景:把数据画成图表,从截图 / 发票 / **PDF 报告 / 合同**里反向抽数据点(水印 / 红章可忽略,双栏论文按阅读序合并)。
- **教育 / 学术** —— 学生从课件截图 / 扫描讲义 / 论文 PDF 提文字、把双栏论文合并成连续文本、问图表里读出的数据;老师把纸质试卷扫描件变成可编辑文本。
- **运营 / 内容创作者 / 公众号作者** —— 分享卡 / OG 图 / 海报 / 二维码,中文 + 彩色 emoji + 渐变开箱即用。
> **不太适合**:不用 Claude Code 的用户;只要单一能力且已搭好流水线的工程化团队;需要付费商用模型 / 训练微调 / 实时视频 OCR 的场景(这些超出免费 MCP 范围)。
---
## 💝 支持作者
如果 media-gen-mcp 帮到你,欢迎请作者喝杯咖啡 ☕
微信 | 支付宝
:-: | :-:
|
Built for everyone who'd rather say it than script it.
装一次,以后所有图像活儿都是一句话。