Openrouter Image (openrouter-image)

openrouter映像

](https://www.npmjs.com/package/@mindbreaker81/openrouter-image)   ](https://nodejs.org) ](https://github.com/Mindbreaker81/openrouter-image/releases/latest)

双接口MCP服务器和CLI，用于通过OpenRouter的Responses API生成/编辑图像。

此软件包可用于多种方式：

• 📚 作为图书馆 -用于Node.js应用程序的程序化API
• 🖥️ 作为CLI -用于自动化和脚本编写的命令行界面
• 🔌 作为MCP服务器 -适用于Claude Code、Cursor和其他MCP兼容工具
• 🤖 作为Claude代码技能 -与Claude Code的原生集成

所有接口共享一个 共同核心 (src/core.js)并提供相同的功能。

______________________________________________________________________

目录

• 使用模式

- 出版 - 作为图书馆 - 作为CLI - 作为MCP服务器 - 作为Claude代码技能

• 安装
• 需求
• 环境变量
• MCP服务器（HTTP）

- 服务器端口和冲突

• 命令行界面
• MCP工具——参考
• 编码工具中的配置
• 卷曲示例（MCP JSON-RPC）
• 测试
• 项目结构
• 安全
• 许可证

______________________________________________________________________

使用模式

作为图书馆

使用 OpenRouterImageClient Node.js应用程序中的类：

import { OpenRouterImageClient } from '@mindbreaker81/openrouter-image';

const client = new OpenRouterImageClient({
  apiKey: process.env.OPENROUTER_API_KEY,
  defaultModel: 'google/gemini-2.5-flash-image'
});

// Generate an image
const result = await client.generateImage('A sunset over mountains', {
  outputPath: 'sunset.png'
});

console.log(`Image saved to: ${result.savedPath}`);

文档： 看 图书馆.md 以获取API的完整参考和示例。

作为CLI

全局安装并从命令行使用：

npm install -g @mindbreaker81/openrouter-image

# Generate an image
openrouter-image generate "A futuristic city" -o city.png

# Edit an image
openrouter-image edit "Make it rainy" -i city.png -o rainy-city.png

# List available models
openrouter-image models

# List saved images
openrouter-image list

请参阅下文 CLI文档.

作为MCP服务器

作为HTTP或stdio MCP服务器运行，以与AI编码工具集成：

# HTTP mode (default port 3000)
openrouter-image server

# Stdio mode (for Claude Code)
openrouter-image server --stdio

请参阅下文 MCP服务器文档.

作为Claude代码技能

安装和配置为本地Claude代码技能：

npm install -g @mindbreaker81/openrouter-image
./scripts/install-claude.sh

然后直接在Claude Code中使用：

• “生成日落图像”
• “编辑diagram.png以添加数据库”
• “显示所有可用型号”

文档： 看 CLAUDE_SKILL.md 有关详细的设置说明。

______________________________________________________________________

需求

• Node.js>=20 （使用ES模块和 node:test)
• npm （包含在Node.js中）
• 一 OpenRouter API密钥 (在这里买一个)

______________________________________________________________________

安装

从npm安装

npm install -g @mindbreaker81/openrouter-image

从git安装

git clone https://github.com/mindbreaker81/openrouter-image.git
cd openrouter-image
npm install
npm link

从tarball安装

npm pack
npm install -g mindbreaker81-openrouter-image-*.tgz

作为库依赖项安装

npm install @mindbreaker81/openrouter-image

______________________________________________________________________

环境变量

复制 .env.example 一 .env 并填写值：

cp .env.example .env

如果您想将图像保存到 ./output 而不是 /data，定义en tu .env: OUTPUT_DIR=./output。MCP服务器和CLI都使用它。

备注: AUTH_TOKEN 只有MCP服务器使用它。CLI只需要 OPENROUTER_API_KEY 可选地 OUTPUT_DIR.

______________________________________________________________________

MCP服务器（HTTP）

服务器通过带有Bealer身份验证的HTTP公开JSON-RPC MCP端点。

服务器端口和冲突

默认情况下，服务器使用端口 3000。启动前检查该端口是否已在您的机器上使用。

检查端口是否空闲：

• Linux/macOS： lsof -i :3000 哦 ss -tlnp | grep 3000如果有出口，港口就被占领了。
• 窗户： netstat -ano | findstr :3000。如果出现带有端口的线路，则表示它正忙。

如果繁忙，如何更改端口：

• 连接Node.js： 定义启动时的环境变量，例如 PORT=3001 npm starto美国CLI： openrouter-image server --port 3001.
• Con Docker： 英语 docker-compose.yml 更改端口映射（例如。 "3001:3000")哦。第一个数字是你电脑上的端口；第二个是容器的内部。帕拉 docker run，例如使用 -p 3001:3000.
• 如果您更改端口，请更新客户端MCP配置（光标、克劳德代码等）中的URL：例如 http://localhost:3001/mcp 而不是 http://localhost:3000/mcp.

使用Docker Compose运行

