jobs

Create Job

Queue an inference job.

Answers 202 with the job, which by default is still queued: enhancement runs on the fleet rather than in this request, and a large job can take minutes. There are three ways to collect the result, and the first is usually the one you want:

Set wait and this call holds the response open for that many seconds, up to 30. A job that finishes inside the window comes back finished, with its output, and needs no second call at all. One that does not comes back queued or running, exactly as if you had not asked.
Poll GET /v1/jobs/{id}.
Supply a webhook_url and let the result come to you.

The status code is 202 either way, including when the job is already finished: it says the submission was accepted, not that the work is still outstanding. Read status for that.

Send an Idempotency-Key header to make retries safe: a repeat with the same key returns the original job instead of running inference again.

Send a custom_id to have your own identifier come back on every read of this job and on the webhook, so a result can be matched to your record without keeping a table of ours. It is a label: not interpreted, not required to be unique, and not a key jobs can be looked up by. It is not the Idempotency-Key — that one decides whether a job is created at all.

Send input_megapixels — the size of the file you uploaded — and eta_seconds is estimated for your file rather than for a typical one. It is advisory: the price, the queue and the size limits are decided from the file itself.

waitnumber

Seconds to hold the response open waiting for the job to finish. A fast job then needs no polling at all; if it is still running when the time is up you get the queued/running job back as usual.

Idempotency-Keystring

Makes a retry safe: a later request with the same key and the same body answers with the job the first one made, instead of making another; the same key with a different body is refused. Any value of your own, up to 255 printable ASCII characters — a UUID is a good choice. Keys are your API key's own, so another caller's cannot collide with yours.

Request body

modelstring required

Which model to run, by the name from the model catalog.

input_keystring required

Object key returned by POST /v1/uploads.

paramsobject

Options for the model, validated against its published params_schema.

webhook_urlstring nullable

Absolute http or https URL to receive a signed POST once the job settles. See the webhooks section for the body and its signature.

custom_idstring nullable

Your own identifier for this job, returned on every read of it and on the webhook. Not interpreted, not required to be unique, and not something jobs can be searched by.

input_megapixelsnumber nullable

The size of the file you uploaded, in megapixels (width × height ÷ 1,000,000; for a clip, one frame times the number of frames). Optional. Used only to make eta_seconds an estimate for your file rather than for a typical one — it does not affect the price, the queue or whether the job is accepted, all of which read the file itself.

Response

Successful Response

idstring required

custom_idstring nullable

Your own identifier for the job, if you sent one.

modelstring nullable

The model this job was sent to.

status'queued' | 'running' | 'succeeded' | 'failed' required

flaggedboolean nullable

Whether an automated check thought this job's images may fall outside what the service allows: the part of your image the job worked on (all of it, unless you named a region), and for some jobs the one that came back. null means they were not all checked.

errorstring nullable

Why a failed job failed, in words meant for a person.

error_codestring nullable

The same fact as error, as a stable identifier to branch on. New codes appear as new things become worth telling apart, so treat an unfamiliar one as a failure you have no special handling for rather than as an error in itself. A failed job is never charged, whatever the code; inference_failed is the one worth singling out, because it means the fault was ours and the same request is worth retrying.

communityboolean

Whether the job runs on the community queue, which runs on shared, free capacity and can wait longer at busy times. Explains a long wait that is not a fault.

creditsinteger nullable

What this job was billed. A job is charged when it succeeds — a still at the model's image price, a video by its length — so this reads 0 until then, and stays 0 for a job that fails.

created_atstring date-time nullable

When the job was submitted. ISO-8601, UTC.

finished_atstring date-time nullable

When the job settled. ISO-8601, UTC. Not stated while a job is still queued or running.

thumbnail_urlstring nullable

A temporary link to a small preview of the job's picture — the result, or the image the model worked from when the job produced no file — for showing a list of jobs without fetching each one whole. Absent until the job succeeds, where no preview could be made, and once the job's pictures are deleted.

keptboolean

Whether this result was asked to outlive the ordinary retention schedule.

eta_secondsnumber nullable

Rough seconds until the job finishes — the wait for capacity plus the time running. Not stated once a job has settled, so a callback never carries one.

Create Job

Request

Query parameters

Headers

Request body

Response

Changes