mediagen

mediagen — 为编码 Agent 提供图像和视频生成能力

通过 Google Gemini、OpenAI 和 Kie AI，为你的 Agent 提供图像和视频生成功能——一个技能，一次安装，无需学习 API。

大致描述你想要什么，然后让它决定其余事项：

You:   Make a hero image for the landing page, wide, something moody and industrial.

Agent: npx -y mediagen image "A disused loading dock at dusk, wet concrete…"
         --aspect-ratio 21:9 --json
       → ./output/image-20260823T094107Z.png

它完整写出了提示词，知道 OpenAI 不支持 21:9 规则，并从 --json 中读取路径。

或者明确提出要求，它就不再自行决定：

You:   Same thing with gemini-3-pro-image, 21:9, 4K, marked as AI-generated,
       saved as hero.png.

Agent: npx -y mediagen image "A disused loading dock at dusk, wet concrete…"
         --model gemini-3-pro-image --aspect-ratio 21:9 --size 4K
         --output-name hero.png --json
       → ./output/hero.jpg

       [looks at the image]

       npx -y mediagen mark ./output/hero.jpg --visible-label
         --label-position top-right --json
       → ./output/hero.labelled.jpg

看到主体的位置后，它在第二轮中标注了结果——并将标签放在平坦的屋顶线上，而不是货物装卸区上方。

CLI 能接受的任何参数，都可以用文字提出——提供商、模型、宽高比、尺寸、输出名称和目录、质量预设、视频时长、用于编辑的输入图像，以及是否标注结果。说出其中任何一项，Agent 就会按要求使用；如果没有提及，它会自行选择，或采用你配置的默认值。

安装

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

安装就这么简单。无需进行其他设置——该技能通过 npx 运行 CLI，首次使用时会下载，之后会将其缓存起来。

接着提供一个密钥：

npx -y mediagen init

交互式向导：选择提供商，逐个输入密钥（输入时不会显示），通过实时 API 验证每个密钥，为每个提供商选择一个模型，并设置默认值。只需一个密钥即可开始使用。

现在只要向你的 Agent 请求生成图像即可。

Agent 可以用它做什么

• 根据描述生成图像和视频，或编辑你已有的媒体
• 为任务选择合适的提供商——该技能知道 Gemini 支持 21:9 和视频，OpenAI 完全不支持 16:9，而 Kie 汇集了约 30 种第三方模型
• 按字面要求执行你的指令。 指定模型、宽高比、尺寸或文件名，它就会照做。想在选择前查看可用选项时，可以使用 mediagen models
• 妥善撰写提示词。 该技能内置了提示词撰写指南，因此在发送任何内容之前，它会将“一张氛围阴郁、富有工业感的主视觉图”扩写为包含主体、构图、光线、相机和材质的完整描述
• 在需要时标注 AI 生成的内容——对于任何写实风格或计划发布的内容，该技能都会建议进行标注
• 自行从故障中恢复，因为每个错误都附带机器可读的错误代码和后续操作

它不会做的事：要求你把 API 密钥粘贴到聊天中。 如果出现配置错误，该技能会提示你在自己的终端中运行 mediagen init。

前置条件

• 至少一个 API 密钥：
  • Google Gemini（在此获取）——支持图像和视频，支持的画幅范围最广
  • OpenAI（在此获取）——支持图像
  • Kie AI（在此获取）——约 30 种第三方模型
• Node.js 20.11 或更高版本

配置

mediagen init 可完成首次设置。之后如需修改设置：

npx -y mediagen config edit

菜单会列出每项设置、当前值及其来源——包括提供商、模型、密钥、输出目录、质量预设，以及 mediagen mark 的默认行为。每项更改都会在你进行操作时写入。

对于无法使用终端的 CI 和脚本，可以通过 config set 将相同的设置作为参数传入：

echo "$GEMINI_API_KEY" | npx -y mediagen config set gemini --stdin
npx -y mediagen config set gemini-model gemini-3-pro-image

使用哪个提供商

设置你偏好的顺序，最偏好的放在最前面：

