Codex Manual

GPT Image 2 Images API

Codex can help you build an image workflow, but gpt-image-2 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 as the main Codex model in ~/.codex/config.toml. Set it in the request-level model field when calling the Images API directly.

Common endpoints:

Set the API origin and Key

export API_BASE_URL="https://api.yairouter.com"
export XAI_API_KEY="YOUR_YAI_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",
    "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' \
  -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' \
  -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 on this page was verified 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.

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 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. It does not currently support transparent backgrounds. Omit input_fidelity on edits because the model always processes image inputs at high fidelity.

Troubleshooting

• 401 or 403: check the Router Key and confirm that the account can use gpt-image-2.
• 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 GPT Image 2 model page and 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 guide.