Skip to main content
A job is any slow operation: a generation, a render, a language change, reading a file (its words, its search index, its shot log), a subject read behind a crop, or a download behind an import. A tool that starts one returns a job id at once. A job id means the work was dispatched, not that it finished.

​
When work becomes a job

A tool call answers within the time a client waits for a call, about 30 seconds. Work that cannot finish in that window is dispatched and reported as a job with its id, its place in the queue, and an estimate where past runs of the same shape agree. inspect_media on a file that has not been read yet answers within the window and reports that the read is preparing. import_media by URL answers in about 20 seconds and finishes each remaining download as its own job.

​
Following a job

  • get_jobs with ids long-polls those jobs for up to wait_seconds, at most 25, inside the 30 seconds some clients allow a call. A cut call loses the answer, not the job.
  • get_jobs with no ids lists every job still running in the workspace, whoever started it, with its prompt, model, the item it will become and who started it.
  • A finished generation or render carries the item’s id, its URL and a link a conversation can render. A finished language change carries timeline_id. A job id also resolves as a ref for the item it made.
  • A workspace can register a webhook. job.succeeded, job.failed and job.cancelled are posted as they happen, for generation, render, dub and transcription jobs.

​
Cost

cost_credits on a job is what it has cost so far. A generation the model fails to produce is refunded. cancel_jobs returns the charge for work still waiting, keeps it for what a running job finished, and refunds a job at a model provider where nothing was used. Each id reports its outcome and whether it was refunded.

​
The result

A generation or a render produces an item. A language change produces a new timeline, and the job carries its id. A file read (a transcript, an index, a shot log) has nothing to fetch: the tool that started it, called again with the same input, returns the stored result.