cp .env.example .env
# Edit .env: AUTH_TOKEN, OPENROUTER_API_KEY, OPENROUTER_IMAGE_MODEL

docker compose up -d --build

# Health check
curl http://localhost:3000/health

保存的图像将在 ./output/ （安装为 /data 在容器中）。

独立运行Docker

docker build -t openrouter-image .

docker run -d --name openrouter-image \
  -p 3000:3000 \
  -e AUTH_TOKEN=mi-token-secreto \
  -e OPENROUTER_API_KEY=sk-or-... \
  -e OPENROUTER_IMAGE_MODEL=google/gemini-2.5-flash-image \
  -v $(pwd)/output:/data \
  openrouter-image

使用Node.js运行（HTTP模式）

# Load environment variables
set -a && . ./.env && set +a

# Start server
npm start
# or:
node src/server.js

# Or via CLI
openrouter-image server --port 3000

使用Node.js运行（stdio模式）

openrouter-image server --stdio

或者直接：

node src/server.js --stdio

端点

验证

# Health
curl http://localhost:3000/health

# Listar tools MCP
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

______________________________________________________________________

命令行界面

使用CLI

# Con npm run (desde el repo)
npm run cli --  [options]

# Si se instaló globalmente (npm link / npm install -g)
openrouter-image  [options]

# Con node directamente
node src/cli.js  [options]

记住定义 OPENROUTER_API_KEY 可选地 OUTPUT_DIR （默认值 /data). 要使用本地目录： OUTPUT_DIR=./output openrouter-image ...

Comandos命令行界面

models -列出可用的图像模型

openrouter-image models

打印一个标记表，其中包含ID、名称、供应商、每张图像的估计成本和注释。

`generate

` -生成图像

openrouter-image generate "A cinematic cyberpunk street at night" \
  -m google/gemini-2.5-flash-image \
  -o tests/cyberpunk.png

输出示例：

tool: generate_image
model: google/gemini-2.5-flash-image
output_path: tests/cyberpunk.png
saved_to: /home/user/project/output/tests/cyberpunk.png
mime_type: image/png
bytes: 909527
base64_length: 1212704

如果文件扩展名与检测到的实际MIME类型（PNG/JPEG/GIF/WebP）不匹配，CLI将自动更正扩展名。

`edit

` -编辑现有图像

openrouter-image edit "make it rainy and dark" \
  -i tests/cyberpunk.png \
  -o tests/cyberpunk-rain.png \
  -m openai/gpt-5-image-mini

list -列出保存的图像

openrouter-image list --prefix tests --limit 20 --sort mtime_desc

`read

` -从图像读取元数据

openrouter-image read tests/cyberpunk.png
openrouter-image read tests/cyberpunk.png --copy-to /tmp/local-copy.png

使用Docker（CLI）运行

一个专用 Dockerfile.cli 包含（与MCP服务器分开 Dockerfile):

# Build CLI image
docker build -f Dockerfile.cli -t openrouter-image-cli .

# List models
docker run --rm \
  -e OPENROUTER_API_KEY=sk-or-... \
  openrouter-image-cli models

# Generate image with mounted volume
docker run --rm \
  -e OPENROUTER_API_KEY=sk-or-... \
  -v $(pwd)/output:/data \
  openrouter-image-cli generate "A mountain landscape at sunset" \
    -m google/gemini-2.5-flash-image \
    -o tests/landscape.png

# List saved images
docker run --rm \
  -v $(pwd)/output:/data \
  openrouter-image-cli list

______________________________________________________________________

MCP工具-参考

generate_image

使用OpenRouter（响应API）从提示符生成图像。

注释 ：

• 是 output_path 它对真正的MIME的扩展不正确，它会自动更正。
• 使用 return_base64: false 骗局 output_path 避免巨大的JSON答案。

edit_image

编辑/转换现有的低图像 OUTPUT_DIR （通过响应API的图像到图像）。

list_image_models

列出OpenRouter上可用的图像模型，并提供最新价格。

• 参数： 没有
• 不需要 OPENROUTER_API_KEY （使用OpenRouter的公共API）
• 退出： tabla Markdown图标 id, name, provider, image_output, coste/imagen aprox., notas
• 模型从低到高的估计成本

list_output_images

列出保存在下面的图像 OUTPUT_DIR.

read_output_image

从磁盘读取图像并将其作为MCP内容返回 type: image.

______________________________________________________________________

编码工具中的配置

该MCP服务器支持多种人工智能辅助开发工具。

完整指南：Ver MCP_CLIENT_CONFIG_GUIDE.md 有关详细的文档、故障排除和身份验证方法。

快速总结

通用配置（标准MCP格式）

{
  "mcpServers": {  // o "servers" para VS Code
    "openrouter-image": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer TU_AUTH_TOKEN"
      }
    }
  }
}

示例：光标

恩 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "openrouter-image": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer ${env:AUTH_TOKEN}"
      }
    }
  }
}

示例：克劳德代码

选项1：CLI

claude mcp add --transport http openrouter-image \
  http://localhost:3000/mcp \
  --env AUTH_TOKEN="tu-token-aqui"

