mediagen

这是什么？适合谁？

mediagen 是一个面向编码 Agent（Claude Code、Codex 等）的 AI 图像与视频生成 Skill，GitHub 55 Stars（MIT 协议），以 npm 包形式分发。它的定位一句话讲清：一个 Skill、一次安装，横跨 Google Gemini、OpenAI、Kie AI 三家生成能力，无需学任何 API。

核心机制是「说个大概，它决定其余」：你描述意图（「给落地页做张 hero 图，宽幅，压抑的工业感」），Agent 自己展开完整 prompt、调用 CLI（npx -y mediagen image ...）、处理各家的怪癖（如 OpenAI 不支持 21:9 时自动换比例或模型）、读回 --json 返回的文件路径。你也可以精确指定模型/比例/尺寸/输出名，它就照办不再自作主张。

典型能力：

• 图像生成：跨 Gemini / OpenAI / Kie AI，支持宽高比、4K、质量档位
• 图像编辑：输入参考图做修改
• 视频生成：含时长控制
• AI 标注（mark）：给生成图打「AI-generated」可见标签，支持指定标签位置—Agent 会先看图再把标签放到不遮挡主体的位置（如平坦屋顶线而非装卸区上方）

适合人群：

• 前端/全栈开发者：构建中需要配图（hero 图、占位图、社交封面），不想切换工具
• 用 Agent 写 Landing Page 的人：一句「配张图」直接在代码工作流里完成
• 独立开发者：注册三家 API 太麻烦，一次向导（mediagen init）配齐所有 key

不适合：专业设计师的精修工作流（Midjourney/ComfyUI 的控制深度）；纯聊天用户（它是给编码 Agent 的 Skill）。

使用前提：Node.js 环境（npx）；至少一家 provider 的 API key；一个支持 Skill 的编码 Agent。

准备工作

1. Node.js：任意现代版本（npx 可用即可）。
2. API key：Google Gemini / OpenAI / Kie AI 任选一家起步，多家可后续加。
3. 安装：一条命令（见下），CLI 通过 npx 首次拉取并缓存。
4. 成本：Skill 免费；生成消耗各 provider 的 API 费用（图像约 $0.03-0.2/张、视频更贵，以各家定价为准）。
5. 时间预算：安装+配置 5 分钟；第一张图 1 分钟内。

3 步快速上手

第 1 步：安装 Skill

npx -y skills add Cripacx/mediagen --skill mediagen

这就是全部安装—CLI 由 npx 按需拉取，无需预装。

第 2 步：配置 key

npx -y mediagen init

交互式向导：选 provider、逐个输入 key（不回显）、对着线上 API 验证每个 key、为每家选默认模型。一个 key 就够起步。

第 3 步：向 Agent 要一张图

给这个落地页做一张 hero 图：宽幅、黄昏的废弃装卸码头、湿漉漉的水泥地，
阴郁的工业感。

Agent 会自己展开完整 prompt、选择合适的模型与宽高比（21:9 等）、执行 npx -y mediagen image ... --json 并把生成路径汇报给你。

预期结果：./output/ 下出现生成的图片文件，Agent 知道路径可直接引用（如写入 HTML）。成功判定：图像分辨率/比例符合用途，文件路径在对话中可查。

常见踩坑

踩坑 1：以为要手动学三家 API

• 现象：先去读 OpenAI/Gemini 文档再装 Skill。
• 原因：把 Skill 当成了普通工具而非 Agent 的能力扩展。
• 解决：完全不需要—Agent 通过 CLI 处理所有 API 差异，你只管用自然语言。

踩坑 2：宽高比指定了模型不支持的值

• 现象：坚持 21:9 但选了不支持该比例的模型。
• 原因：各家模型的比例支持不同（README 示例中 OpenAI 不支持 21:9）。
• 解决：不指定比例让 Agent 自己选；或指定比例后让 Agent 换支持的模型（Skill 的 fallback 逻辑会处理）。

踩坑 3：忘了 init 就直接生成

