OpenRouter GenImage Kote for Claude Code

openrouter-genimage-kote 是一个原生 Claude Code 插件，可通过 OpenRouter 生成和编辑栅格图像。图生图是主要工作流：插件可以在改变姿势、服装、背景、光照或风格的同时保留角色或物体，并且最多可使用 16 个有序参考。文生图适用于不需要视觉参考的新素材。

该插件直接连接到固定的 OpenRouter API 源。它没有代理模式、KoteGateway、可配置的 API 源、路由选择，也不依赖外部图像代理。

Claude Code
    -> bundled local stdio MCP server
    -> direct HTTPS
    -> https://openrouter.ai/api/v1/
    -> generated file inside the primary project root

环境要求

• Claude Code 2.1.216 或更高版本。2.1.216 是受支持的最低版本，因为该插件依赖于修正后的插件技能命名空间行为以及安全的 userConfig 处理。开发验证固定使用 Claude Code 2.1.241。

• Node.js 20 或更高版本，并可作为 node 使用。

• 一个个人 OpenRouter API 密钥。

• 一个精确的 OpenRouter 图像模型 ID，且该模型支持所请求的操作和参数。

• 可选：用于完整账户额度信息的 OpenRouter 管理密钥。

MCP 根目录刷新行为本身需要 Claude Code 2.1.203+，但出于上述原因，此插件有意将最低版本提高到 2.1.216。

Related MCP server: openrouter-imgen-mcp

从 marketplace 安装

在 Claude Code 中添加 GitHub marketplace：

/plugin marketplace add koteyye/openrouter-genimage-kote-claude-code

安装插件：

/plugin install openrouter-genimage-kote@kote-plugins

该插件默认禁用，因为图像生成可能会产生费用。请打开 /plugin，配置下面描述的四项选项，然后显式启用插件。请在交互式插件 UI 中输入秘密：不要在 shell 命令中放置真实的 API 密钥，否则它可能被保留在 shell 历史中。

配置完成后重新加载插件组件：

/reload-plugins

然后检查 MCP 状态：

/mcp

openrouter-images 服务器应已连接并公开三个工具。

配置

启用插件后，Claude Code 会提示输入以下 userConfig 值：

敏感值会通过 Claude Code 的安全存储进行脱敏和保存。插件只能在其本地 MCP 进程中通过环境变量接收这些值。空的管理密钥被视为不存在。

这里刻意没有 baseUrl、endpoint、routing、provider 或 proxy 设置。功能不能选择网络路由，也不能静默选择另一个图像模型。

工具

Claude Code 工具名称在运行时会被命名空间化。余额技能限定为预期名称 mcp__plugin_openrouter-genimage-kote_openrouter-images__openrouter_balance， 该名称在技能以及 Claude Code 2.1.241 的检查中使用，并在技能与静态检查中固定显示。其出现在实时工具列表中仍是一个交互式发布门禁。

这两个付费工具都会在 _meta 中发布 "anthropic/requiresUserInteraction": true，因此 Claude Code 必须在每次生成或编辑调用之前寻求用户的明确批准。MCP 服务器不会实现自己的提示，也不会在 MCP 传输之外读取 stdin。

主图功能： 主要工作流程

请 Claude 编辑工作区中的某个路径：

Make the background transparent in assets/character.png and save the result as
assets/character-transparent.png. Preserve the character, clothing, proportions,
and illustration style.

Claude 应该使用 project_file 引用调用 openrouter_edit_image。本地 PNG、JPEG 或 WebP 会按真实路径、大小和 magic bytes 进行验证，然后以 base64 数据 URL 的形式在内存中发送。源文件不会被修改。

对于迭代编辑，请引用上一次工具调用返回的路径：

Create another variation of assets/generated/character-in-tavern.png with
evening lighting. Keep everything else as close as possible.

使用公共 HTTPS 引用

Use https://example.com/reference.webp as the visual reference and create a
matching inventory icon with a transparent background.

只接受无凭据的公共 https:// URL。Localhost、回环地址、链路本地地址、元数据地址，以及 http:、file:、data:、blob: 和 javascript: 输入都会被拒绝。显式的 HTTPS 引用会按原样传递给 OpenRouter；插件不会向该 URL 附加任何授权信息。

多个有序引用

Use assets/references/girl.png for identity and face,
assets/references/outfit.png for clothing only, and
https://example.com/style.webp for palette and lighting. Preserve that order.

