TokenRouter 图像生成与编辑

通过 Chat Completions API，使用 TokenRouter 支持图像能力的模型，生成新图像或编辑已有图像。

使用方法

请使用绝对路径运行脚本（切勿先执行 cd 进入 skill 目录）：

生成新图像：

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

uv run ~/.openclaw/workspace/skills/pbd-tokenrouter-image-generator/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/pbd-tokenrouter-image-generator/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 密钥

该脚本需要 TokenRouter API 密钥。密钥查找顺序如下：

1. --api-key 参数
2. PBD_TOKENROUTER_API_KEY 环境变量
3. 自动检测：从当前 agent 在 ~/.openclaw/openclaw.json 中配置的 tokenrouter provider 部分读取

若未找到 API 密钥

运行脚本前，请先检查密钥是否可用：

test -n "$PBD_TOKENROUTER_API_KEY" && echo "密钥已找到" || echo "未找到密钥"

若以上任一来源均未提供有效密钥，请勿运行脚本。应引导用户完成密钥获取流程：

1. 告知用户需要一个 TokenRouter API 密钥。
2. 指引其访问：https://www.tokenrouter.com
3. 逐步说明操作步骤：
   • 在网站注册或登录
   • 登录后，进入 API Keys 页面
   • 在侧边栏 / 导航栏中找到 API Keys 菜单项
   • 点击 API Keys 进入密钥管理页面
   • 创建一个新的 API 密钥并复制
4. 用户获得密钥后，提供以下两种配置方式：
   • 选项 A — 直接向 agent 提供密钥： 用户可在聊天窗口中粘贴密钥，agent 将通过 --api-key 参数传入脚本。这是最快启动方式，无需环境配置。
   • 选项 B — 配置为环境变量（持久化）：
     • 仅限当前终端会话： export PBD_TOKENROUTER_API_KEY="sk-xxx..."（在终端中粘贴执行）
     • 持久化（zsh）： 将 export 行添加至 ~/.zshrc，然后执行 source ~/.zshrc
     • 持久化（bash）： 将 export 行添加至 ~/.bashrc，然后执行 source ~/.bashrc
5. 密钥就绪后，继续执行图像生成命令。

重要提示： 此检查不可跳过。若无有效密钥运行，将报错 Error: No API key provided 或 HTTP 401/403。

可选归属头信息（可选）

• --site-url 或 PBD_TOKENROUTER_SITE_URL
• --app-name 或 PBD_TOKENROUTER_APP_NAME

模型与图像配置

• --model 为必填项（脚本无默认值）
• 默认 / 推荐模型： google/gemini-2.5-flash-image
• 其他支持的图像模型（用户可请求切换）：
  • openai/gpt-5-image
  • openai/gpt-5-image-mini
  • google/gemini-3-pro-image-preview
  • google/gemini-3.1-flash-image-preview
• 使用 --aspect-ratio 设置 image_config.aspect_ratio（例如 1:1、16:9）
• 使用 --image-size 设置 image_config.image_size（1K、2K、4K）

注：TokenRouter 文档中，aspect_ratio 和 image_size 是图像生成通用的配置字段。特定 provider / 模型可能支持额外字段（如 Sourceful 特性）。若请求失败，请移除不支持的选项或更换模型。

注：脚本始终发送 modalities: ["image", "text"]。部分纯图像模型（如某些 FLUX 变体）可能拒绝该配置 — 若使用非 Gemini 模型时出现意外错误，此即可能原因。当前 CLI 参数未暴露绕过方案。

默认工作流（草稿 → 迭代 → 定稿）

目标：在投入更高画质设置前，快速完成多轮迭代。

• 草稿阶段：采用更小尺寸 / 更快模型
  • --image-size 1K
• 迭代阶段：小幅调整 prompt，并每次使用新文件名保存结果
• 定稿阶段：若所选模型支持，可启用更大尺寸或更高画质
  • 示例：--image-size 4K --aspect-ratio 16:9

预检 + 常见失败

• 预检步骤：

  • command -v uv
  • API 密钥检查（关键）： 脚本将依次尝试 --api-key、PBD_TOKENROUTER_API_KEY、以及从 ~/.openclaw/openclaw.json（tokenrouter provider 配置）自动读取。若全部失败，立即中止，并引导用户前往 https://www.tokenrouter.com 注册并获取 TokenRouter API 密钥（详见上文“若未找到 API 密钥”章节）
  • test -d ~/.openclaw/media/outbound || mkdir -p ~/.openclaw/media/outbound
  • 若为图像编辑任务：test -f "path/to/input.png"

• 常见失败类型：

  • Error: No API key provided. → 脚本未能从 --api-key、PBD_TOKENROUTER_API_KEY 或 ~/.openclaw/openclaw.json 中读取到密钥。请引导用户前往 https://www.tokenrouter.com 注册并免费获取 TokenRouter API 密钥，随后设置 PBD_TOKENROUTER_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-03-21-10-00-00-example.png

Prompt 处理规范

• 图像生成：直接使用用户提供的描述文本，除非其过于模糊、无法执行。
• 图像编辑：明确指出需变更内容，其余部分严格保持不变。

精准编辑用 Prompt 模板：

• 仅修改：<变更内容>。其余全部保持一致：主体、构图/裁剪、姿态、光照、配色方案、背景、文字及整体风格。不得添加新对象。

输出行为

• 默认将响应中第一个图像保存至 ~/.openclaw/media/outbound/output-name.png（请在 --filename 中传入完整路径）
• 支持 TokenRouter 的 base64 data URL 图像响应格式（message.images[0].image_url.url）
• 打印已保存的文件路径
• 除非用户明确要求，否则不主动读取图像内容

使用示例

生成新图像：

mkdir -p ~/.openclaw/media/outbound

uv run ~/.openclaw/workspace/skills/pbd-tokenrouter-image-generator/scripts/generate_image.py 
  --prompt "一张具有日系治愈系动漫美学风格的田野照片。" 
  --filename "~/.openclaw/media/outbound/2026-03-21-10-00-00-healing.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/pbd-tokenrouter-image-generator/scripts/generate_image.py 
  --prompt "使用美白滤镜美化该照片。" 
  --filename "~/.openclaw/media/outbound/2026-02-26-14-25-30-sunset-sky-edit.png" 
  --model google/gemini-2.5-flash-image 
  --input-image "self-photo.jpg"

参考文档

• TokenRouter 文档：https://www.tokenrouter.com/docs