OpenRouter GenImage Kote para Claude Code

openrouter-genimage-kote es un plugin nativo de Claude Code que genera y edita imágenes ráster a través de OpenRouter. El flujo de trabajo principal es imagen a imagen: el plugin puede conservar un personaje u objeto mientras cambia la pose, la ropa, el fondo, la iluminación o el estilo, y puede usar hasta 16 referencias ordenadas. La generación de texto a imagen está disponible para nuevos activos que no necesitan una referencia visual.

El plugin se conecta directamente al origen fijo de la API de OpenRouter. No tiene modo proxy, KoteGateway, origen de API configurable, selección de ruta ni dependencia de un intermediario de imágenes externo.

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

Requisitos

• Claude Code 2.1.216 o posterior. La versión 2.1.216 es la versión mínima compatible porque este plugin depende del comportamiento corregido del espacio de nombres de plugin-skill y del manejo seguro de userConfig. La validación de desarrollo está fijada a Claude Code 2.1.241.

• Node.js 20 o posterior disponible como node.

• Una clave de API personal de OpenRouter.

• Un ID exacto de modelo de imagen de OpenRouter que admita la operación y los parámetros solicitados.

• Opcional: una clave de administración de OpenRouter para obtener información completa de los créditos de la cuenta.

El comportamiento de actualización de las raíces de MCP en sí mismo requiere Claude Code 2.1.203+, pero este plugin establece deliberadamente el mínimo superior de 2.1.216 por las razones anteriores.

Related MCP server: openrouter-imgen-mcp

Instalación desde el marketplace

En Claude Code, añade el marketplace de GitHub:

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

Instala el plugin:

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

El plugin está deshabilitado por defecto porque la generación de imágenes puede generar costes. Abre /plugin, configura las cuatro opciones descritas a continuación y habilita explícitamente el plugin. Introduce los secretos en la interfaz interactiva del plugin: no pongas una clave de API real en un comando de shell, donde podría quedar guardada en el historial del shell.

Recarga los componentes del plugin después de la configuración:

/reload-plugins

A continuación, inspecciona el estado de MCP:

/mcp

El servidor openrouter-images debería estar conectado y exponer tres herramientas.

Configuración

Claude Code solicita estos valores de userConfig cuando el plugin está habilitado:

Los valores sensibles se enmascaran y se almacenan mediante el almacenamiento seguro de Claude Code. El plugin los recibe únicamente como variables de entorno en su proceso local de MCP. Una clave de administración vacía se considera ausente.

Deliberadamente no hay ningún ajuste de baseUrl, de endpoint, de proxy, de proveedor ni de enrutamiento. El modelo no puede elegir una ruta de red ni seleccionar silenciosamente otro modelo de imagen.

Herramientas

El servicio MCP expone tres herramientas:

Los nombres de las herramientas de Claude Code reciben un espacio de nombres en tiempo de ejecución. La habilidad openrouter_balance está asignadas al nombre esperado mcp__plugin_openrouter-genimage-kote_openrouter-images__openrouter_balance, fijado en la habilidad y las comprobaciones estáticas para Claude Code 2.1.241. Su aparición en la lista real de herramientas sigue siendo una comprobación interactiva de la fase de publicación.

Ambas herramientas de pago publican _meta["anthropic/requiresUserInteraction"] = true, por lo que Claude Code debe solicitar una aprobación explícita en cada generación o edición. El servidor MCP no implementa su propio aviso de usuario y nunca lee de stdin fuera del transporte MCP.

Imagen a imagen: flujo de trabajo principal

Pide a Claude que edite una ruta dentro del área de trabajo:

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 debe llamar a openrouter_edit_image con una referencia project_file. Una imagen PNG, JPEG o WebP local se comprueba por ruta real, tamaño y bytes mágicos, y luego se envía en memoria como data URL de base64. El archivo original nunca se modifica.

Para una edición iterativa, consulta la ruta devuelta por la llamada bloquean:

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

Referencias HTTPS públicas

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

Solo se aceptan URL públicas con https:// que no contengan credenciales. Se rechazan los que incluyen localhost, loopback, enlace local, direcciones de metadatos, http:, file:, data:, blob: y javascript:. Una referencia HTTPS explícita se envía a OpenRouter tal cual se ha pasado; el plugin no adjunta la autorización de OpenRouter a esa URL.

Múltiples referencias ordenadas

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 describe el papel de cada referencia en el aviso y las pasa en el mismo orden. El plugin no las ordena, combina, elimina ni reinterpreta. La primera referencia suele ser el asunto principal.

Imágenes pegadas en el chat

La interfaz MCP pública solo acepta una ruta accesible del área de trabajo o una URL HTTPS pública. Si se pega una imagen en Claude Code pero no se expone al modelo una ruta concreta útil, Claude no debe inventar una ruta ni buscar en cachés no documentados de Claude Code. Guarda el archivo adjunto no dentro el proyecto, por ejemplo assets/references/source.png, y proporciona esa ruta, o proporciona una URL HTTPS pública.

