Jobs

Your jobs, newest first, one page at a time. Every filter is optional and they combine; a missing one filters nothing. A row carries the item counts and what ran, not items — read one job for those.

To follow a job you just submitted, read it by id — GET /api/v1/jobs/{id}?wait= holds the answer until it settles — or register a webhook. Polling this list is the slow way to watch one job.

USE THIS WHEN:

• Finding jobs by status, type, op, preset or date — last week's failures, say
• Reading every attempt of one job (rootJobId)

DO NOT USE WHEN:

• You have the job's id → GET /api/v1/jobs/{id}
• You only need how many → GET /api/v1/jobs/counts

One page of rows, with meta

Submits an async job. Name the work with op — one entry of GET /api/v1/ops — and the service derives the rest. Price it first: the same request with ?dryRun=true creates nothing.

op is the vocabulary:

• {"op": "remove_bg", "assetIds": ["ast_…"]}
• {"op": "resize", "assetIds": ["ast_…"], "parameters": {"width": 1200}}
• {"op": "generate", "prompt": "a red bicycle on white", "count": 2}
• {"op": "render_template", "templateId": "builtin-template-og-image", "items": [{"title": "Hello"}]}

A parameter outside the op's contract is 400 invalid_param naming it, before any credit is touched.

presetId runs a saved preset (GET /api/v1/presets) by slug or id, or slug@version to pin one version. The preset decides the job type; model / prompt / parameters override its ONE AI step — a preset with no AI step, or with several, refuses them (400 invalid_param naming the field). steps runs the same list of steps inline, once, without saving a preset (op, presetId and the overrides are refused beside it — put them on the step). assetIds batches: one item per asset. Several segments — an AI step beside other steps, or two of them — run as one chain job, each item walking the segments in order; the dry run breaks its price down per segment (steps[]). type (its values are the enum on the request schema) is what an op or a preset translates into; send it only without op.

The response is the job: follow it with GET /api/v1/jobs/{id} or a job.* webhook. Nothing is charged at submit — the credits of an AI job are taken when it settles, for the items that completed. A deterministic job counts its items against the period's processing allowance instead.

wait (seconds, at most 60; a larger value is clamped) holds the response until a ONE-item job is terminal: 200 with the finished job and its outputs, or 202 with the same job when the window closes first — then GET /api/v1/jobs/{id}?wait= waits again. One call, one result, and still a job: it is charged for what completes, retried and replayable exactly as without it. On a batch wait is ignored and the answer is the 201 at once.

The dry run is a validation pass. It answers every 400 and 404 a submit would, but never refuses for money or quota (402 insufficient_credit, 422 asset_count_exceeded): what the account cannot afford comes back as data instead — sufficientCredit, assetCountLeft, processCountLeft, and what runs past the allowance would cost (overageRuns, overageCredits). Images not stored yet are priced by how many: imageCount on a dry run stands for that many more assetIds — the price depends on the op, model, parameters and count, never on the pixels — and the submit after the upload names them.