Claude 在提示中描述每个参考的用途，并按相同顺序传递这些信息。插件不会对它们进行排序、合并、删除或重新解释。第一个参考通常是主要的主体。

粘贴到聊天中的图像

公共 MCP 接口仅接受可访问的 workspace 路径或公共 HTTPS URL。如果图像被粘贴到 Claude Code 中，但模型没有暴露具体可用的路径，Claude 不得伪造路径，也不得搜索 Claude Code 缓存。请先将附件保存到项目中，例如保存为 assets/references/source.png，然后提供该路径，或提供一个公共 HTTPS URL。

如果支持 Claude Code 版本提供了具体路径，那么只有当它通过 MCP 根限制验证后，才会被视为正常的 project_file。

文字生成图像

仅当没有可用于影响结果的现有视觉时，才使用 text-to-image：

Create a 1:1 inventory icon of one healing potion, centered with generous
padding, readable at small size, no text, transparent background, PNG.

默认生成一个结果。请明确要求多个替代方案；n 可从 1 到 10，额外的图像可能会增加费用。如果请求的模型支持，则长宽比、背景、格式、分辨率、质量、压缩和种子将作为参数传递。

交付付费请求之前，服务器会先发现模型能力。它会本地拒绝不支持的图像输入/输出或参数，并且绝不会回退到另一种模型。付费的 POST /images 不会被自动重试，因为上游计费状态可能未知。

输出目录

输出结果只会写入 CLAUDE_PROJECT_DIR 内部，即使有一个来自附加 MCP 根的 源路径。路径始终是项目相关的。现有文件永远不会被覆盖；如果冲突，会追加数字后缀。写入操作会使用完成且已同步的临时文件，然后在该目录中发布一个原子的不冲突，且不会任何现有文件。

MCP 会返回一段简洁的文本以及结构化内容，包括操作、模型、已请求/为止返回、已使用/可用阈值、可选成本、保存的路径、MIME 类型、字节大小和警告。它绝不会返回完整的图像字节、base64、提示或凭据。如果某些返回的项目无效，则已有效的图片会保存，结果会报告部分成功。如果 OpenRouter 未提供 usage.cost，插件会报告未提供 cost，而不是显示 0。

生成后，Claude 必须 报告确切的保存路径，并在描述视觉内容之前检查文件。该路径可用作下一个图像生成参考。

工作区根目录

输入路径解析为 CLAUDE_PROJECT_DIR。只允许在绝对路径为当前 MCP 根目录内的实际文件时才允许绝对路径。根 目录包括主项目以及使用 --add-dir、/add-dir 或 Claude Code 额外目录设置添加的附加目录。服务器会 在 notifications/roots/list_changed 刷新内存中的根目录。

附加根目录对于插件是只读的：所有生成的输出都保留在主项目内。对于输入和输出路径，都不允许路径穿越或 symlink 逃逸。

余额与额度

运行原生命名空间技能：

/openrouter-genimage-kote:openrouter-balance

你也可以请请求“检查我的 OpenRouter 余额”。该技能会立即调用 openrouter_balance，不会启动图像生成。

GET /key 会报告当前 API 密钥的使用情况/限制。它的 limit_remaining 值是 剩余的 API 密钥使用限制，不是整个 OpenRouter 账户余额。如果配置了管理密钥——或当前密钥明确标识其为管理密钥——插件还会再调用一次 GET /credits，并返回总额度、总账户使用量以及差异。如果调用失败，会报告为不可用，同时成功的额度信息仍然可见。余额响应不会缓存。

安全与网络安全行为

• 所有经过认证的生产请求均通过 HTTPS 直接访问 https://openrouter.ai/api/v1/。

• 重定向会被拒绝，防止授权信息传递到目标重定向。

• 不会自动读取代理环境变量；没有全局 fetch 拦截、代理 dispatcher、gateway bootstrap 或路由标记。

• API 密钥通过环境变量传递给本地进程，而不是使用命令行参数或插件文件。

• 日志以脱敏的 JSON 行输出到 stderr，日志不包含完整输入、密钥、授权标头、base64、二进制图片或完整上游响应体。

• 本地参考限制：每个最多 20 MiB，总 50 MiB，最多 16 个图像。默认，响应/解码图片的总字节限制为 128 MiB。

• 公共 HTTPS 引用会随付费请求一起交给 OpenRouter 使用。必须使用你有权共享的 URL。

请参阅 SECURITY.md 报告安全问题和获得完整安全信息。

版本 0.1.0 限制

