6.8 KiB
GPT Image model selection and API notes
Checked against official OpenAI documentation on 2026-09-09. This is the active
API reference for this skill; openai-cookbook.md remains an earlier GPT Image 2
cookbook, not a current model catalog. The 2.5 index is
optional; use migration notes only for comparisons.
Choose before generating
| Choice | Exact API model ID | Typical use |
|---|---|---|
| Flare | gpt-image-2.5-flare |
Fast, everyday generation |
| Sunburst | gpt-image-2.5-sunburst |
Precise edits and detail-sensitive work |
| Image 2 | gpt-image-2 |
Existing workflows and explicit compatibility requests |
The 2.5 models also have snapshots ending in -2026-09-08. There is no documented
bare gpt-image-2.5 API alias. A name such as “GPT 2.5” is a request to clarify,
not a reason to silently choose a model or send an invented ID.
Ask one short model-choice question if the user has not chosen, supplied an
ambiguous name, or made a probable typo. Do not ask again when an exact model was
already supplied. If the user delegates the choice, explain the selection and
proceed. Model selection belongs in the conversation, never inside the image
prompt. Always pass the selected ID explicitly with --model.
The noninteractive CLI keeps gpt-image-2 as its compatibility default. This
is not permission for an agent to skip the model-choice step. Do not generate
multiple models or prompt variants without authorization. Do not change models
or materially rewrite the prompt in response to permission, quota, or policy
errors. The CLI disables automatic SDK retries; report errors rather than
silently repeating potentially billable requests.
Parameters
Both 2.5 models use the existing /v1/images/generations and /v1/images/edits
endpoints. No Responses API migration is needed.
| Parameter | Contract |
|---|---|
quality |
2.5: low, medium, high, xhigh, max, auto. Image 2: through high plus auto. CLI default remains high. |
size |
auto, a CLI shortcut, or WIDTHxHEIGHT; see limits below. |
background |
auto, opaque, transparent. Transparency requires png or webp, not jpeg. |
output_format |
png (default), jpeg, webp. |
output_compression |
Integer 0–100 for JPEG/WebP. Do not request compression for PNG. |
n |
1–10; default 1. More images require the user's authorization. |
user |
Optional end-user identifier, forwarded unchanged. |
moderation |
auto or low; this CLI exposes it for generation only. Existing CLI default remains low. |
input_fidelity |
Edits only, omitted by default. See the qualification below. |
For Image 2 and 2.5, both edges must be positive multiples of 16 and at most 3840 pixels, the long/short ratio at most 3:1, and total pixels between 655,360 and 8,294,400 inclusive. Above 2560×1440 is experimental. A size shortcut controls the actual request; saying “4K” inside a prompt does not set the API dimensions.
For references, repeat -i; for a mask, use -i plus -m. Validate the actual
input image and mask requirements before a live call. The CLI checks file
existence; that alone does not prove valid format, alpha channel, or size.
Parameters requiring care
- Input fidelity: official documentation explicitly requires omission for
gpt-image-2. The CLI drops it only for Image 2 and its dated snapshots, not all names starting withgpt-image-2. Explicitlow/highon 2.5 is passed through as an opt-in request, not advertised as verified API support. Prefer omission until the chosen model's behavior is confirmed. - Edit moderation: the generic HTTP reference lists it, but the Python edit signature used here does not. Do not add it to edits merely because the generation method accepts it.
- Cost: equal per-token rates do not imply equal per-image cost. Compare returned usage for the selected model, size, and quality. Do not promise a fixed multiplier per quality level or assume Flare is always cheaper.
- Output: save
data[].b64_json; a successful response is not proof that text, identity, or layout is correct. Check the actual image. Do not addresponse_formatfor GPT Image models.
Validation boundary
The dependency floor is openai>=2.32.0. Offline request-serialization tests
pass on both 2.32.0 and the freshly resolved 3.10.0 (which uses httpx2). This is
a tested version pair, not a claim that 2.32.0 introduced every 2.5 feature or
that all intervening and future versions were tested.
Run PYTHONPATH=src python -m unittest discover -s tests -v for offline tests.
They use in-process HTTP responses, no credentials or paid image generation.
Live checks on 2026-09-09: the model list omitted 2.5 and
models.retrieve returned 404 model_not_found, while the repository CLI
successfully completed three Sunburst generation requests and two reference edits
(HTTP 200, quality=high, PNG, one image per request). The initial three runs
did not record credential fingerprints. The two replacement-showcase runs
captured a private fingerprint and passed the verified credential to the CLI.
A separate read-only audit verified the current local credential and account
through /v1/me and /v1/models (HTTP 200). Model metadata lookup
alone cannot establish generation availability. See the
samples, exact settings and visual checks.
These runs cover Sunburst generation and single-reference editing. Flare,
masks, transparency, xhigh/max, explicit 2.5 input fidelity, and the separate
community templates still require live validation. The poster's knife shadow
points in the wrong direction despite successful generation.
Before release testing, verify the effective key source, endpoint, project and organization. Keep a non-secret credential fingerprint in private run evidence; never publish keys or account details. Report blocking failures before proposing a release. Run a separately authorized small live sample for each selected model and endpoint. Record exact model, prompt, size, quality, response/error, and output path. Check transparency, exact text, requested edits and preserved regions. Do not treat mocked requests, model listings, or another author's examples as successful local image generation.