openai-imagegen/references/image-api.md

Image API quick reference

This file is for the fallback CLI mode only. Use it only after the user explicitly asks to use scripts/image_gen.py instead of the built-in image_gen tool.

These parameters describe the Image API and bundled CLI fallback surface. Do not assume they are normal arguments on the built-in image_gen tool.

Scope

• This fallback CLI is intended for GPT Image models (gpt-image-1.5, gpt-image-1, and gpt-image-1-mini).
• The built-in image_gen tool and the fallback CLI do not expose the same controls.

Endpoints

• Generate: POST /v1/images/generations (client.images.generate(...))
• Edit: POST /v1/images/edits (client.images.edit(...))

Core parameters for GPT Image models

• prompt: text prompt
• model: image model
• n: number of images (1-10)
• size: 1024x1024, 1536x1024, 1024x1536, or auto
• quality: low, medium, high, or auto
• background: output transparency behavior (transparent, opaque, or auto) for generated output; this is not the same thing as the prompt's visual scene/backdrop
• output_format: png (default), jpeg, webp
• output_compression: 0-100 (jpeg/webp only)
• moderation: auto (default) or low

Edit-specific parameters

• image: one or more input images. For GPT Image models, you can provide up to 16 images.
• mask: optional mask image
• input_fidelity: low (default) or high

Model-specific note for input_fidelity: - gpt-image-1 and gpt-image-1-mini preserve all input images, but the first image gets richer textures and finer details. - gpt-image-1.5 preserves the first 5 input images with higher fidelity.

Output

• data[] list with b64_json per image
• The bundled scripts/image_gen.py CLI decodes b64_json and writes output files for you.

Limits and notes

• Input images and masks must be under 50MB.
• Use the edits endpoint when the user requests changes to an existing image.
• Masking is prompt-guided; exact shapes are not guaranteed.
• Large sizes and high quality increase latency and cost.
• High input_fidelity can materially increase input token usage.
• If a request fails because a specific option is unsupported by the selected GPT Image model, retry manually without that option.

Important boundary

• quality, input_fidelity, explicit masks, background, output_format, and related parameters are fallback-only execution controls.
• Do not assume they are built-in image_gen tool arguments.