Si una versión compatible de Claude Code proporciona una ruta real, esta se considera un project_file normal solamente después de pasar la validación de la zona raíz MCP.

Texto a imagen

Usa la opción de texto a imagen solo cuando ninguna imagen existente deba influir en el resultado:

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

De forma predeterminada se genera un resultado de la imagen. Pide varias alternativas explícitamente; n puede ser de 1 a 10 y las imágenes adicionales pueden aumentar el coste. La relación de aspecto, el fondo, el formato, la resolución, la calidad, la compresión y la semilla se pasan como parámetros de la herramienta cuando se solicitan y el modelo configurado los admite.

Antes de la solicitud de pago, el servidor descubre las capacidades del modelo. Rechaza localmente la entrada/salida de imágenes o los parámetros no compatibles y nunca avanza usar otro modelo. Una POST /images de pago nunca se reintenta automáticamente porque el estado de facturación del proveedor puede ser desconocido.

Salidas

Los resultados se escriben exclusivamente dentro de CLAUDE_PROJECT_DIR, incluso cuando una fuente proviene de una raíz MCP adicional. Las rutas son relativas al proyecto. Nunca se sobrescriben archivos existentes ni archivos de origen; los conflictos reciben un sufijo numérico. Las escrituras utilizan un archivo temporal completo y sincronizado (fsync), seguido de una publicación atómica sin reemplazo en el mismo directorio. Un destino existente nunca se reemplaza.

El resultado de la herramienta MCP contiene texto conciso y contenido estructurado con información sobre la operación, el modelo, las cantidades solicitadas y devueltas, recuento de referencias, de ser así de coste, las rutas guardadas, los tipos MIME, los tamaños de byte y las advertencias. Nunca devuelve los bytes completos de la imagen, no devuelve base64, el prompt ni credenciales. Si algún elemento devuelto no es válido, las imágenes individualmente válidas se guardan y el resultado informa un éxito parcial. Si OpenRouter omite usage.cost, el plugin notifica que no se dispone del coste en lugar de mostrar cero.

Después de la generación, Claude debe notificar la ruta exacta guardada e inspeccionar el archivo antes de describir sus contenidos visuales. Esa ruta guardada puede usarse como siguiente referencia de imagen a imagen.

Raíces de espacio de trabajo

Las rutas de entrada relativas se eligen desde CLAUDE_PROJECT_DIR. Las rutas de entrada absolutas solo se permiten si sus rutas reales son archivos regulares dentro de los rizos MCP actuales. Las raíces incluyen el proyecto principal y los directorios añadidos con --add-dir, /add-dir o con los ajustes de directorios adicionales de Claude Code. El servidor refresca sus raíces en memoria después de notifications/roots/list_changed.

Las raíces adicionales son de solo lectura desde la perspectiva del plugin: cada salida generada permanece en el proyecto principal. Se rechaza el recorrido por rutas relativas y el escape de enlaces simbólicos tanto para las rutas de entrada como de salida.

Balance y créditos

Ejecuta la habilidad nativa con el espacio de nombres:

/openrouter-genimage-kote:openrouter-balance

También puede preguntar: “Comprueba mi balance de OpenRouter”. La habilidad llama a openrouter_balance exactamente una vez y no genera una generación.

GET /key informa del uso y del límite de gasto de la clave de API actual. Su valor de limit_remaining es el límite de gasto restante de la clave de API, no el balance completo de la cuenta de OpenRouter. Si está configurada una clave administración —o si la clave actual identifica explicitamente como clave de administración—, el plugin llama también a GET /credits e informa del balance total, el uso total de la cuenta y su diferencia aritmética. Si falla créditos, se notifica como no disponible mientras que el uso de clave con éxito sigue siendo visible. Las respuestas del balance no se almacenan en caché.

Seguridad y comportamiento de red

• Todas las solicitudes autenticadas de producción se envían solo a https://openrouter.ai/api/v1/ mediante HTTPS.

• Las redirecciones se rechazan, lo que impide que la autorización se envíe a un objetivo de redirección.

• Las variables de entorno de proxy no se leen automáticamente; no existe interceptación global de fetch, despachador de proxy, bootstrap pasarela ni marcador de ruta.

• Las claves de API se pasan al proceso local a través de sustancias del entorno, nunca mediante objetos de línea de comandos ni archivos de plugin.

• Los registros se emiten a stderr como líneas JSON redactadas. No contienen prompts completos, claves, encabezados de autorización, base64, imágenes binarias ni cuerpos de respuestas completos.

• Las limitaciones locales se limitan a 20 MiB definidas, 50 MiB en total y 16 imágenes. El total de respuestas e imágenes descodificas se limita a 128 MiB de forma predeterminada.

• Las referencias HTTPS públicas se envían a OpenRouter como parte de la solicitud de pago. Usa siempre las URL que tengas permitidas compartir con ese servicio.

