generate-image

生成图像

通过 OpenRouter 的 Image API 生成和编辑图像。该 API 可通过统一的请求格式调用 Gemini、Seedream、Recraft、 GPT-Image、Riverflow 以及约 30 种其他模型。

适用场景

以下情况请使用此技能： 照片和照片级写实图像、插画和艺术作品、概念艺术、 演示文稿和海报视觉设计、徽标和矢量标记、图像编辑，以及基于参考图像进行合成。

以下情况请改用 scientific-schematics： 流程图、电路图、生物通路图、 系统架构图、CONSORT 图以及其他技术示意图。

API 密钥

生成图像需要 OpenRouter 密钥。脚本按以下顺序查找密钥：

1. --api-key
2. OPENROUTER_API_KEY 环境变量
3. .env 文件中的 OPENROUTER_API_KEY=，先从工作目录逐级向上查找，再查找脚本所在目录

如果未找到密钥，脚本会退出并显示设置说明。密钥：https://openrouter.ai/keys

--list-models、--model-info 和 --dry-run 无需密钥。

快速开始

# Generate
python scripts/generate_image.py "A beautiful sunset over mountains"

# Edit an existing image
python scripts/generate_image.py "Make the sky purple" -i photo.jpg -o edited.png

路径相对于此技能所在目录。默认输出为 generated_image.<ext>，扩展名取决于模型返回的媒体类型。运行结束后会显示单次请求的费用。

然后查看图像。 在任何地方使用之前，先读取文件并检查图像：构图、宽高比和其中的文字都是模型可能悄无声息地出错的地方。

选择模型

默认模型：google/gemini-3.1-flash-image。

需求	模型
综合质量、遵循提示词	google/gemini-3.1-flash-image
最高级别的 Gemini 模型	google/gemini-3-pro-image
低成本迭代	google/gemini-3.1-flash-lite-image（仅限 1K）、openai/gpt-image-1-mini
照片级写实控制、可复现的随机种子	bytedance-seed/seedream-4.5
单次请求生成多张图像	bytedance-seed/seedream-4.5、openai/gpt-image-2（最多 10 张）
矢量 / SVG 输出	recraft/recraft-v4.1-vector
透明背景	使用 openai/gpt-image-1 和 --background transparent
图像中文字清晰可读	recraft/recraft-v4.1、sourceful/riverflow-v2.5-pro — 详见下方注意事项

references/models.md 列出了完整目录，包含各模型的参数、允许的取值和价格。实时列表具有权威性，且可免费查看：

python scripts/generate_image.py --list-models            # every model and its allowed values
python scripts/generate_image.py --list-models gemini     # filtered by substring
python scripts/generate_image.py --model-info openai/gpt-image-1   # one model, plus pricing

参数支持因模型而异

这是最需要注意的地方。不同模型支持的参数集以及允许的取值各不相同，发送模型不支持的内容会被拒绝，而不是忽略。

脚本会在产生任何费用之前，根据实时目录检查请求；如果参数无效，会在不到一秒内于本地报错，并打印合法取值：

$ python scripts/generate_image.py "abstract pattern" -m openai/gpt-image-2 --background transparent
Error: Request rejected before billing (1 problem):
  - background=transparent is not allowed; this model accepts: auto, opaque

大致参考——但应以检查结果为准，因为目录会不断更新：

• --resolution — Gemini、Seedream、Riverflow、Krea、Grok。不同模型支持的档位各不相同：只有 Gemini 3.1 Flash 支持 512，Gemini 3 Pro / Seedream / Riverflow 支持 4K，而 1K 仅适用于 gemini-3.1-flash-lite-image 和 Krea 模型。
• --output-format — 仅 Riverflow 2.5 支持（png、jpeg、webp；fast 变体仅支持 jpeg）。Gemini、OpenAI、Seedream 和 Recraft 都会自行选择容器格式。
• --quality、--background、--output-compression — OpenAI 系列支持；Riverflow 2.5 也支持 --background。gpt-image-2 或 gpt-5.4-image-2 不支持 --background transparent——请改用 gpt-image-1、gpt-image-1-mini、gpt-5-image 或 gpt-5-image-mini。
• --seed — Seedream 和 Krea 支持。Gemini 和 OpenAI 不支持。
• --aspect-ratio — 几乎所有模型都支持，但枚举值差异很大：gpt-image-1 仅接受 1:1、3:2、2:3、auto，而 gpt-5-image* 完全不接受此参数。
• --n — 每个模型的上限不同：Gemini、Riverflow、MAI 和 Grok 为 1，Recraft 为 6，Seedream 和 OpenAI 为 10。Krea 模型完全不支持此参数。

传入 --dry-run 可进行验证并打印准确的请求正文，而不会生成图像或产生费用。 如果希望由 API 自行判定，请使用 --no-preflight 跳过检查。

编写提示词

与模型选择相比，提示词质量对输出质量的影响更大。请分别用一句话说明：

