Skip to main content
POST
Edit an image
Put an uploaded image ID or a completed result.id in the URL. Describe the change in prompt, including the details to preserve. The default model is nano-banana-2. Each request creates one new image. To refine it, wait for completion and use the edit’s result.id in the next request. The source remains available. Your integration does not select or manage Studio versions. Use edit_type for edit, pose-change, face-swap, or extend; model and account restrictions still apply. For a precise region, use inpaint. A successful request returns HTTP 202 with a jobs array. Save each id, then get the job until it finishes. Read the completed media from result.url and its reusable ID from result.id. Use an Idempotency-Key when submitting work that may be retried.

Authorizations

Authorization
string
header
required

Create an API key in Studio → account menu → API Keys. Keep it on your server.

Headers

Idempotency-Key
string

Use a unique key for each intended creation. Retry the same method, path and JSON with the same key to replay its response for 24 hours after completion. Conflicting requests and unfinished or uncertain outcomes return 409. An uncertain receipt is never automatically rerun.

Required string length: 1 - 128
Pattern: ^[!-~]+$

Path Parameters

id
string<uuid>
required

Source resource ID.

Body

application/json
prompt
string
required

Describe the requested change.

Minimum string length: 1
model
string
default:nano-banana-2

Model for this operation. Account and plan limits apply.

resolution
enum<string>
default:standard

Output quality; dimensions depend on the model and aspect ratio.

Available options:
standard,
high
num_images
integer
default:1

Number of outputs. Defaults to 1. Account limits still apply.

Required range: 1 <= x <= 1
Example:

1

seed
integer
aspect_ratio
string

Optional target ratio, especially for extend.

edit_type
enum<string>
default:edit

Kind of edit. Feature and model availability vary.

Available options:
edit,
pose-change,
face-swap,
extend
reference_image_ids
string<uuid>[]

Multiple image references for text edits.

Maximum array length: 3

Resource ID.

reference_asset_ids
string<uuid>[]

Multiple asset references for text edits.

Maximum array length: 3

Resource ID.

speed
string

Optional processing speed; accepted values depend on the operation and model.

Response

Accepted; poll each job.

jobs
object[]
required
Minimum array length: 1