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 (20 by default, at most 25; 0 reads once), inside the 30 seconds some clients allow a call. A cut call loses the answer, not the job.
  • get_jobs with no ids lists the work still running that someone started (generations, renders, language changes, transcriptions, store imports), whoever started it, with its prompt, model, the item it will become and who started it. File reads and uploads in progress are counted in also_running.
  • 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 status, cloud_minutes where the charge is known at the stop (get_jobs reports it otherwise), and refunded for work charged in credits.

​
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.