npx -y mediagen config set provider-priority gemini,kie,openai

这是偏好顺序，而不是白名单。未指定 --provider 的请求会发送给顺序中第一个具备密钥且能完成任务的提供商——因此，缺少 OpenAI 密钥不会妨碍 Gemini 完成任务；请求视频时，也会直接跳过无法生成视频的提供商。指定 --provider 会覆盖上述所有设置。

mediagen models 会显示最终顺序、哪些提供商可用，以及请求会交由谁处理：

1. Google Gemini (gemini)  [preferred, key from config file]
  Would use: gemini-3.1-flash-image  (provider default)
2. Kie AI (kie)  [key from config file]
3. OpenAI (openai)  [preferred, no key]
  No key configured, so requests to it fail. Fix: mediagen config set openai

A request with no --provider uses gemini/gemini-3.1-flash-image.

使用 --json 时，还会添加 wouldUse、usableProviders 和 providerPriority。技能会让 Agent 在生成内容前读取这些信息，因此绝不会选择你没有密钥的提供商所提供的模型。

检查已配置的内容以及密钥是否仍然有效：

npx -y mediagen doctor

doctor 会逐个报告提供商的密钥是否已配置、密钥来自哪一层，以及提供商是否接受该密钥。它会区分_未配置_、已拒绝、无法连接_和_没有低成本的检查方法，因为这四种情况需要分别处理。

警告

特意不提供任何可将 API 密钥作为参数传入的标志。参数会留在 Shell 历史记录和进程列表中，即使命令已执行完毕，它们仍可能长期存在。

设置会依次从环境变量、工作目录中的 .env 文件和配置文件中读取：

提示

旧环境变量覆盖了你刚配置的密钥，是这类工具中代价最高的问题。mediagen config list 会标记所有被覆盖的值，让你直接看到问题，而不必猜测。

提供商

说明

OpenAI 接受的是像素尺寸，而非宽高比，而且确实无法生成 16:9 图像——它能生成的最宽图像为 1536×1024，也就是 3:2。请求 16:9 时，系统会明确拒绝，而不会悄悄提供其他比例的图像。技能了解这一限制，会将宽屏比例的请求路由到 Gemini。

即使某个模型没有列在清单中，请求仍会发送给相应提供商，因此，新发布的模型无需等待 mediagen 将其加入清单即可使用。Kie 的模型目录根据 Kie 自己的文档生成，而非手动维护。

内容标记

《欧盟 AI 法案》将披露分为两项义务，因此 mediagen mark 有两个独立开关：

生成操作永远不会添加标记。 标记始终是第二条命令，需要在生成文件后运行：

npx -y mediagen image "a wide banner" --aspect-ratio 21:9 --size 2K --json
npx -y mediagen mark ./output/image-….jpg --visible-label --label-position top-left

这并非形式主义。可见标签必须放在主体之外，而只有成品图像才能确定该放在哪里。机器可读标记也不是免费的：向 JPEG 或 WebP 添加元数据意味着要对其进行解码和重新编码，因此标记会带来第二次有损处理——这笔代价值得有意承担，而不应只是请求生成图像的副作用。mediagen 会以高质量重新编码，以尽量降低这笔代价，但无法将其完全消除。

若要让 mediagen mark 默认绘制可见标签，而不必每次都指定：

npx -y mediagen config edit      # "AI marking by default"

配置的默认值仍可在每次运行时通过 --no-mark 或 --no-visible-label 覆盖。

可见标签是欧盟委员会自己的图标，随《AI 生成内容透明度行为准则》发布，可免费使用，无需注明出处。它的三个版本中会使用两个：默认使用 AI GENERATED，对由人创作、再经模型修改的媒体，使用 --modified 生成 AI MODIFIED。系统会根据标签所在角落下方的实际内容，选择浅色或深色版本，因为没人能看清的标签就不算披露。

默认情况下，标签位于右下角。--label-position 可将其移至其他角落，或使用 auto 将其放在图像细节最少的位置。

重要

