Track jobs and image versions

Use POST /v1/jobs for new integrations. Every supported operation returns 202 with the same jobs array. Each job ID identifies the new work, even when an edit or upscale also creates a version of an existing image.

Submit and poll

{
  "operation": "edit",
  "image_id": "11111111-1111-4111-8111-111111111111",
  "input": {
    "prompt": "Change the background to a warm terracotta studio wall.",
    "model": "nano-banana-2",
    "resolution": "standard"
  }
}

Save every ID in jobs and call GET /v1/jobs/{id}. HTTP 202 means accepted; it does not mean the media is ready.

Status	What your application should do
`pending` or `generating`	Keep the ID and continue polling.
`completed`	Read `result.url`, `result.width`, and `result.height`.
`failed`	Stop polling and record `error.code`.
`policy_blocked`	Stop polling and ask for revised inputs.

result is null until the output is complete and has a media URL. error is null unless the job failed or was blocked. Error codes are safe classifications; support unknown values with a general failure message. Start with a five-second polling interval and a client deadline. Keep the job IDs after the deadline so polling can resume; video may need longer than a still image. The quickstart includes a complete polling helper.

Use a result in the next operation

On completion, result.image_id equals the job ID. For an image result, pass it as image_id to edit, inpaint, upscale, or animate that image. Video results are ready for playback or download; they are not valid sources for these image operations. Assets and uploaded source images keep their existing APIs. Uploaded images are not processing jobs; inspect them with GET /images/{id}.

Existing image endpoints

The existing /images/* and /text-to-video endpoints remain available with their original response shapes. Current clients can continue using them. When moving to the jobs API, wrap the existing operation body in input, set operation, and move any source image from the URL to the envelope’s image_id.

Know the existing response shape

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.

Read 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

Integration guides

Jobs

Images and video

Reusable assets

Track jobs and image versions

Submit and poll

Use a result in the next operation

Existing image endpoints

Know the existing response shape

Read existing image states

An edit does not reset the original image

Recover without creating duplicates

​Submit and poll

​Use a result in the next operation

​Existing image endpoints

​Know the existing response shape

​Read existing image states

​An edit does not reset the original image

​Recover without creating duplicates

Submit and poll

Use a result in the next operation

Existing image endpoints

Know the existing response shape

Read existing image states

An edit does not reset the original image

Recover without creating duplicates