OpenRouter 图像生成与编辑

通过 Chat Completions API 使用 OpenRouter 支持图像的模型生成新图像或编辑现有图像。

使用方法

请使用绝对路径运行脚本（不要先切换到技能目录）：

生成新图像：

# 确保输出目录存在
mkdir -p ~/.openclaw/media/outbound

uv run ~/.openclaw/workspace/skills/openrouter-image-generation/scripts/generate_image.py \
  --prompt "你的图像描述" \
  --filename "~/.openclaw/media/outbound/output-name.png" \
  --model google/gemini-2.5-flash-image \
  [--aspect-ratio 16:9] \
  [--image-size 2K]

编辑现有图像（图生图）：

# 确保输出目录存在
mkdir -p ~/.openclaw/media/outbound

uv run ~/.openclaw/workspace/skills/openrouter-image-generation/scripts/generate_image.py \
  --prompt "编辑指令" \
  --filename "~/.openclaw/media/outbound/output-name.png" \
  --input-image "path/to/input.png" \
  --model google/gemini-2.5-flash-image

重要提示： OpenClaw 默认交付路径为 ~/.openclaw/media/outbound/。请将生成的图像保存在此路径下，以便其他 OpenClaw 流程能够顺利获取。

API 密钥

脚本按以下顺序检查 API 密钥：

1. --api-key 参数
2. OPENROUTER_API_KEY 环境变量

可选的 OpenRouter 归因头信息：

• --site-url 或 OPENROUTER_SITE_URL
• --app-name 或 OPENROUTER_APP_NAME

模型与图像配置

• --model <openrouter-model-id> 为必填项（脚本无默认值）
• 示例模型：google/gemini-2.5-flash-image
• 使用 --aspect-ratio 设置 image_config.aspect_ratio（例如 1:1、16:9）
• 使用 --image-size 设置 image_config.image_size（1K、2K、4K）
• 使用 --image-config-json '{"key":"value"}' 传递高级或特定提供商的额外参数（合并至 image_config）

注意：OpenRouter 文档中列出的 aspect_ratio 和 image_size 是图像生成的常见配置字段。特定提供商或模型可能支持其他键（如 Sourceful 功能）。若请求失败，请移除不支持的选项或更换模型。

注意：脚本始终发送 modalities: ["image", "text"]。仅支持图像的模型（部分 FLUX 变体）可能拒绝此请求——若使用非 Gemini 模型时出现意外错误，可能是原因所在。目前 CLI 参数未提供相应绕过方式。

默认工作流（草稿 → 迭代 → 最终版）

目标：在投入高质量设置前快速迭代。

• 草稿：较小尺寸 / 更快模型

- --image-size 1K

• 迭代：微调提示词并每次使用新文件名
• 最终版：若模型支持，使用更大尺寸或更高画质

- 示例：--image-size 4K --aspect-ratio 16:9

预检与常见问题

• 预检：

- command -v uv

- test -n "$OPENROUTER_API_KEY"（或传入 --api-key）

- test -d ~/.openclaw/media/outbound || mkdir -p ~/.openclaw/media/outbound

- 若为编辑操作：test -f "path/to/input.png"

• 常见错误：

- Error: No API key provided. → 设置 OPENROUTER_API_KEY 或传入 --api-key

- Error loading input image: → 路径错误或文件不可读

- HTTP 400 且提示模型/图像配置错误 → 不支持的模型或无效的 image_config.aspect_ratio / image_config.image_size

- HTTP 401/403 → 密钥无效、无模型访问权限或配额/积分不足

- No image found in response → 模型不支持图像输出或请求格式被拒绝

文件名生成

文件名应遵循格式：~/.openclaw/media/outbound/yyyy-mm-dd-hh-mm-ss-name.png

示例：

• ~/.openclaw/media/outbound/2026-02-26-14-23-05-product-shot.png
• ~/.openclaw/media/outbound/2026-02-26-14-25-30-sky-edit.png

提示词处理

• 生成图像时：直接传递用户描述，除非过于模糊无法执行。
• 编辑图像时：明确说明修改内容，并保持其余部分不变。

精确编辑的提示词模板：

• Change ONLY: <修改内容>。Keep identical: 主体、构图/裁剪、姿势、光照、色彩基调、背景、文字和整体风格。不要添加新物体。

输出结果

• 默认将第一个返回的图像保存至 ~/.openclaw/media/outbound/output-name.png（需在 --filename 中指定完整路径）
• 支持 OpenRouter 的 base64 数据 URL 图像响应格式（message.images[0].image_url.url）
• 输出保存的文件路径
• 除非用户要求，否则不要读取图像内容

示例

生成新图像：

mkdir -p ~/.openclaw/media/outbound

uv run ~/.openclaw/workspace/skills/openrouter-image-generation/scripts/generate_image.py \
  --prompt "一张电影感的产品照片：一款哑光黑色机械键盘置于木制桌面上，温暖的窗光照射" \
  --filename "~/.openclaw/media/outbound/2026-02-26-14-23-05-keyboard-product-shot.png" \
  --model google/gemini-2.5-flash-image \
  --aspect-ratio 16:9 \
  --image-size 2K

编辑现有图像：

mkdir -p ~/.openclaw/media/outbound

uv run ~/.openclaw/workspace/skills/openrouter-image-generation/scripts/generate_image.py \
  --prompt "Change ONLY: 将天空改为橙色日落云彩，充满戏剧性。Keep identical: 主体、构图、前景光照和整体风格。" \
  --filename "~/.openclaw/media/outbound/2026-02-26-14-25-30-sunset-sky-edit.png" \
  --model google/gemini-2.5-flash-image \
  --input-image "original-photo.jpg"

参考资料

• OpenRouter 文档：https://openrouter.ai/docs/guides/overview/multimodal/image-generation