OpenRouter GenImage Kote для Claude Code

openrouter-genimage-kote — это нативный плагин Claude Code, который генерирует и редактирует растровые изображения через OpenRouter. Основной рабочий сценарий — image-to-image: плагин может сохранять персонажа или объект, меняя позу, одежду, фон, освещение или стиль, а также может использовать до 16 упорядоченных референсов. Text-to-image доступен для новых изображений, которым не нужен визуальный референс.

Плагин подключается напрямую к фиксированному API-origin OpenRouter. В нём нет прокси-режима, KoteGateway, настраиваемого API origin, выбора маршрута или зависимости от внешнего брокера изображений.

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.

• Персональный API-ключ OpenRouter.

• Точный идентификатор image-модели OpenRouter, который поддерживает запрошенную операцию и параметры.

• Необязательно: управляющий ключ OpenRouter для полной информации о кредитах аккаунта.

Само поведение обновления MCP корней требует Claude Code 2.1.203+, но этот плагин намеренно устанавливает более высокий минимум 2.1.216 по причинам, указанным выше.

Related MCP server: openrouter-imgen-mcp

Установка из маркетплейса

В Claude Code добавьте GitHub-маркетплейс:

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

Установите плагин:

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

Плагин отключён по умолчанию, потому что генерация изображений может требовать оплаты. Откройте /plugin, настройте четыре параметра, описанных ниже, и включите плагин явно. Вводите секреты в интерактивном UI плагина: не помещайте настоящий API-ключ в команду оболочки, где он может сохраниться в истории.

Перезагрузите компоненты плагина после настройки:

/reload-plugins

Затем проверьте статус MCP:

/mcp

Сервер openrouter-images должен быть подключён и предоставлять три инструмента.

Конфигурация

Claude Code запрашивает эти значения userConfig, когда плагин включён:

Чувствительные значения маскируются и хранятся и через защищённое хранилище Claude Code. Плагин получает их только в виде переменных окружения в своём локальном MCP-процессе. Пустой управляющий ключ считается отсутствующим.

Намеренно нет настроек baseUrl, endpoint, маршрутизации, провайдера или прокси. Нельзя выбрать сетевую маршрут или незаметно выбрать другую image-модель.

Инструменты

Имена инструментов Claude Code получают пространство имён во время выполнения. Навык баланса привязан к ожидаемому имени mcp__plugin_openrouter-genimage-kote_openrouter-images__openrouter_balance, закреплённому в навыке и статических проверках для Claude Code 2.1.241. Его появление в живом списке инструментов остаётся интерактивной проверкой релиза.

Обе платные инструменты публикуют _meta["anthropic/requiresUserInteraction"] = true, поэтому Claude Code должен запрашивать явное разрешение при каждой генерации или редактировании. MCP-сервер не реализует собственный промпт и никогда не читает stdin за пределами MCP-транспорта.

Image-to-image: основной рабочий процесс

Попросите 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 должен вызвать openrouter_edit_image с референсом project_file. Локальный PNG, JPEG или WebP проверяется по реальному пути, размеру и магическим байтам, затем отправляется в памяти как base64 data 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, loopback, link-local, метаданные, http:, file:, data:, blob: и javascript: отклоняются. Явный HTTPS-референс передаётся в OpenRouter как есть; плагин не добавляет к этому URL авторизацию OpenRouter.

Несколько упорядоченных референсов

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 описывает роль каждого референса в этих запроса in same order and передаёт их в том же порядке. Плагин не сортирует, не объединяет, не удаляет и не переинтерпретирует их. Первый референс обычно является основным объектом.

Изображения, вставленные в чат

Публичный MCP-интерфейс принимает только доступный путь в рабочей области или публичный HTTPS URL. Если изображение вставлено в Claude Code, но модели не выставлен конкретный используемый путь, Claude не должен выдумывать путь или искать недокументированные кэши Claude Code. Сохраните вложение в проекте, например как assets/references/source.png, и укажите этот путь, или предоставьте публичный HTTPS URL.

Если поддерживаемая версия Claude Code предоставляет конкретный путь, он обрабатывается как обычный project_file только после проверки MCP корней.

Text-to-image

