Skip to main content
POST
Edit an image (existing API)
This is a legacy endpoint for existing integrations. New integrations should use the public v1 API. For existing integrations. Use the edit guide for new work. Existing response formats and version handling →

Authorizations

Authorization
string
header
required

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

Path Parameters

id
string<uuid>
required

Image or asset ID from a previous response. Resource ID.

Body

application/json
prompt
string
required

Describe the requested change.

Minimum string length: 1
resolution
enum<string>
required

Output quality. Send explicitly. Pixel dimensions depend on the image model.

Available options:
standard,
high
Example:

"standard"

version_id
string<uuid>

Optional selection from an existing Studio image history. When chaining completed API results, use result.id from the v1 job response as the source image and omit this field.

model
string

Image model used for the edit.

Example:

"nano-banana-2"

num_images
integer
default:1

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

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

1

aspect_ratio
string

Optional target ratio, especially for extend.

task
enum<string>
default:edit

Kind of edit. Feature and model availability vary.

Available options:
edit,
pose-change,
face-swap,
extend
reference_image_id
string<uuid>

Optional image reference. Do not combine with reference_asset_id.

reference_asset_id
string<uuid>

Optional reusable asset reference. Do not combine with reference_image_id.

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.

seed
integer
speed
string

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

Response

Returns the parent image with a new version. The original may already be completed. Track the new version id and poll its source_image_id for the operation’s result.

id
string<uuid>
required

Resource ID.

status
enum<string>
required

Job state. Only completed has a finished result.

Available options:
pending,
generating,
completed,
failed,
policy_blocked,
nsfw_filtered
path
string | null

Result URL. Can be null while the job is pending.

watermarked_path
string | null
width_px
integer | null
height_px
integer | null
size_bytes
integer | null
extension
string | null
is_generated
boolean
for_training
boolean

Whether the upload is a reusable asset reference.

task
string | null

Operation that created this job.

type
string | null
created_timestamp
string<date-time>
finish_timestamp
string<date-time> | null
fail_reason
string | null

Human-readable failure detail.

failure_code
enum<string> | null

Machine-readable failure category, when available.

Available options:
input_rejected,
provider_unavailable,
queue_timeout,
policy_blocked
asset_ids
string<uuid>[] | null

Linked reusable assets.

Resource ID.

versions
object[]

Related versions. May be omitted or empty. Never infer a new version is completed from the parent status.