如需进一步查看，请参见 0.1.0。0.1.0 不支持蒙版、交互式内绘、像素级编辑、内部图片，未文档化的 Claude 图像缓存、SVG 输出、PDF/GIF/HEIC/TIFF/BMP/ICO 输入，视频、LoRA 训练、流式生成、插件 UI、对象存储、外部图像代理、自动缩放或自动购买 功能。回声，机器模型，目前只支持 IsGenerator。图像模型：保留和种子不能保证完全相同像素或完全可复现结果。

故障排除

MCP 服务器已断开

1. 确认 node --version 返回的版本是 20 或更高。

2. 确认 Claude Code 版本是 2.1.216 或更高。

3. 打开 /plugin，确认插件已启用且所有必需选项均已填写。

4. 执行 /reload-plugins，然后执行 /mcp。

5. 检查 Claude Code 的调试输出和 MCP stderr。绝不要把未脱敏的 key 粘贴到 issue 中。

配置错误

打开 /plugin 并 修正 API key、图像模型 ID 和输出目录。是指服务器的所有工具都会注册，即使初始配置错误；调用会返回 GENIMAGE_CONFIG_INVALID，而不会移除 MCP 传输。

引用被拒绝

使用 PNG、JPEG 或 WebP，并确认文件位于 MCP 根目录下且小于 20 MiB。要添加另一个目录，请通过 Claude Code 而不是从立场所代理复制外部绝对路径。如果要粘贴图像，请先保存到项目中。

模型或参数不支持

选择支持图像输出的精确 OpenRouter 模型；图像生成还需要参考，并且 reference 必须合法。删除不支持的参数或自行设置模型。插件不会自动选择替代模型。

输出已存在

请选择一个不同的项目相对路径。该插件有意不覆盖现有文件。

更新和移除

刷新 marketplace 并更新插件：

/plugin marketplace update
/plugin update openrouter-genimage-kote@kote-plugins
/reload-plugins

卸载它：

/plugin uninstall openrouter-genimage-kote@kote-plugins

该插件本身不存储 API 密钥。卸载后生成的项目文件仍会保留；如果不再需要，应由用户手动删除。

开发与验证

npm ci
npm run ci

构建仅使用本地 esbuild，不发起任何网络请求，最终生成一个不包含 source map 的 Node 20 ESM 文件：plugins/openrouter-genimage-kote/dist/mcp-server.mjs。插件运行时不需要相邻的 node_modules 目录。

显式运行当前固定的 Claude Code 校验器：

npx --yes @anthropic-ai/claude-code@2.1.241 plugin validate ./plugins/openrouter-genimage-kote --strict
npx --yes @anthropic-ai/claude-code@2.1.241 plugin validate . --strict

npm run validate:plugin 始终执行静态 manifest、skill、禁止路由和密钥（secret）检查。当 npm 缓存中已有对应包时，它还会运行固定的 CLI；这条自动路径是离线的。CI 会显式调用固定的校验器。

npm run smoke:marketplace 会将 marketplace 和插件复制到临时缓存目录中，不会修改真实的 Claude 配置。设置 RUN_CLAUDE_MARKETPLACE_SMOKE=1 后，即可在隔离的临时配置和插件目录中，使用 Claude Code 2.1.241 添加/安装/列出/卸载本地 marketplace。

真实的 OpenRouter 测试需要付费，默认是禁用的：

RUN_OPENROUTER_E2E=1 \
OPENROUTER_API_KEY="<enter through a secure CI secret or local environment>" \
OPENROUTER_IMAGE_MODEL="provider/model-id" \
npm run test:e2e

一个可选的管理密钥（management-key）额度测试还会读取 OPENROUTER_MANAGEMENT_API_KEY。请勿将真实凭据放入已提交的文件或命令历史中。

CI 已配置为支持 Ubuntu、macOS 和 Windows。自动化检查覆盖 source、protocol、integration、bundle、manifest 以及隔离的 marketplace 行为。交互式 /mcp、slash-skill 发现、每次调用的确认对话框，以及付费图像质量仍是发布门禁检查；不要因为源码构建成功，就推断这些检查都已经执行过。

许可证与署名

本项目以 MIT 许可证发布。平台无关的部分在源码层面改编自 openrouter-genimage-kote-opencode 的提交 fd1e29d4a740d1765ce69b80aceb722cec0a9258b，该项目同样采用 MIT 许可证。完整的依赖与复用声明见 THIRD_PARTY_NOTICES.md。