baoyu-image-gen

图像生成（AI SDK）

基于官方 API 的图像生成。支持 OpenAI、Google、OpenRouter、DashScope（阿里通义万象）、Jimeng（即梦）、Seedream（豆包）和 Replicate 提供商。

脚本目录

Agent 执行：

1. {baseDir} = 此 SKILL.md 文件所在目录
2. 脚本路径 = {baseDir}/scripts/main.ts
3. 解析 ${BUN_X} 运行时：如果已安装 bun → bun；如果有 npx → npx -y bun；否则建议安装 bun

第 0 步：加载偏好设置 ⛔ 阻塞

重要：必须先完成此步骤，才能进行任何图像生成。请勿跳过或延后。

检查当前工作目录中是否存在 EXTEND.md：

test -f .baoyu-skills/baoyu-image-gen/EXTEND.md && echo "found"

结果	操作
找到	加载、解析并应用设置。如果 default_model.[provider] 为 null → 仅询问模型（参见 first-time-setup.md 中的流程 2）
未找到	⛔ 停止。请勿生成任何图像。 阅读 references/config/first-time-setup.md，并逐步完成其中的流程 1 检查清单。这是一个多轮交互式设置过程，需要向用户提出多个问题。只有在第 5 步（验证）通过后，才能继续生成图像。

重要：首次设置是一个多步骤交互式工作流，而不是单次操作。你必须向用户提问，并在每个步骤等待回答。

路径	位置
.baoyu-skills/baoyu-image-gen/EXTEND.md	相对于当前工作目录

EXTEND.md 支持：默认提供商 | 默认质量 | 默认宽高比 | 默认图像尺寸 | 默认模型 | 批处理工作线程上限 | 提供商特定的批处理限制

架构：references/config/preferences-schema.md

用法

# Basic
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image cat.png

# With aspect ratio
${BUN_X} {baseDir}/scripts/main.ts --prompt "A landscape" --image out.png --ar 16:9

# High quality
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --quality 2k

# From prompt files
${BUN_X} {baseDir}/scripts/main.ts --promptfiles system.md content.md --image out.png

# With reference images (Google, OpenAI, OpenRouter, Replicate, or Seedream 4.0/4.5/5.0)
${BUN_X} {baseDir}/scripts/main.ts --prompt "Make blue" --image out.png --ref source.png

# With reference images (explicit provider/model)
${BUN_X} {baseDir}/scripts/main.ts --prompt "Make blue" --image out.png --provider google --model gemini-3-pro-image-preview --ref source.png

# OpenRouter (recommended default model)
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider openrouter

# OpenRouter with reference images
${BUN_X} {baseDir}/scripts/main.ts --prompt "Make blue" --image out.png --provider openrouter --model google/gemini-3.1-flash-image-preview --ref source.png

# Specific provider
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider openai

# DashScope (阿里通义万象)
${BUN_X} {baseDir}/scripts/main.ts --prompt "一只可爱的猫" --image out.png --provider dashscope

# DashScope Qwen-Image 2.0 Pro (recommended for custom sizes and text rendering)
${BUN_X} {baseDir}/scripts/main.ts --prompt "为咖啡品牌设计一张 21:9 横幅海报，包含清晰中文标题" --image out.png --provider dashscope --model qwen-image-2.0-pro --size 2048x872

# DashScope legacy Qwen fixed-size model
${BUN_X} {baseDir}/scripts/main.ts --prompt "一张电影感海报" --image out.png --provider dashscope --model qwen-image-max --size 1664x928

# Replicate (google/nano-banana-pro)
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate

# Replicate with specific model
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate --model google/nano-banana

