Codex Manual

GPT Image 2 图片 API

Codex 可以帮你编写图片工作流，但真正生成和编辑图片的是 gpt-image-2 与 Images API。

与 Codex 的关系

本章放在 Codex 专题中，是因为图片 API 经常由 Codex 帮你集成到当前项目，但它不是 Codex CLI 的内置图片命令。不要把 gpt-image-2 写成 ~/.codex/config.toml 里的 Codex 主模型；直接调用 Images API 时，才在请求的 model 字段中填写 gpt-image-2。

常用端点：

用途	端点
文本生成图片	`POST /v1/images/generations`
编辑图片、参考图生成、局部重绘	`POST /v1/images/edits`

准备主域名与 Key

export API_BASE_URL="https://api.xairouter.com"
export XAI_API_KEY="YOUR_XAI_ROUTER_KEY"

API_BASE_URL 只填写统一的主 API 域名，不带 /v1；具体 API 请求继续使用标准的 /v1/images/... 路径。

生成图片

curl --fail-with-body -sS "$API_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一张现代茶饮品牌的方形海报，玻璃杯、柚子切片、清爽白绿色背景",
    "n": 1,
    "size": "1024x1024",
    "quality": "low",
    "output_format": "png"
  }' > gpt-image-response.json

jq -er '.data[0].b64_json' gpt-image-response.json \
  | base64 --decode > gpt-image.png

macOS 自带的 base64 使用 -D 代替 --decode。Images API 直接在 data[].b64_json 中返回图片，不需要再传旧的 response_format。

编辑图片

编辑接口使用 multipart/form-data 上传本地文件：

curl --fail-with-body -sS "$API_BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F 'model=gpt-image-2' \
  -F 'image[][email protected]' \
  -F 'prompt=保留主体与构图，把背景改成雨夜霓虹街道' \
  -F 'size=1024x1024' \
  -F 'quality=low' \
  -F 'output_format=png' > gpt-image-edit-response.json

jq -er '.data[0].b64_json' gpt-image-edit-response.json \
  | base64 --decode > gpt-image-edited.png

需要多张参考图时，重复添加 -F 'image[]=@文件名'。局部重绘可以再添加 -F '[email protected]'；原图与遮罩必须格式、尺寸一致且小于 50 MB，遮罩需要 alpha 通道。多图编辑时，遮罩应用于第一张图片。

实测说明

2026-07-29 已验证本页的 OpenAI 兼容请求结构：/v1/images/generations 与 /v1/images/edits 均返回 HTTP 200，图片位于 data[0].b64_json，image[] multipart 上传可用。

size 是请求的目标尺寸，不应当作输出文件像素的硬保证。实测中两次请求虽然填写 1024x1024，解码后的 PNG 均为 1254x1254。如果业务依赖精确像素，请在保存后读取实际宽高，再按需缩放或裁切。low 适合低成本验证，成稿可改为 medium 或 high。

常用参数

参数	说明
`model`	固定使用 `gpt-image-2`
`size`	常用值包括 `1024x1024`、`1536x1024`、`1024x1536`、`2048x2048`、`3840x2160` 或 `auto`
`quality`	`low`、`medium`、`high` 或 `auto`
`output_format`	`png`、`jpeg` 或 `webp`；默认 `png`
`output_compression`	JPEG / WebP 的压缩参数，范围 `0`–`100`
`n`	一次生成的图片数量

gpt-image-2 支持灵活尺寸：请求尺寸的两边需为 16 的倍数，最长边不超过 3840 px，长宽比不超过 3:1，总像素范围为 655,360–8,294,400。它当前不支持透明背景；编辑时也不要传 input_fidelity，模型会自动以高保真方式处理输入图像。

排查要点

401 或 403：检查 Router Key 及当前账户是否可以使用 gpt-image-2。
400：检查 JSON 字段，或确认编辑请求使用 multipart 并以 image[] 上传文件。
429：检查当前额度和请求频率。
返回成功但没有输出文件：先查看响应 JSON，再确认 jq 读取的是 data[0].b64_json。
moderation_blocked：调整提示词或输入图片后重试，不要循环提交相同内容。

能力与参数以 OpenAI GPT Image 2 模型页和图片生成指南为准；需要 SDK、遮罩和 Responses API 的完整示例，可继续阅读GPT-5.5 与 GPT Image 2 实战。

上一章接入 XAI Router 下一章权限与安全