Codex Manual

GPT Image 2.5 Images API

Codex can help you build an image workflow, but GPT Image 2.5 models and the Images API perform the actual generation and editing.

How this relates to Codex

This chapter belongs in the Codex hub because Codex often helps integrate an image API into the current project, but this is not a built-in Codex CLI image command. Do not set gpt-image-2.5-sunburst as the main Codex model in ~/.codex/config.toml. Set it in the request-level model field when calling the Images API directly.

GPT Image 2.5 provides two models: gpt-image-2.5-sunburst and gpt-image-2.5-flare.

Common endpoints:

Set the API origin and Key

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

Set API_BASE_URL to the single main API origin without /v1. Individual API requests still use the standard /v1/images/... paths.

Generate an image

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.5-sunburst",
    "prompt": "A square poster for a modern tea brand, a glass cup, grapefruit slices, and a fresh white-and-green background",
    "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

The built-in macOS base64 command uses -D instead of --decode. The Images API returns image data in data[].b64_json, so the legacy response_format field is unnecessary.

Edit an image

The edit endpoint accepts local files as 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.5-sunburst' \
  -F 'image[][email protected]' \
  -F 'prompt=Preserve the subject and composition, but replace the background with a neon street in the rain' \
  -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

For multiple references, repeat -F 'image[]=@filename'. For inpainting, also add -F '[email protected]'. The source image and mask must have the same format and dimensions, be smaller than 50 MB, and the mask needs an alpha channel. With multiple references, the mask applies to the first image.

Merge multiple remote reference images

The edit endpoint expects each image[] part to contain an actual image file. It does not accept an image URL as a plain form value. Download remote references first, then upload each file as an image[] part:

curl --fail -sSL \
  'https://assets.stickpng.com/thumbs/6720d9662b0e07609d50e149.png' \
  -o reference-1.png

curl --fail -sSL \
  'https://assets.stickpng.com/thumbs/6720da6c2b0e07609d50e150.png' \
  -o reference-2.png

curl --fail-with-body -sS "$API_BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F 'model=gpt-image-2.5-sunburst' \
  -F 'image[][email protected];type=image/png' \
  -F 'image[][email protected];type=image/png' \
  -F 'prompt=Blend the two images into one coherent composition' \
  -F 'size=1024x1024' \
  -F 'quality=high' \
  -F 'output_format=png' > gpt-image-merge-response.json

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

When using -F, let curl generate the multipart Content-Type and boundary. Do not manually set the Content-Type, Host, or Connection headers.

Verification notes

The OpenAI-compatible request structure was verified with GPT Image 2 on 2026-07-29: both /v1/images/generations and /v1/images/edits returned HTTP 200, image data appeared in data[0].b64_json, and multipart image[] uploads worked. GPT Image 2.5 uses the same request shape; confirm model access and run a small smoke test with your account before first use.

Treat size as a requested target, not a hard guarantee for the decoded file. Although both test requests used 1024x1024, the decoded PNG files were 1254x1254. If exact pixels matter, inspect the saved file and resize or crop it as needed. Use low for an inexpensive smoke test, then switch to medium or high for final output.

Common parameters

gpt-image-2.5-sunburst supports flexible dimensions: both requested edges must be multiples of 16, the longest edge must not exceed 3840 px, the aspect ratio must not exceed 3:1, and total pixels must be between 655,360 and 8,294,400. Set background:"transparent" with output_format:"png" or "webp" for transparent output. Omit input_fidelity on edits because this relay does not pass that field upstream.

Troubleshooting

• 401 or 403: check the Router Key and confirm that the account can use the selected GPT Image 2.5 model.
• 400 with duplicate parameter name: remove the manually specified multipart Content-Type and let curl generate the boundary.
• 400 with expected PNG, JPEG, or WebP: do not send a URL with -F 'image[]=https://...'; download the image first, then upload it with -F 'image[]=@filename'.
• 429: check quota and request frequency.
• The request succeeds but no file appears: inspect the response JSON and confirm that jq reads data[0].b64_json.
• moderation_blocked: revise the prompt or input images instead of retrying the same content.

See the OpenAI image generation guide for current capabilities and parameters. For complete SDK, mask, and Responses API examples, continue with the GPT-5.5 and GPT Image 2.5 guide.