可见标签绝不会覆盖源文件。mediagen mark photo.png --visible-label 会生成 photo.labelled.png，并确保 photo.png 的像素完全不变，同时将机器可读标记写入该文件——因此，无论你发布这两者中的哪一个，都会包含披露信息。若标签位置不佳，可以从未改动的原始文件重新生成，不能从其他文件生成。 只有在确实需要时，才使用 --in-place 覆盖原文件。

不使用 Agent 时

这个技能是 CLI 的封装，而 CLI 本身也可以独立使用。

npx -y mediagen image "a wide banner" --aspect-ratio 21:9 --size 2K
npx -y mediagen image "make the sky stormy" --input ./photo.jpg
npx -y mediagen mark ./output/image-….jpg --visible-label
npx -y mediagen video "a marble rolling down a wooden track" --duration 6
npx -y mediagen models

如果你经常使用，想运行更短的命令，可以全局安装：

npm install -g mediagen

选项

提示

不使用技能时，提示词需要由你自己撰写。mediagen 会原样发送提示词——不会扩写或改写。请确定主体、构图、光线、相机或媒介、材质和氛围，并说明你想要什么，而不是不想要什么。

脚本编写

使用 --json 时，stdout 只包含一个 JSON 对象，不含其他内容。 不使用该选项时，保存路径位于最后一行；失败时 stdout 不会写入任何内容，因此读取最后一行时，绝不会把错误消息当作路径。

{
  "success": true,
  "filePath": "./output/image-20260823T094107Z.png",
  "kind": "image",
  "provider": "gemini",
  "model": "gemini-3.1-flash-image",
  "mimeType": "image/png"
}

失败时会附带一个 errorCode——取值为 VALIDATION_ERROR、CONFIG_ERROR、 API_ERROR、NETWORK_ERROR、FILE_ERROR、CONTENT_BLOCKED 或 TIMEOUT——以及一个 hint，说明具体的下一步操作。

将其用作 MCP 服务

适用于使用 MCP 通信，而不是运行技能的主机。使用同一个软件包，通过 mediagen mcp 启动，并提供 generate_media、list_models 和 check_configuration。

claude mcp add mediagen --env GEMINI_API_KEY=your-api-key-here -- npx -y mediagen mcp

{
  "mcpServers": {
    "mediagen": {
      "command": "npx",
      "args": ["-y", "mediagen", "mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

code --add-mcp "{\"name\":\"mediagen\",\"command\":\"npx\",\"args\":[\"-y\",\"mediagen\",\"mcp\"]}"

{
  "servers": {
    "mediagen": {
      "command": "npx",
      "args": ["-y", "mediagen", "mcp"]
    }
  }
}

运行 mediagen init 后，上述配置中的 env 都可以省略—— 服务会读取与 CLI 相同的配置。

工作原理

一条流水线，三个前端。技能驱动 CLI；MCP 服务则是基于同一核心的 第二个适配器。两者本身都不包含任何行为，因此某项功能不会只存在于其中一个而缺失于另一个。

      agent skill  ·  CLI  ·  MCP server
                     ↓
 request → model resolution → capability check → provider client
                     ↓
                save to disk → result

              mediagen mark → AI content marking

每个提供方都是一个独立目录，声明其支持的功能。 添加提供方时，只需在其目录之外修改一行。提供方清单不导入厂商 SDK，因此 doctor 和 config 无须加载 SDK。

src/
├── types/          leaf types everything shares
├── core/           pipeline, errors, capability checks, file handling
├── config/         the three configuration layers, key verification
├── providers/      one directory per provider, plus the registry
│   ├── gemini/
│   ├── openai/
│   ├── kie/
│   └── shared/     polling for asynchronous providers
├── cli/            the command tree; output.ts owns stdout
├── mcp/            the MCP server
└── marking/        AI content marking
skills/mediagen/    the agent skill
scripts/            catalogue generation, version syncing

贡献

请参阅 CONTRIBUTING.md，了解开发环境设置、如何添加提供方以及如何发布版本。