Past the processing allowance a deterministic job (a pass over assets, a render, a chain's passes) is not refused: each run past it is paid from your balance at the plan's overageCredits (GET /api/v1/ops), held with the job and charged for the runs it hands out. Only a balance that cannot cover them refuses the submit — 402 insufficient_credit, like an AI job.

USE THIS WHEN:

• Running an AI op, a batch, or anything you want an asset_id back for
• Pricing a run before paying for it (?dryRun=true)

DO NOT USE WHEN:

• One image you already hold and a deterministic op → POST /api/v1/images/transform (bytes in, bytes out)
• Reading an image's metadata → POST /api/v1/images/metadata, or GET /api/v1/assets/{id} for a stored one

How many of your jobs are in each status and of each type, as one table: a row per status and type that has any, with its count. Takes the filters GET /api/v1/jobs takes, except status and type — those are the table's two dimensions — and every cell is the meta.total that listing would report for that status and type.

To count by status alone, sum the rows for each status; to count the statuses within one type, keep that type's rows first.

USE THIS WHEN:

• Checking how many jobs failed, or are still running, without paging through them
• Showing a count beside each status or type filter

DO NOT USE WHEN:

• You need the jobs themselves → use GET /api/v1/jobs
• You need credits spent → use GET /api/v1/usage

The non-zero cells; an empty list when nothing matches

One job as it stands: its status, the item counts, what ran (op, preset and version, model, steps) and, per item, the output — resultAssetId, or output for an analyze — or, for a failed item, errorCode and retryable. The first 100 items ride inline and itemsTruncated says when there are more (GET /api/v1/jobs/{id}/items pages the rest). actualCredits is what the job was charged; it is set when the job settles.

wait turns the read into a long-poll: the answer is held until the job is terminal or the window closes, and the job as it stands comes back either way — read status. It is how a 202 from a waited submit is picked up.

A job record lives as long as the assets it made: at expiresAt it is swept, and a read after that is 404.

USE THIS WHEN:

• Reading what a job produced, or why an item failed
• Waiting for a job to finish without writing a poll loop (?wait=)

DO NOT USE WHEN:

• Listing jobs → use GET /api/v1/jobs
• You only want the assets it made → GET /api/v1/assets?jobId={id}

The job — terminal or not; read status

Stops a PENDING or PROCESSING job. Items not yet handed to a provider or a worker are cancelled and never charged; items already running finish, and are charged for what they complete — nothing is taken at submit, so there is nothing to refund. The answer is the job: CANCELLED when nothing was in flight, else CANCELLING until the running items settle, and then CANCELLED. A chain item lets the segment in flight finish and starts no further one.

The job settles as CANCELLED and a job.failed event goes out. What it did make is kept; a resume retries the cancelled items.

USE THIS WHEN:

• Stopping a running or queued job you no longer want

DO NOT USE WHEN:

• The job is already terminal (COMPLETED, FAILED, CANCELLED) or CANCELLING → 400 invalid_state

The job — CANCELLING or CANCELLED

One page of a job's items, in item order (index, from 0) — the number the rest of the API names an item by, in events and in a resume.

GET /api/v1/jobs/{id} carries the first 100 items inline and sets itemsTruncated when there are more; this is how to read the rest. A batch takes up to 10000 assets, each times its variants, so the whole list is not something to hold in a context or re-read on every poll.

USE THIS WHEN:

• A job says itemsTruncated and you need an item past the first page
• You want only the failed ones, to decide whether a resume is worth its price (status=FAILED)

DO NOT USE WHEN:

• You want the assets the job produced → GET /api/v1/assets?jobId={id}, which is the run's products without the items around them

One page of items, with meta

Retries what did not finish: a new job over the FAILED and CANCELLED items of a FAILED or CANCELLED job, with the original's configuration — the same op, model, prompt and parameters, the same preset at the version the original ran, or the same inline steps and subjects. Only the incomplete items are retried (a variant set may repeat a few that had completed — deterministic work, priced like any other run).

• The new job is an ordinary submit: it is priced, checked and charged like one, so it can be refused like one (402, 422).
• A chain item restarts on the segment it failed on (failedStep), from the image the last segment it finished made; the segments it already paid for are not paid again.
• A source asset deleted since the original ran drops its item from the retry; when none is left the answer is 404 asset_not_found.
• The new job points back with parentJobId, carries rootJobId — the first attempt's id, the same on every resume and on the first attempt itself — and advances attemptNumber by 1; GET /api/v1/jobs?rootJobId= lists every attempt. Only the latest attempt can be resumed, and only a few times (details.job.maxResumes).

Whether a resume can help at all is on the job: retryable: true means at least one failed item failed for a reason that may pass.

USE THIS WHEN:

• Retrying only the failed items of a partially-successful job without resubmitting the whole batch

DO NOT USE WHEN:

• Submitting a fresh job → use POST /api/v1/jobs
• Every failed item says retryable: false — the same input fails the same way

The new attempt, created