• 现象：调用报错找不到 key。
• 原因：跳过了 mediagen init 配置步骤。
• 解决：跑一次 init 向导；多个 key 可以分批添加，验证每把 key 后再继续。

踩坑 4：AI 标注挡住主体

• 现象：生成图的 label 盖在关键内容上。
• 原因：一次性生成+标注时位置固定。
• 解决：用两段式—先生成，Agent 看图后再 mediagen mark 指定 --label-position（如 top-right）；README 演示的正是这种「看了图再标注」的工作流。

踩坑 5：视频生成成本失控

• 现象：随手要视频，账单超预期。
• 原因：视频生成比图像贵一个量级。
• 解决：开发阶段全用图像占位，最终版才出视频；明确指定时长参数。

踩坑 6：缓存后不改版本

• 现象：CLI 更新了新模型支持，本地还是旧行为。
• 原因：npx 缓存了旧版本。
• 解决：定期 npx -y mediagen@latest 或清 npx 缓存。

初级用法

1. 配图补全：写页面时说「这节缺张图，按上下文生成」，Agent 用周围文案推断内容风格。
2. 精确指定：「用 gemini-3-pro-image、21:9、4K，存成 hero.png」—所有参数照办，Agent 不再自行决定。
3. 社交封面：为博客文章生成 OG 图，比例 1200x630 等价参数。

高级玩法

1. 两段式标注流水线：生成 -> Agent 查看主体位置 -> mark 放标签到安全区域，产出合规的 AI 内容披露图。
2. 参考图编辑：给一张产品图，让 Agent 生成不同背景/光照的变体（图像编辑模式）。
3. 多 provider 比价：同一 prompt 分别指定三家生成，人眼选最佳；Skill 屏蔽了各家 API 差异使这成为一句话的事。
4. 构建时生成：把生成步骤写进构建脚本，让 hero 图随主题/季节自动更新。

小技巧

1. 说意图不说参数：「宽幅、阴郁工业感」比「1920x820」更能让 Agent 选对模型和比例。
2. --json 是关键：让 Agent 用 json 输出模式，路径解析零歧义，后续引用不猜。
3. 默认模型先跑通：init 时选的默认模型先用于验证流程，再尝试高端模型（更贵更慢）。
4. output 目录提前规划：生成物默认进 ./output/，项目里记得加 .gitignore 或改成资源目录。
5. 质量档位区分用途：草稿用低质量档位省钱，终稿再上 4K。

常见问题 FAQ

Q1: 和直接调 OpenAI/Gemini API 有什么区别？

A: 区别在「谁写调用代码」。直接调 API 你要读文档、处理各家参数差异（比例/尺寸/质量命名的不同）、解析响应；mediagen 让 Agent 写好全部调用并处理怪癖（如 OpenAI 的 21:9 限制），你只用自然语言。三家能力一个 Skill 全覆盖。

Q2: 支持哪些模型？

A: Google Gemini（含 gemini-3-pro-image 等）、OpenAI 图像模型、Kie AI 的生成模型，具体列表以 mediagen init 向导内可选项为准（2026-08-25 核验时 README 未列全量型号）。

Q3: 一定要付费 API 吗？

A: 是。Skill 本身免费开源，但生成消耗 provider 费用。Google AI Studio 有免费额度可起步；商用规模建议直接看各家定价页。

Q4: 能在 Claude Code 之外的 Agent 用吗？

A: 可以。Skill 是标准 Agent Skill 格式（支持 Claude Code、Codex 等），核心是 npm CLI，任何能跑 shell 命令的 Agent 都能配合使用；纯聊天机器人（无执行环境）不行。

Q5: 生成的内容有版权问题吗？

A: 各 provider 对生成内容的权利声明不同（以各家服务条款为准）。带 mark 功能给图打 AI 生成标注，可用于满足平台对 AI 内容的披露要求，但不等于法律确权。

参考链接

• GitHub 仓库
• npm 包

本文基于公开资料整理（GitHub 仓库 README 与 npm 页面，数据核验日期 2026-08-25），AI 辅助生成。