Используйте 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, и дополнительные изображения могут увеличить стоимость. Соотношение сторон, фон, формат, разрешение, качество, сжатие и seed передаются как параметры инструмента, когда они запрошены и поддерживаются настроенной моделью.

Перед платным запросом сервер определяет возможности модели. Он локально отклоняет неподдерживаемый ввод/вывод изображения или параметры и никогда не переключается на другую модель. Платный POST /images никогда не повторяется автоматически, потому что статус биллинга вышестоящей системы может быть неизвестен.

Выводы

Результаты записываются только внутри CLAUDE_PROJECT_DIR, даже если ресурс получен из дополнительного MCP корня. Все pathways relative to the project relative. Существующие файлы и исходные файлы никогда не перезаписываются; конфликты получают числовой суффикс. Запись использует полный временный файл с fsync и последующей атомарной публикацией no-clobber в той же директории; существующий приемник никогда не заменяется.

Результат MCP содержит краткий текст и структурированные данные: операцию, модель, запрошенные/возвращённые количества, число референсов, необязательную стоимость, сохранённые пути, MIME-типы, размер в байтах и предупреждения. Он никогда не возвращает полные байты изображения, base64, промпт или учётные данные. Если некоторые полученные элементы недействительны, корректные изображения сохраняются, а результат сообщает о частичном успехе. Если OpenRouter не возвращает usage.cost, плагин сообщает, что стоимость не была предоставлена, но не показывает ноль.

После генерации Claude должен сообщить точный сохранённый путь и проверить файл, прежде чем описывать его содержимое. Этот сохранённый путь можно использовать как следующий референс для image-to-image.

Корни рабочего пространства

Относительные входные пути разрешаются от CLAUDE_PROJECT_DIR. Абсолютные входные пути разрешены только тогда, когда их реальные пути являются обычными файлами внутри текущих MCP корней. Корни включают основной проект, а также неявные с помощью --add-dir, /add-dir или перегрузки факторов добавить каталоги в Claude Code. Сервер обновляет корни в памяти после notifications/roots/list_changed.

Дополнительные корни read-only с точки зрения плагина: каждый созданный результат остаётся в основном проекте. Лексический обход и выход через симлинк отклоняются как для входных, так и выходных путей.

Баланс и кредиты

Запустите нативный навык с использованием хранилища space:

/openrouter-genimage-kote:openrouter-balance

Вы также можете спросить: «Проверь мой баланс OpenRouter». Навык вызывает openrouter_balance ровно один раз и не запускает генерацию.

GET /key сообщает об использовании и лимитах расходования для текущего API-ключа. Его limit_remaining — это оставшийся лимит трат API-ключа, а не полный баланс счёта OpenRouter. Если настроен управляющий ключ (или текущий ключ явно идентифицирует себя как управляющий), плагин также вызывает GET /credits и сообщает общий кредит, общее использование счёта и их арифметическую разницу. Ошибка получения кредитов приводит к сообщению «недоступно», при этом успешная информация о ключе остаётся видимой. Ответы о балансе не кэшируются.

Безопасность и сетевое поведение

• Все аутентифицированные production-запросы идут напрямую на https://openrouter.ai/api/v1/ по HTTPS.

• Редиректы отклоняются, что предотвращает авторизацию на целевом адресе.

• Прокси-переменные окружения не читаются автоматически; нет глобального перехвата fetch, прокси-диспетчера, загрузчика шлюза или маркера маршрута.

• API-ключи передаются в локальный процесс, встроенный в среду, через подстановку переменных окружения, а не через аргументовых командной строки или файлы плагина.

• Логи пишутся в stderr как скрытые JSON-строки. Они исключают полные промпты, ключи, заголовки авторизации, base64, бинарные изображения и полные тела вышестоящих запросов.

• Локальные ссылки ограничены 20 MiB каждая, 50 MiB суммарно и 16 изображений. Общие ответы и декодированные изображения по умолчанию ограничены до 128 MiB.

• Публичные HTTPS-референсы раскрываются OpenRouter в рамках платного запроса. Используйте только URL-адреса, которые вы авторизованы передавать этому сервису.

См. SECURITY.md для безопасности и полной модели угроз.

