Existing integrations

This page is for integrations that already use /images/generate, /images/virtual-try-on, /images/{id}/edit, or the other operation-specific endpoints. Those endpoints remain supported. For a new integration, start with the quickstart.

Move to public v1

Use the same operation path with the /v1 prefix, such as /v1/images/virtual-try-on or /v1/images/{id}/edit. Send the operation fields directly in the JSON body. The v1 reference defines its own smaller schema; do not copy every old field unchanged.

Use model instead of Generate’s model_version.
Use one outfit source array, even for a single garment.
Use edit_type for edit task selection, and mode for inpainting.
Upscaling defaults to a 4K (2160p) target with SeedVR.
Use result.id as the source for the next image operation. Omit internal version fields.

The new try-on default is v6; the unversioned endpoint still defaults to v1. Send model: "v1" explicitly on the new endpoint when keeping that model matters. Default model choices for other operations are listed in models and settings. All new creation endpoints return 202 with a jobs array. Poll GET /v1/jobs/{id}. Creation uses the focused operation routes; the former generic POST /v1/jobs route has been removed. The successful job response retains its existing fields, with additive result.id, result.type, and error.message fields. Job reads are restricted to the resolved workspace. The new /v1/images/{id} response is a compact media object; the old image response below remains available at /images/{id}.

Existing response shapes

Operation	Success response	What to poll
Generate	`202`, array of images	Every returned image `id`
Try-on, default	`202`, array of images	Every returned image `id`
Try-on with `create_version=true`	`202`, parent image with versions	New version’s `source_image_id`
Edit or inpaint	`202`, parent image with versions	New version’s `source_image_id`
Upscale	`200`, parent image with versions	New version’s `source_image_id`
Image-to-video, Kling 3	`200`, new standalone video image	Returned image `id`
Image-to-video, Kling 2.5	`200`, parent image with versions	New version’s `source_image_id`
Text-to-video	`200`, new standalone video image	Returned image `id`

For the existing image shape, call GET /images/{id}. For several jobs, use POST /images/batch with up to 100 IDs. Match batch results by id; inaccessible or missing records are not placeholders in the returned array.

Existing image states

Status	What your application should do
`pending`	Keep the job ID and wait.
`generating`	Continue polling with a bounded interval.
`completed`	Read `path` and the output dimensions.
`failed`	Stop polling. Record `failure_code` and `fail_reason` when present.
`policy_blocked` or `nsfw_filtered`	Stop polling. Ask for revised inputs; do not automatically resubmit.

A five-second polling interval is a reasonable starting point for a small integration. Set a client deadline and retain job IDs when it expires so you can resume. Video may need a longer deadline than a still image.

An edit does not reset the original image

An original image can remain completed throughout an edit. The response includes a new version linked to a separate pending image job:

{
  "id": "ORIGINAL_IMAGE_ID",
  "status": "completed",
  "versions": [
    {
      "id": "NEW_VERSION_ID",
      "image_id": "ORIGINAL_IMAGE_ID",
      "source_image_id": "EDIT_JOB_ID",
      "version_type": "edited",
      "status": "pending"
    }
  ]
}

The identifiers above illustrate their roles; the service returns UUIDs. Poll EDIT_JOB_ID, then retrieve the parent again to display its updated versions. A response can include older versions too. For a single edit, compare version IDs before and after submitting. This excerpt uses the request and waitForJob helpers from the quickstart:

const before = await request(`/images/${imageId}`);
const previous = new Set((before.versions || []).map(version => version.id));
const parent = await request(`/images/${imageId}/edit`, {
  method: 'POST',
  body: {
    prompt: 'Change the background to a pale studio wall.',
    model: 'nano-banana-2',
    resolution: 'standard',
    num_images: 1,
  },
});
const added = (parent.versions || []).filter(
  version => !previous.has(version.id) && version.source_image_id,
);
if (added.length !== 1) {
  throw new Error('Could not uniquely identify this edit. Check versions before retrying.');
}
const versionId = added[0].id;
const result = await waitForJob(added[0].source_image_id);

Serialize version-creating operations on the same parent while using this comparison. Concurrent edits can make multiple versions appear between the two reads. Store the parent ID, version ID, and job ID together in your application. To edit a specific previous result, pass its version_id with the next request. Omitting it uses the original source image, not automatically the most recent version.

Recover without creating duplicates

Retrying a read is different from retrying a creation request. If a POST times out, it may already have created a job. Keep any returned IDs and check recent images or parent versions before submitting again. Do not assume an idempotency header is supported. Handle errors and account actions →

Start building

Virtual try-on

Generate

Image tools

Video

Results and integration

Reusable assets

More reference

Existing integrations

Move to public v1

Existing response shapes

Existing image states

An edit does not reset the original image

Recover without creating duplicates

​Move to public v1

​Existing response shapes

​Existing image states

​An edit does not reset the original image

​Recover without creating duplicates

Move to public v1

Existing response shapes

Existing image states

An edit does not reset the original image

Recover without creating duplicates