Edit an image

Image editing. Both the official OpenAI SDK's multipart/form-data upload and a JSON body (base64 string) are accepted.

Body

modelstringYes

ID of a model that supports editing

promptstringYes

1–4000 characters

imagestring | fileYes

Source image — a base64 string in JSON, a file part in multipart

maskstring | fileNo

Mask for the region to edit. Check capabilities.image_mask

nintegerNo

Number of images to generate, 1–4 (default 1)

sizestringNo

256x256 · 512x512 · 1024x1024 · 1792x1024 · 1024x1792 · 1536x1024 · 1024x1536 · auto. Only values supported by the selected model are accepted; omission uses the model default

response_formatstringNo

url (default) · b64_json

userstringNo

End-user identifier

The entire multipart body is limited to 4 MiB; JSON is limited to 5 MiB. After file-to-base64 conversion, the payload must also fit within 5 MiB. Exceeding these limits returns 413 request_too_large or invalid_request_error. Check encoded byte size, not only image dimensions.

Model-specific editing

Choose a model with capabilities.image_editing: true in GET /v1/models. capabilities.image_mask describes mask support. Omitted fields mean unverified support; unsupported options return 400.

• Native Gemini image supports prompt-based editing without a mask. Explicit mask returns 400 and is never ignored. Only n: 1 is supported. Size aliases have the same aspect-ratio/resolution meaning as image generation.
• Imagen editing rejects explicit size with 400. Regular edits preserve the source size; upscale uses a 2× factor.
• Omitting size uses the model default; no shared 1024x1024 default is injected. Check limits.supported_sizes and limits.max_images, subject to the generation/editing differences documented here.