选项2：文件 ~/.claude.json

{
  "mcpServers": {
    "openrouter-image": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer ${env:AUTH_TOKEN}"
      }
    }
  }
}

示例：使用GitHub Copilot的VS代码

恩 .vscode/mcp.json （项目根源）：

{
  "servers": {
    "openrouter-image": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer ${input:auth-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "auth-token",
      "description": "OpenRouter Image MCP Auth Token",
      "password": true
    }
  ]
}

⚠️ VS代码美国 "servers" （没有 "mcpServers")并且需要 "type": "http" 明确的。

Tailscale/远程网络使用

如果您在远程机器上运行MCP服务器（例如通过tailscale）：

{
  "mcpServers": {
    "openrouter-image": {
      "url": "http://100.82.111.22:3000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

更多细节，请参阅完整的指南 MCP_CLIENT_CONFIG_GUIDE.md 具有针对每个工具的特定说明、故障排除和身份验证方法。

______________________________________________________________________

卷曲示例（MCP JSON-RPC）

首先加载环境变量：

set -a && . ./.env && set +a

生成图像并保存（没有Base64响应）

curl -fsS http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  --data '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"tools/call",
    "params":{
      "name":"generate_image",
      "arguments":{
        "model":"black-forest-labs/flux.2-klein-4b",
        "prompt":"A clean vector-style icon of a home server rack on a desk, minimal, white background, crisp lines.",
        "output_path":"tests/flux.2-klein-4b.png",
        "return_base64":false
      }
    }
  }'

编辑现有图像

curl -fsS http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  --data '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"edit_image",
      "arguments":{
        "model":"openai/gpt-5-image-mini",
        "prompt":"Turn this into a clean flat illustration style, keep composition, white background.",
        "input_image_path":"tests/flux.2-klein-4b.png",
        "output_path":"tests/edited.png",
        "return_base64":false
      }
    }
  }'

列出保存的图像

curl -fsS http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  --data '{
    "jsonrpc":"2.0",
    "id":3,
    "method":"tools/call",
    "params":{
      "name":"list_output_images",
      "arguments":{ "prefix":"tests/", "limit":50, "sort":"mtime_desc" }
    }
  }'

恢复保存的图像

curl -fsS http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  --data '{
    "jsonrpc":"2.0",
    "id":4,
    "method":"tools/call",
    "params":{
      "name":"read_output_image",
      "arguments":{ "path":"tests/flux.2-klein-4b.png" }
    }
  }'

______________________________________________________________________

测试

该项目包括一组使用 node:test （Node.js内置测试运行器）。

npm test

测试包括：

• CLI参数验证：帮助，未知命令，缺少提示/模型，没有输入的编辑，无效的限制，没有路径的读取。
• 与Mock HTTP的集成：模拟OpenRouter端点的本地服务器(/responses y /models/find)，验证流程 generate, edit y models 端到端，包括自动更正文件扩展名。

______________________________________________________________________

项目结构

openrouter-image/
├── src/
│   ├── core.js          # Lógica compartida (API calls, file handling, models)
│   ├── server.js        # Servidor MCP HTTP (Express, JSON-RPC)
│   └── cli.js           # CLI (parseArgs, commands)
├── tests/
│   └── cli.test.js      # Suite de tests (node:test)
├── scripts/
│   └── models_clean.js  # Script para generar tabla de modelos filtrada
├── output/              # Directorio de imágenes generadas (montado como /data)
├── Dockerfile           # Imagen Docker para el servidor MCP
├── Dockerfile.cli       # Imagen Docker para la CLI
├── docker-compose.yml   # Docker Compose (MCP server)
├── package.json         # Dependencias, scripts, bin
├── .env.example         # Plantilla de variables de entorno
├── MCP_CLIENT_CONFIG_GUIDE.md  # Guía detallada de configuración para IDEs
├── OPENROUTER_IMAGE_MODELS.md  # Tabla estática de modelos (referencia)
├── CHANGELOG.md         # Historial de cambios
└── README.md            # Este archivo

______________________________________________________________________

安全

• 认证：el端点 /mcp 需要 Authorization: Bearer 一个象征性的燃料： openssl rand -hex 32.
• 路径遍历: safeJoinOutputDir() 防止相对路径逃离 OUTPUT_DIR.
• 符号链接：磁盘操作拒绝低symlinks OUTPUT_DIR （防止访问目录外的文件）。
• MIME检测：si OpenRouter分发数据URL(data:image/png;base64,...)，MIME自动提取。如果没有，则由Magic字节（PNG、JPEG、GIF、WebP）检测。
• 自动扩展：如果文件扩展名与检测到的MIME不匹配，则在保存时会更正。

______________________________________________________________________

具有输出图像和价格的模型

• 动态（MCP/CLI）：美国la工具 list_image_models 或命令 openrouter-image models 从OpenRouter API获得更新的价格列表。
• 静态文档: OPENROUTER_IMAGE_MODELS.md 包含从同一API定期生成的表。

______________________________________________________________________

许可证

麻省理工学院-参见 许可证 文件。