Videos · Concepts

Jobs

A job is one request to generate one prompt's worth of video. It moves through a queue to a GPU worker and ends with a file you can download.

Lifecycle

POST /v1/videos validates the request and, only if it is valid, puts a job in the queue and returns its id. A GPU worker for the right model claims the job, runs it, uploads the result to object storage, and marks the job finished. You find out by checking its status.

StatusMeaning
queuedAccepted and waiting for a worker. No GPU time has been used yet.
processingA worker claimed it and is generating.
completedThe video is ready. Fetch it from /content.
failedThe job could not be completed.
canceledThe job was canceled before it finished.

Checking status

  • Poll GET /v1/videos/{id} every 3 to 5 seconds. Generation takes a minute or two, so faster polling only adds load.
  • There is no progress percentage: progress is always null. The underlying engine does not report progress mid-generation in a way worth showing.
  • The submit response includes eta_seconds, a rough estimate. Use it to decide when to start polling, not as a deadline.
  • A job that has not reached processing can sit in queued when every worker is busy. That is normal under load.

Webhooks (a callback_url on submit) are planned as a later addition so well-behaved clients do not need to poll. They are not part of the first release.

Results

Finished videos are stored in object storage and served through a short-lived signed URL. GET /v1/videos/{id}/content redirects (302) to it, and returns 404 if the job is not completed. A job that asked for several outputs has one variant per output (see Quality and output).

Who can see a job

Jobs belong to the API key that created them. Reading or downloading another key's job returns 404.

← AuthenticationTasks and inputs →