Consulta SECURITY.md para notificaciones de vulnerabilidades y el modelo de amenazas completo.

Limitaciones de la versión 0.1.0

La versión 0.1.0 no admite máscaras, inpainting interactivo, edición de píxeles exactos, identificadores internos de activos, cachés de imágenes no documentados, salida SVG, entrada de PDF, GIF, HEIC, TIFF, BMP o ICO, generación de vídeo, entrenamiento LoRA, streaming de imágenes, interfaz de plugin, almacenamiento de objetos, procesamiento de imágenes externo, cambio de mandos ni redimensionamiento automático de entrada. El paso directo específico del proveedor y el cambio automático de modelo están presentes de forma deliberada no implementados.

Los modelos de imágenes son generativos: la preservación y las semillas no garantizan píxeles idénticos ni una reproducibilidad absoluta.

Solución de problemas

El servidor MCP está desconectado

1. Confirma que node --version sea 20 o superior.

2. Confirma que Claude Code sea 2.1.216 o superior.

3. Abre /plugin y verifica que el complemento esté habilitado y todas las opciones obligatorias no estén vacías.

4. Ejecuta /reload-plugins, después /mcp.

5. Revisa la salida de producción de Claude Code y la salida de error del MCP. Nunca pegues claves no protegidas en un problema.

Error de configuración

Abre /plugin y corrige la base de conocimiento la clave de API, el ID exacto del modelo de imagen y el directorio relativo que prefiera. El servidor registra todas las herramientas incluso si la configuración inicial no es válida; las llamadas devuelven GENIMAGE_CONFIG_INVALID en lugar de tumbar el transporte MCP.

Referencia rechazada

Use PNG, JPEG o WebP; verifica que el archivo esté dentro de una raíz MCP actual y sea menor de 20 MiB. Añade otro directorio a través de Claude Code en place del ruta absoluta desde una raíz no conocida. Si se pega una imagen, guárdala primero dentro del proyecto.

Modelo o parámetro no compatible

Seleccione un modelo de OpenRouter que ofrezca salida de imagen y que anuncie explícitamente soporte para imagen: entrada de imagen imágenes e input_references para la edición. Elimina los parámetros opcionales no compatibles o elegi un modelo adecuado usted mismo. El plugin elegirá un modelo sustitutivo no.

La salida ya existe

El poder usar proyecto nuevo como salida. El plugin intencionalmente no sobrescribe los archivos existentes.

Actualizar y eliminar

Refresca el marketplace y actualiza el plugin:

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

Elimínalo con:

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

El plugin no almacena claves de API por sí mismo. Los archivos de proyecto que se generan persisten después de la desinstalación y deben ser eliminados por el usuario si ya no se necesitan.

Desarrollo y verificación

npm ci
npm run ci

La compilación usa únicamente el esbuild local, no realiza ninguna solicitud de red y genera un único archivo ESM de Node 20 en plugins/openrouter-genimage-kote/dist/mcp-server.mjs, sin mapa de fuentes. El runtime del plugin no necesita un directorio node_modules adyacente.

Ejecuta explícitamente el validador de Claude fijado actualmente:

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 siempre realiza comprobaciones estáticas del manifiesto, las habilidades, el enrutamiento prohibido y los secretos. También ejecuta la CLI fijada cuando ese paquete ya está disponible en la caché de npm; esta ruta automática funciona sin conexión. CI invoca explícitamente el validador fijado.

npm run smoke:marketplace copia el marketplace y el plugin a una estructura de caché temporal y no toca la configuración real de Claude. Establece RUN_CLAUDE_MARKETPLACE_PRUEBA=1 para añadir/instalar/listar/desinstalar el marketplace local con Claude Code 2.1.241 en directorios de configuración y de plugin temporales aislados.

Las pruebas reales de OpenRouter son de pago y están deshabilitadas por defecto:

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

Una prueba opcional de créditos con clave de gestión también lee OPENROUTER_MANAGEMENT_API_KEY. No pongas credenciales reales en archivos versionados ni en el historial de comandos.

CI está configurado para Ubuntu, macOS y Windows. Las comprobaciones automatizadas cubren el código fuente, el protocolo, la integración, el bundle, el manifiesto y el comportamiento aislado del marketplace. El /mcp interactivo, el descubrimiento de las slash-skills, el diálogo de confirmación por llamada y la calidad de imagen de pago siguen siendo controles previos al lanzamiento; no asumas que se ejecutaron únicamente al haber compilado correctamente el código fuente.

Licencia y atribución

Licenciado bajo MIT. El total las jornadas. Las partes independientes de la plataforma se adaptaron a nivel de código fuente a partir de openrouter-genimage-kote-opencode en la confirmación fd1e29d4a740b0d1780c5a0b5b0ce59c0a4258b, también con licencia MIT. Consulta THIRD_PARTY_NOTICES.md para los avisos de dependencias y reutilización.