图片生成 是做什么的?
同步图像生成与编辑。无需轮询任务状态。
何时使用
- 文生图、图生图、带遮罩的内补绘制。
- 透明背景、WebP/JPEG 输出、GPT-Image 动画 GIF。
- 用户指定了图像模型名称,或要求特定的尺寸、质量或格式。
何时不使用
- 视频、音乐、语音或 Jev 决策模型。请使用专门的技能。
- 用户想先比较价格:运行
models --category image。
前置条件
按照以下顺序解析 API 密钥(第一个匹配项胜出):
skills/image-generation/config.json→api_keyskills/ai-gateway/config.json→api_keyAIGW_IMAGE_API_KEYAIGW_API_KEYOPENAI_API_KEY
使用以下命令存储凭证:
python3 core/gateway.py login --key sk-xxx --skill image
--base-url 将网关地址写入配置文件。解析顺序:技能配置、共享配置、AIGW_IMAGE_BASE_URL、AIGW_BASE_URL,然后是 core/config.json 中打包的默认值。
命令
# 文生图
python3 core/gateway.py image generate --prompt "a red panda on a bench, soft light" \
--model <model> --size 1024x1024 --quality high --output-format png
# 多图生成
python3 core/gateway.py image generate --prompt "sticker sheet" --n 4
# 透明 PNG(需要支持 alpha 输出的模型层级)
python3 core/gateway.py image generate --prompt "cartoon fox sticker, clean cutout edges" \
--background transparent --output-format png
# 动画 GIF(需要支持 GIF 的模型层级)
python3 core/gateway.py image generate --prompt "a small robot waves, loop it" \
--output-format gif --frame-count 9 --frame-duration-ms 200
# 编辑 / 内补绘制
python3 core/gateway.py image edit --prompt "make the sky sunset orange" \
--image input.png --mask mask.png
# 使用透明标记圈进行编辑(GPT-Image 2.5+)
python3 core/gateway.py image edit --prompt "replace the circled object with a red apple" \
--image input.png --markup markup.png
# 发现模型和别名
python3 core/gateway.py models --category image
python3 core/gateway.py resolve nano-banana
参数
| 标志 | 必需 | 说明 |
|---|---|---|
--prompt | 是 | 文本描述。 |
--model | 否 | 确切的模型 ID。当只有一个图像模型可用时省略。 |
--size | 否 | 1024x1024、1536x1024、auto 或模型特定值。使用 -1k 模型变体以获得最低价格层级。 |
--n | 否 | 图像数量。硬限制为 128。 |
--quality | 否 | auto / low / medium / high;GPT-Image 2.5+ 还支持 xhigh、max。 |
--output-format | 否 | png / jpeg / webp;GPT-Image 2.6 增加了 svg、gif。 |
--background | 否 | transparent 需要 png 或 webp。 |
--moderation | 否 | auto / low。 |
--complexity | 否 | GPT-Image 2.6 规划深度 low / medium / high。不影响计费。 |
--output-compression | 否 | 0-100,仅限 JPEG/WebP。 |
--frame-count | 否 | 2-64,仅限 GIF。必须是非负整数。 |
--frame-duration-ms | 否 | 20-2000,仅限 GIF。 |
--markup | 否 | 仅编辑。覆盖编辑区域的透明 PNG 标记圈;仅限 GPT-Image 2.5+。 |
--group | 否 | 路由到特定的计费组。 |
端点
POST /v1/images/generations— JSON,同步。POST /v1/images/edits— multipart,字段名image[],可选的mask。
响应中包含 data[] 项。每个项包含 b64_json 或 url。CLI 会解码 base64、下载 URL,并将文件写入 outputs/image/<YYYY-MM-DD>/。如果下载被拒绝,则返回原始 URL 到 urls 中。
Gemini 图像模型也接受 /v1/images/generations,其中 size 映射到 imageSize 加上 aspectRatio。已验证:2048x2048 返回 2048x2048。GPT-Image 2.6 也接受显式的像素尺寸;已验证 3840x2160 返回 3840x2160。
分辨率
| 需求 | Size 值 | 结果 |
|---|---|---|
| 1K 方形 | 1024x1024 | 1024x1024 或 1254x1254 |
| 2K 方形 (Gemini) | 2048x2048 | 2048x2048 |
| 4K 横向 | 3840x2160 | 3840x2160 |
使用 -1k 模型变体以获得最低价格层级;更大的尺寸仅在模型固定价格时按相同调用次数计费。
以 -1k 结尾的模型 ID(gpt-image-2.6-1k、-flare-1k、-sunburst-1k)始终返回 1K。从中请求 4K 会回显请求尺寸但静默返回约 1254x1254,因此请检查输出尺寸而不是信任请求。
--output-format svg 仅支持 --n 1;上游拒绝更大的批次。请将 GIF/SVG 请求保持在 n=1,并自行拆分批次。
格式与透明度
| 能力 | 要求 |
|---|---|
png / jpeg / webp | 普遍可用。 |
| 透明背景 | 需要 png 或 webp。只有较新的模型层级才能输出 alpha 通道;入门级层级会拒绝。 |
| 动画 GIF | 2.6 及以上层级的生成图像模型。需要 --output-format gif 以及 --frame-count (2-64) 和 --frame-duration-ms (20-2000)。 |
| SVG 输出 | 2.6 及以上层级,仅限生成。编辑端点会拒绝 svg 和 gif。 |
当某个格式被拒绝并返回 400 时,表示所选模型层级不支持该格式。请切换到更新版本的模型层级,而不是重试相同的模型。
有些模型接受 background: transparent 而不报错,但仍然返回不透明的图像。请始终验证结果,而不是信任请求:
file outputs/image/<date>/<name>.png # "RGBA" 或 "color_type 6" 表示真正的 alpha
RGB 结果表示该标志被忽略。请在其他模型层级上重试,或本地后处理白色背景。
编辑
image edit 将本地文件作为 multipart 上传,因此输入图像无需是公开的。
--image可重复;最多接受 16 个输入。--mask标记重绘区域;--markup在 GPT-Image 2.5 及更高版本上圈出编辑区域,并作为 multipart 文件传递。- 编辑端点仅接受
png/jpeg/webp输出。svg和gif仅限生成。 - 除非提示另有要求,否则返回的图像会保持输入帧。
已验证:通过 image edit 使用单个本地图像在 GPT-Image 模型和 Gemini 图像模型上都能工作,每个模型都会返回保留原始构图的编辑后图像。
错误
| 状态码 | 含义 | 操作 |
|---|---|---|
| 400 | 参数无效或模型能力不支持 | 修正标志;检查 models --category image。 |
| 401 | 密钥缺失或无效 | 重新运行 login,然后 doctor。 |
| 402 | 配额不足 | 告知用户充值。 |
| 429 | 速率限制或并发上限 | 退避并重试。 |
| 503 | 该密钥所属组中模型不可用 | 切换模型或使用该组的密钥。 |
| 5xx | 上游故障 | 重试一次,然后逐字显示错误信息。 |