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), finding the subject for a crop, or a download for an import. A tool that starts one returns a job id right away. A job id means the work is queued or running, not that it is done.

When work becomes a job

A tool call answers within the time a client waits, about 30 seconds. Work that can’t finish in that time is started as a job and returned with its id, its place in the queue, and an estimate when past runs of the same kind agree. inspect_media on a file that hasn’t been read yet answers in time and reports that the read is being prepared. 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), within the 30 seconds some clients allow for a call. If a call is cut off, the answer is lost but the job keeps running.
  • get_jobs with no ids lists all work still running in the workspace (generations, renders, language changes, transcriptions, store imports), 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 includes the item’s id, its URL and a link a conversation can display. A finished language change includes timeline_id. A job id also works 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 refunds work still waiting, keeps the charge for what a running job already finished, and refunds a job at a model provider when nothing was used. Each id reports its status, cloud_minutes when the charge is known at the moment it stops (otherwise get_jobs reports it), 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 includes its id. A file read (a transcript, an index, a shot log) has no separate result to fetch: calling the tool that started it again with the same input returns the stored result.