# Batch mode with saved prompt files
${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json

# Batch mode with explicit worker count
${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4 --json

批处理文件格式

{
  "jobs": 4,
  "tasks": [
    {
      "id": "hero",
      "promptFiles": ["prompts/hero.md"],
      "image": "out/hero.png",
      "provider": "replicate",
      "model": "google/nano-banana-pro",
      "ar": "16:9",
      "quality": "2k"
    },
    {
      "id": "diagram",
      "promptFiles": ["prompts/diagram.md"],
      "image": "out/diagram.png",
      "ref": ["references/original.png"]
    }
  ]
}

promptFiles、image 和 ref 中的路径均相对于批处理文件所在目录解析。jobs 为可选项（可被 CLI 的 --jobs 覆盖）。也接受顶层数组格式（不带 jobs 包装）。

选项

选项	说明
--prompt <text>、-p	提示词文本
--promptfiles <files...>	从文件读取提示词（拼接）
--image <path>	输出图像路径（单图模式下必需）
--batchfile <path>	用于生成多张图像的 JSON 批处理文件
--jobs <count>	批处理模式的工作线程数（默认：自动，最大值取决于配置；内置默认值为 10）
--provider google|openai|openrouter|dashscope|jimeng|seedream|replicate	强制指定提供商（默认：自动检测）
--model <id>、-m	模型 ID（Google：gemini-3-pro-image-preview；OpenAI：gpt-image-1.5；OpenRouter：google/gemini-3.1-flash-image-preview；DashScope：qwen-image-2.0-pro）
--ar <ratio>	宽高比（例如：16:9、1:1、4:3）
--size <WxH>	尺寸（例如：1024x1024）
--quality normal|2k	质量预设（默认：2k）
--imageSize 1K|2K|4K	Google/OpenRouter 的图像尺寸（默认：根据质量设置）
--ref <files...>	参考图像。Google 多模态、OpenAI GPT Image 编辑、OpenRouter 多模态模型、Replicate 以及 Seedream 5.0/4.5/4.0 均支持。不支持 Jimeng、Seedream 3.0 或已移除的 SeedEdit 3.0
--n <count>	图像数量
--json	JSON 输出

环境变量

变量	描述
OPENAI_API_KEY	OpenAI API 密钥
OPENROUTER_API_KEY	OpenRouter API 密钥
GOOGLE_API_KEY	Google API 密钥
DASHSCOPE_API_KEY	DashScope API 密钥（阿里云）
REPLICATE_API_TOKEN	Replicate API 令牌
JIMENG_ACCESS_KEY_ID	Jimeng（即梦）Volcengine 访问密钥
JIMENG_SECRET_ACCESS_KEY	Jimeng（即梦）Volcengine 私密密钥
ARK_API_KEY	Seedream（豆包）Volcengine ARK API 密钥
OPENAI_IMAGE_MODEL	OpenAI 模型覆盖值
OPENROUTER_IMAGE_MODEL	OpenRouter 模型覆盖值（默认值：google/gemini-3.1-flash-image-preview）
GOOGLE_IMAGE_MODEL	Google 模型覆盖值
DASHSCOPE_IMAGE_MODEL	DashScope 模型覆盖值（默认值：qwen-image-2.0-pro）
REPLICATE_IMAGE_MODEL	Replicate 模型覆盖值（默认值：google/nano-banana-pro）
JIMENG_IMAGE_MODEL	Jimeng 模型覆盖值（默认值：jimeng_t2i_v40）
SEEDREAM_IMAGE_MODEL	Seedream 模型覆盖值（默认值：doubao-seedream-5-0-260128）
OPENAI_BASE_URL	自定义 OpenAI 端点
OPENROUTER_BASE_URL	自定义 OpenRouter 端点（默认值：https://openrouter.ai/api/v1）
OPENROUTER_HTTP_REFERER	用于 OpenRouter 归属信息的可选应用／网站 URL
OPENROUTER_TITLE	用于 OpenRouter 归属信息的可选应用名称
GOOGLE_BASE_URL	自定义 Google 端点
DASHSCOPE_BASE_URL	自定义 DashScope 端点
REPLICATE_BASE_URL	自定义 Replicate 端点
JIMENG_BASE_URL	自定义 Jimeng 端点（默认值：https://visual.volcengineapi.com）
JIMENG_REGION	Jimeng 区域（默认值：cn-north-1）
SEEDREAM_BASE_URL	自定义 Seedream 端点（默认值：https://ark.cn-beijing.volces.com/api/v3）
BAOYU_IMAGE_GEN_MAX_WORKERS	覆盖批处理工作线程上限
BAOYU_IMAGE_GEN_<PROVIDER>_CONCURRENCY	覆盖服务商并发数，例如 BAOYU_IMAGE_GEN_REPLICATE_CONCURRENCY
BAOYU_IMAGE_GEN_<PROVIDER>_START_INTERVAL_MS	覆盖服务商启动间隔，例如 BAOYU_IMAGE_GEN_REPLICATE_START_INTERVAL_MS

加载优先级：CLI 参数 > EXTEND.md > 环境变量 > <cwd>/.baoyu-skills/.env > ~/.baoyu-skills/.env

模型解析

模型优先级（从高到低），适用于所有服务商：

1. CLI 标志：--model <id>
2. EXTEND.md：default_model.[provider]
3. 环境变量：<PROVIDER>_IMAGE_MODEL（例如 GOOGLE_IMAGE_MODEL）
4. 内置默认值

EXTEND.md 会覆盖环境变量。如果同时存在 EXTEND.md default_model.google: "gemini-3-pro-image-preview" 和环境变量 GOOGLE_IMAGE_MODEL=gemini-3.1-flash-image-preview，则以 EXTEND.md 为准。

Agent 每次生成前都必须显示模型信息：

• 显示：Using [provider] / [model]
• 显示切换提示：Switch model: --model <id> | EXTEND.md default_model.[provider] | env <PROVIDER>_IMAGE_MODEL

DashScope 模型

当用户需要官方 Qwen-Image 行为时，请使用 --model qwen-image-2.0-pro，或设置 default_model.dashscope / DASHSCOPE_IMAGE_MODEL。

官方 DashScope 模型系列：

• qwen-image-2.0-pro、qwen-image-2.0-pro-2026-03-03、qwen-image-2.0、qwen-image-2.0-2026-03-03
  • size 支持使用 宽*高 格式自由指定
  • 总像素数必须介于 512*512 和 2048*2048 之间
  • 默认尺寸约为 1024*1024
  • 自定义比例（如 21:9）以及中文/英文文字较多的布局，优先选择此系列
• qwen-image-max、qwen-image-max-2025-12-30、qwen-image-plus、qwen-image-plus-2026-01-09、qwen-image
  • 仅支持固定尺寸：1664*928、1472*1104、1328*1328、1104*1472、928*1664
  • 默认尺寸为 1664*928
  • qwen-image 目前与 qwen-image-plus 能力相同
• 旧版 DashScope 模型，例如 z-image-turbo、z-image-ultra、wanx-v1
  • 仅在用户明确要求旧版行为或兼容性时继续使用

将 CLI 参数转换为 DashScope 行为时：

• --size 优先于 --ar
• 对于 qwen-image-2.0*，优先使用显式指定的 --size；否则根据 --ar 推断，并采用下方官方推荐的分辨率
• 对于 qwen-image-max/plus/image，只能使用五种官方固定尺寸；如果请求的比例不受支持，则切换到 qwen-image-2.0-pro
• --quality 是 baoyu-image-gen 的兼容性预设，并非 DashScope API 的原生字段。将 normal / 2k 映射到下表中的 qwen-image-2.0* 尺寸，是实现层面的推断，并非官方 API 保证

常见宽高比对应的推荐 qwen-image-2.0* 尺寸：

比例	normal	2k
1:1	1024*1024	1536*1536
2:3	768*1152	1024*1536
3:2	1152*768	1536*1024
3:4	960*1280	1080*1440
4:3	1280*960	1440*1080
9:16	720*1280	1080*1920
16:9	1280*720	1920*1080
21:9	1344*576	2048*872

DashScope 官方 API 还提供 negative_prompt、prompt_extend 和 watermark，但 baoyu-image-gen 目前没有将它们作为专用 CLI 标志提供。

官方参考资料：

• Qwen-Image API
• 文生图指南
• Qwen-Image Edit API

OpenRouter 模型

使用完整的 OpenRouter 模型 ID，例如：

• google/gemini-3.1-flash-image-preview（推荐，支持图像输出和参考图工作流）
• google/gemini-2.5-flash-image-preview
• black-forest-labs/flux.2-pro
• 其他支持图像的 OpenRouter 模型 ID

说明：

• OpenRouter 图像生成使用 /chat/completions，而非 OpenAI 的 /images 端点
• 如果使用了 --ref，请选择支持图像输入和图像输出的多模态模型
• --imageSize 会映射到 OpenRouter 的 imageGenerationOptions.size；如有可能，--size <WxH> 会转换为最接近的 OpenRouter 尺寸和推断出的宽高比

Replicate 模型

支持的模型格式：

• owner/name（官方模型推荐使用），例如 google/nano-banana-pro
• owner/name:version（按版本指定的社区模型），例如 stability-ai/sdxl:<version>

示例：

# Use Replicate default model
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate

# Override model explicitly
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate --model google/nano-banana

提供方选择

1. 提供了 --ref 且未指定 --provider → 依次自动选择 Google、OpenAI、OpenRouter、Replicate（Jimeng 和 Seedream 不支持参考图）
2. 指定了 --provider → 使用该提供方（如果指定了 --ref，则必须为 google、openai、openrouter 或 replicate）
3. 仅有一个可用的 API 密钥 → 使用对应提供方
4. 有多个可用的 API 密钥 → 默认使用 Google

质量预设

预设	Google imageSize	OpenAI Size	OpenRouter size	Replicate 分辨率	使用场景
normal	1K	1024px	1K	1K	快速预览
2k（默认）	2K	2048px	2K	2K	封面、插画、信息图

Google/OpenRouter imageSize：可通过 --imageSize 1K|2K|4K 覆盖

宽高比

支持：1:1、16:9、9:16、4:3、3:4、2.35:1

• Google 多模态：使用 imageConfig.aspectRatio
• OpenAI：映射到最接近的受支持尺寸
• OpenRouter：发送 imageGenerationOptions.aspect_ratio；如果只提供 --size <WxH>，则自动推断宽高比
• Replicate：将 aspect_ratio 传递给模型；当提供 --ref 但未提供 --ar 时，默认使用 match_input_image

生成模式

默认：顺序生成。

批量并行生成：当 --batchfile 包含 2 个或更多待处理任务时，脚本会自动启用并行生成。

模式	使用场景
顺序（默认）	常规使用、单张图片、小批量
并行批量	包含 2 个或更多任务的批量模式

执行方式选择：

情况	首选方式	原因
一张图片，或 1-2 张简单图片	顺序	协调开销更低，也更易于调试
多张图片已有保存的提示词文件	批量（--batchfile）	复用已定稿的提示词，应用统一的限流和重试，并提供可预测的吞吐量
每张图片仍需单独推理、撰写提示词或探索风格	子 Agent	任务仍处于探索阶段，因此生成前可能需要对每张图片进行独立分析

经验法则：

• 提示词文件已保存，且任务是“生成所有这些图片”时，优先选择批量模式而不是子 Agent
• 仅当生成过程需要结合逐图思考、改写或差异化创意探索时，才使用子 Agent

并行行为：

• 默认工作线程数为自动设置，受配置上限约束，内置默认值为 10
• 仅在批量模式下应用针对各提供商的限流；内置默认值经过调优，可提升吞吐量，同时避免明显的每分钟请求数（RPM）突增
• 可通过 --jobs <count> 覆盖工作线程数
• 每张图片最多自动重试 3 次
• 最终输出包含成功数、失败数以及逐图失败原因

错误处理

• 缺少 API 密钥 → 显示设置说明的错误
• 生成失败 → 每张图片最多自动重试 3 次
• 宽高比无效 → 发出警告，并使用默认值继续
• 参考图片使用了不受支持的提供商或模型 → 显示错误并提供修复提示

扩展支持

通过 EXTEND.md 使用自定义配置。路径和支持的选项请参阅 偏好设置 部分。

署名

基于 JimLiu 的 baoyu-image-gen，依据 MIT 许可授权。 已修改并适配 Buda.im 平台。