1. 主体 — 画面中有什么，以及占画面的比例。“一个移液器吸头位于 96 孔板上方。”
2. 媒介和风格 — 照片、水彩画、3D 渲染、扁平矢量图、科学插图。
3. 光线和配色 — “柔和的漫射光，冷蓝色和白色配色。”
4. 构图 — “广角镜头，主体位于中心偏左，右侧留出标题空间。”
5. 需要避免的内容 — “没有文字、标签或水印。”

对于海报和幻灯片，要求在字幕或标题的位置留出空白，是最实用的一条构图指示。

低成本地迭代：先用 gemini-3.1-flash-lite-image 起草，再用你最终选定的措辞和实际想用的模型重新生成。若要优化而不是重来，请将上一次的输出作为参考图传入（-i out.png），并只描述需要改动的部分。

编辑和参考图像

-i/--input 可重复使用，并接受本地路径、HTTP(S) URL 或数据 URL。本地文件会进行 base64 编码，并作为 input_references 发送。

# Single-image edit
python scripts/generate_image.py "Add sunglasses to the person" -i portrait.png

# Composite several references
python scripts/generate_image.py "Blend these two styles" -i style_a.png -i style_b.jpg -o blend.png

# Reference an image already on the web
python scripts/generate_image.py "Restyle as a watercolor" -i https://example.com/photo.jpg

参考图数量上限各不相同：OpenAI 为 16 张，Gemini 和 Seedream 为 14 张，riverflow-v2*-pro 为 10 张，gemini-2.5-flash-image 和 Grok 为 3 张，Recraft、MAI 和 Krea 为 1 张。支持的本地格式：PNG、JPEG、GIF、WebP。除输出费用外，Riverflow v2 每张参考图还会收费 $0.20。

示例

-o 路径是脚本创建的目标位置，不是随技能打包的文件。

# Wide hero image for a poster, with space reserved for the title
python scripts/generate_image.py \
  "Laboratory with modern equipment, photorealistic, well-lit, wide shot, \
   equipment on the left, empty wall on the right, no text" \
  --aspect-ratio 21:9 --resolution 2K -o poster/hero.png

# Conceptual illustration for a manuscript — illustrative, never presented as data
python scripts/generate_image.py \
  "Stylised illustration of immune cells surrounding a tumour cell, scientific illustration, \
   cool palette, no text" \
  --resolution 2K -o figures/immunotherapy_concept.png

# Vector logo
python scripts/generate_image.py \
  "Minimal geometric fox logo, two colors" \
  -m recraft/recraft-v4.1-vector -o assets/logo.svg

# Slide background with a transparent alpha channel
python scripts/generate_image.py \
  "Abstract molecular pattern, subtle, blue and white, no text" \
  -m openai/gpt-image-1 --background transparent -o slides/bg.png

# Four variations in one request
python scripts/generate_image.py \
  "Stylized neuron network illustration" \
  -m bytedance-seed/seedream-4.5 --n 4 -o variations.png
# -> variations_1.png ... variations_4.png

# Reproducible output
python scripts/generate_image.py "A cat astronaut" \
  -m bytedance-seed/seedream-4.5 --seed 42

# Check a request costs nothing to get wrong
python scripts/generate_image.py "A cat astronaut" --resolution 4K --dry-run

脚本参数

标志	用途
prompt	图像描述或要应用的编辑（除非使用 --list-models / --model-info，否则必填）
-m、--model	模型标识（默认 google/gemini-3.1-flash-image）
-o、--output	输出路径；扩展名默认采用返回的媒体类型
-i、--input	参考图像——路径、URL 或数据 URL。可重复指定
--n	每次请求生成的图像数，受模型上限限制
--aspect-ratio	1:1、16:9、9:16、4:3、3:2、21:9、……——可选值因模型而异
--resolution	512、1K、2K、4K——分辨率档位因模型而异
--quality	auto、low、medium、high（OpenAI）
--output-format	png、jpeg、webp（Riverflow 2.5）
--background	auto、transparent、opaque
--output-compression	0–100，适用于 OpenAI 模型
--seed	在支持的情况下生成确定性输出
--api-key	覆盖环境变量和 .env
--timeout	请求超时时间，单位为秒（默认 300）
--retries	遇到速率限制和 5xx 响应时的重试次数（默认 2）
--no-preflight	跳过计费请求前的免费能力检查
--dry-run	验证并打印请求，然后退出，不生成图像
--list-models	打印包含允许值的目录，可选择筛选，然后退出
--model-info	打印一个模型的允许值和定价，然后退出

没有 --size：目录中的模型都不接受 size 参数。请使用 --aspect-ratio 和 --resolution 设置输出形状。

API 格式

直接发送请求而不使用脚本：

curl -s https://openrouter.ai/api/v1/images \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.1-flash-image",
    "prompt": "A red bicycle against a white wall",
    "aspect_ratio": "16:9"
  }'

响应：

{
  "created": 1748372400,
  "data": [{ "b64_json": "<base64>", "media_type": "image/png" }],
  "usage": {
    "prompt_tokens": 4,
    "completion_tokens": 1120,
    "total_tokens": 1124,
    "cost": 0.0672,
    "completion_tokens_details": { "image_tokens": 1120 }
  }
}

