Edit an image

POST /v1/images/edits

Reference-image editing without masks. JSON image accepts one or more sources. Multipart uses image or repeated image[] files, each at most 20 MiB.

Guide and limits

Try this endpoint

Enter your API key and request parameters, then send. Generation requests are billed normally; authentication is not persisted in your browser.

application/json

Name	Type	Required	Default / values	Description
model	string	yes	gemini-3.1-flash-lite-image, gemini-3.1-flash-image, gemini-3-pro-image, gpt-image-2.5-fast, gpt-image-2.5-pro, gpt-image-2, image-basic, image-fast, image-pro, image-creative	Public product route. Lite accepts 1K only.
prompt	string	yes	—	Non-blank prompt, at most 4096 Unicode characters.
size	string	no	auto, 1024x1024, 1536x1024, 1024x1536, 1792x1024, 1024x1792, 2048x2048, 2048x1152, 1152x2048, 4096x4096, 4096x2304, 2304x4096	Target tier and aspect ratio; actual output pixels depend on the model. Must agree with resolution/aspect_ratio.
resolution	string	no	"1k"	Case-insensitive tier; Lite only accepts 1k/1080p.
aspect_ratio	string	no	1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9
quality	string	no	auto, standard, hd	Fixed per model; standard for Lite/Flash/2.5-fast/basic/fast, hd for Pro/2.5-pro/2/pro/creative. auto accepts the fixed tier.
n	integer	no	1
response_format	string	no	url, b64_json	Non-streaming response defaults to URL. Default SSE still embeds Base64, even when url is requested.
enhance	boolean	no	true
stream	boolean	no	false	Use true for SSE heartbeats followed by a completion event. No partial previews.
partial_images	integer	no	0
delivery	string	no	"url"	Site extension: stream=true only, incompatible with response_format=b64_json. Emits image_url.completed.
image	string / array	yes	—	Required reference image(s); JSON accepts URLs or image data URLs.

Example request

{
  "model": "gemini-3-pro-image",
  "prompt": "保持构图，将红色改为蓝色",
  "image": "https://example.com/reference.png",
  "stream": true,
  "partial_images": 0
}

multipart/form-data

Boolean form fields use true/false; n and partial_images are integer strings.

Name	Type	Required	Default / values	Description
model	string	yes	gemini-3.1-flash-lite-image, gemini-3.1-flash-image, gemini-3-pro-image, gpt-image-2.5-fast, gpt-image-2.5-pro, gpt-image-2, image-basic, image-fast, image-pro, image-creative	Public product route. Lite accepts 1K only.
prompt	string	yes	—	Non-blank prompt, at most 4096 Unicode characters.
size	string	no	auto, 1024x1024, 1536x1024, 1024x1536, 1792x1024, 1024x1792, 2048x2048, 2048x1152, 1152x2048, 4096x4096, 4096x2304, 2304x4096	Target tier and aspect ratio; actual output pixels depend on the model. Must agree with resolution/aspect_ratio.
resolution	string	no	"1k"	Case-insensitive tier; Lite only accepts 1k/1080p.
aspect_ratio	string	no	1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9
quality	string	no	auto, standard, hd	Fixed per model; standard for Lite/Flash/2.5-fast/basic/fast, hd for Pro/2.5-pro/2/pro/creative. auto accepts the fixed tier.
n	integer	no	1
response_format	string	no	url, b64_json	Non-streaming response defaults to URL. Default SSE still embeds Base64, even when url is requested.
enhance	boolean	no	true
stream	boolean	no	false	Use true for SSE heartbeats followed by a completion event. No partial previews.
partial_images	integer	no	0
delivery	string	no	"url"	Site extension: stream=true only, incompatible with response_format=b64_json. Emits image_url.completed.
image	string	no	—	One reference file. For multiple files use repeated image[]. At most 20 MiB per file.
image[]	array	no	—

Responses

Status	Description
200	JSON result, or SSE comment heartbeats then a completion/error event. HTTP 200 alone is not proof of generation success.
400	Unsupported or conflicting parameters.
401	Missing or invalid customer API Key.
413	Request exceeds upload limits.
429	Capacity or rate limit exceeded.
502	Generation or image delivery failed; do not automatically resubmit.
507	Insufficient capacity before submission.

application/json

{
  "created": 1790980000,
  "data": [
    {
      "url": "https://s3.yanxinyu.ggff.net/media_outputs/0123456789abcdef0123456789abcdef.png"
    }
  ]
}

text/event-stream

event: image_url.completed
data: {"type":"image_url.completed","operation":"edit","url":"https://s3.yanxinyu.ggff.net/media_outputs/0123456789abcdef0123456789abcdef.png","request_id":"REQUEST_ID","created_at":1790980000}

data: [DONE]