Ограничения версии 0.1.0

Версия 0.1.0 не поддерживает маски, интерактивный инпейнтинг, пиксель-перфект-редактирование, внутренние идентификаторы вложений, недокументированные кэши изображений Claude, SVG-вывод, входные данные PDF/GIF/HEIC/TIFF/BMP/ICO, видео, LoRA-обучение, стриминговую генерацию изображений, UI плагина, объектное хранилище, внешний брокер изображений, автоматическое масштабирование входного изображения или автоматическую покупку кредитов. Провайдер-специфичный pas-through и автоматическое переключение моделей намеренно отсутствуют.

Изображения не гарантируют использование значений параметров и сидов: сохранют одинаковые пиксели или абсолютную воспроизводимость.

Устранение неполадок

MCP-сервер отключён

1. Проверьте, что node --version — 20 или новее.

2. Убедитесь, что Claude Code — 2.1.216 или новее.

3. Откройте /plugin и убедитесь, что плагин включён и все обязательные поля заполнены.

4. Выполните /reload-plugins, затем /mcp.

5. `Просматривайте отладочный вывод Claude Code и stderr от MCP. Никогда не вставляйте не стёртые ключи в issue.

Ошибка конфигурации

Откройте /plugin и исправьте API-ключ, точный ID image-модели и относительную выходную папку. Сервер регистрирует все инструменты даже при недействительной настройке при запуске; вызовы возвращают ошибку GENIMAGE_CONFIG_INVALID вместо выхода из строя MCP-транспорта.

Референс отклонён

Используйте PNG, JPEG или WebP; убедитесь, что файл находится в текущем MCP root и его размер меньше 20 MiB. Добавьте ещё одну директорию через Claude Code, а не копируйте абсолютный путь из внешней root. Для вставленного изображения сначала сохраните его в проекте.

Не поддерживается модель или параметр

Выберите точную модель OpenRouter, которая заявляет вывод изображений; для image-to-image также требуется ввод изображений и input_references. Удалите проблема с неподдерживаемыми параметрами или настройте список подходящую модель заново. Плагин не подбирает замену.

Результат уже существует

Выберите новый путь относительно проекта. Плагин намеренно не перезаписывает существующие файлы.

Обновление и удаление

Обновите маркетплейс и плагин:

/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, не выполняет сетевых запросов и создаёт один файл Node 20 ESM по пути plugins/openrouter-genimage-kote/dist/mcp-server.mjs, без карты исходников. Среда выполнения плагина не нуждается в соседней папке node_modules.

Явно запустите текущий закреплённый валидатор Claude:

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 всегда выполняет статические проверки манифеста, навыков, запрещённой маршрутизации и секретов. Он также запускает закэшированный CLI, если этот пакет уже есть в кэше npm; такой автоматический путь работает офлайн. CI вызывает закреплённый валидатор явно.

npm run smoke:marketplace копирует маркетплейс и плагин во временную структуру кэша и не затрагивает реальную конфигурацию Claude. Установите RUN_CLAUDE_MARKETPLACE_SMOKE=1, чтобы добавить/установить/удалить локальный маркетплейс с помощью Claude Code 2.1.241 в изолированных временных каталогах конфигурации и плагинов.

Реальные тесты 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

Дополнительный тест с управляющим ключом также считывает OPENROUTER_MANAGEMENT_API_KEY. Не помещайте настоящие учётные данные в файлы CI или журналы.

CI настроен для Ubuntu, macOS и Windows. Автоматические проверки охватывают исходный код, протокол, интеграцию, сборку, манифест и изолированное поведение маркетплейса. Интерактивные /mcp, выявление slash-навыков, диалог подтверждения каждого вызова и платное качество изображений остаются проверками на этапе выпуска — не делайте вывод об их выполнении на основании одной лишь успешной сборки исходников.

Лицензия и указание авторства

Распространяется по лицензии MIT. Платформонезависимые части были адаптированы на уровне исходного кода из openrouter-genimage-kote-opencode на коммите fd1e29d4a740d1765ce59d0a4a2ce722ce0a9258, также доступном по лицензии MIT. Уведомления о зависимостях и повторном использовании см. в THIRD_PARTY_NOTICES.md.