b64_json 是原始 base64，不是数据 URL。media_type 反映实际格式，因此命名文件时请遵循该格式——矢量模型返回 image/svg+xml，而 gemini-3.1-flash-lite-image 返回 JPEG 而不是 PNG。

流式传输（"stream": true）会发出 image_generation.partial_image、image_generation.completed 和 error 事件，并以 data: [DONE] 结束。只有 OpenAI 模型支持此功能，随附脚本不会使用该功能。

计费采用全有或全无的方式：生成要么完成并全额计费，要么失败且不计费——因此，被拒绝的参数只会浪费时间，不会产生费用。流式预览帧不单独收费。在自带密钥的账户中，usage.cost 显示为 0，实际金额则记录在 cost_details.upstream_inference_cost 中；脚本会报告该数值，而不会声称此次运行免费。

费用

按图像计费的模型价格可预测：Seedream 为 $0.04，Recraft v4.1 为 $0.035（矢量版 $0.08，pro 版 $0.21），Riverflow 2.5 fast 为 $0.019，pro 为 $0.13–0.17，Grok 为 $0.05–0.07。

Gemini、OpenAI 和 MAI 按输出 token 计费，费用随分辨率增加——一张 4K 图像的费用约为 1K 图像的 16 倍。实测：生成一张 1K 的 gemini-3.1-flash-lite-image 图像需要 1120 个输出 token，费用为 $0.034。同等尺寸下，gemini-3.1-flash-image 的费用是其两倍，gemini-3-pro-image 则是其四倍。先用低分辨率和廉价模型起草，定稿时再为高分辨率付费。

注意事项

• **不能相信模型生成的文字。**生成图像中的文字可能拼写错误、乱码或凭空编造。要求“不要文字”，然后用 LaTeX、PowerPoint 或 HTML 叠加真实文字；或者在标签是重点时使用 scientific-schematics。
• **生成的图像只是插图，绝非证据。**它不展示任何实际测量结果。绝不可将其作为显微镜、成像、凝胶或仪器输出呈现，绝不可用它代替报告结果的图表，并在图注中标明这是插图。Nature 和 Science 都要求披露生成式 AI 图像，且有几家期刊禁止使用这类图像，除非明确标注为概念艺术；投稿前请确认目标期刊的要求。
• 生成图像会产生付费 API 调用。反复调整措辞时，优先使用低成本模型和低分辨率。
• 生成图像大约需要 5–60 秒，具体取决于模型和分辨率。
• 参考图像会上传到 OpenRouter。请勿发送未发表或敏感数据、患者图像或任何处于禁运期的数据。
• 绝不要将 API 密钥硬编码。请将其保存在环境变量中，或放在被忽略的 .env 文件中。
• 编辑时要给出具体提示词：“将天空改成日落色调”比“编辑天空”更有效。
• 拒绝请求时会返回提及内容政策的 HTTP 400 或 403 错误，而不是生成质量不佳的图像。请改写提示词——临床和解剖学主题比实际请求内容更容易触发审核。
• 速率限制和 5xx 响应会自动重试；4xx 响应不会重试，因为需要修改的是请求本身。

相关技能

• scientific-schematics — 技术示意图、流程图、电路图、通路图
• scientific-slides — 嵌入生成图像的演示文稿
• latex-posters — 嵌入主视觉图像的海报

Agent 操作流程

1. **检查环境。**确认数据来源、每张图必须传达的信息，以及目标媒介（期刊、海报、幻灯片）。
2. **明确输入。**根据数据或用户确认格式、标识符和参数。任何会影响结果的数值都应询问，不要猜测。
3. **先运行小规模版本。**按最终尺寸渲染一张图，并在生成整套图像前检查其可读性。
4. 按照上述说明和参考资料执行完整任务。
5. **验证结果。**确认坐标轴、单位和误差线均已标注和定义；颜色适合色盲人士识别；数值与底层数据一致。
6. **报告。**说明运行了什么（版本、命令、参数）、检查了什么，以及哪些内容仍不确定。

如果出现这种情况	请这样做
最终尺寸下文字难以辨认	增大字号或简化面板，不要缩小文字。
这些说明中提到的函数、标志或端点在已安装版本中不存在	查阅已安装版本自身的文档（help()、--help、官方文档），进行调整，并告知用户。绝不要编造 API。
所需输入、标识符或参数含糊不清	询问用户，或在运行前明确说明所采用的假设。

诚信规则

• 绝不要捏造结果、参数、标识符、引文或统计数据。如果某项内容无法运行或验证，请明确说明。
• 绝不要为了改善图像外观而篡改数据；应统一应用图像调整，并披露这些调整。
• 请将此处与特定版本相关的细节视为可能过时，并对照已安装版本的官方文档进行确认。
• 对于涉及费用、占用共享 GPU 或云配额、接触个人或患者数据，或无法撤销的操作，执行前必须征求同意。