Skip to main content
Every Director call that makes something (a shot, a film, a song, a plan) starts a job. You get the job back immediately, then poll it until it finishes. This page explains that loop. For each endpoint’s fields, see the generated API reference.

The loop

1

Start

POST a start endpoint. It answers 202 with a director.job and a Location: /api/v1/director/jobs/{id} header. The quoted credits are now held.
2

Poll

GET /api/v1/director/jobs/{id} every 10–30 seconds. Reading a job syncs it with the studio, so polling is what moves it along.
3

Collect

When status is done, the finished file is already in your Pixio assets. output.url is a signed link valid for 6 hours; output.assetPath is the durable copy.
On a timeout or a dropped connection, keep polling the same job id. Don’t start the request again: a second start is a second job, held and billed on its own.

Statuses

status is always one of these five values. Desktop and plugin clients branch on them, so no other value is ever returned. music/plan and prompts/write (the writer calls) start as running; everything else starts as queued.
A film waiting for you to approve its storyboard stays running. Check storyboard.waiting rather than status or stage to know it needs you. See Storyboards.

The job object

Getting the files

Finished files are copied into your Pixio assets, so they appear in your library and the regular asset endpoints work on them.

Listing jobs

Answers { object: "list", data: [...], hasMore, nextBefore }, newest first. limit is 1–100 (default 20). For the next page pass nextBefore as before. An unknown endpoint filter is ignored, not an error.
Listing does not refresh progress. Use it to find jobs; GET a single job for its live status.

Cancelling

Answers 200 with the job. A cancel lands at the end of the current render step, so for a moment you’ll see cancelRequested: true and stage Cancelling before status becomes cancelled. Finished sections or clips, plus any writing, are still charged. Cancelling a job that has already finished changes nothing.

Free checks before you start

The shot, music-video and film endpoints take ?check=true (or ?dry_run=true); packaging and series episodes take ?dry_run=true. Instead of starting, they answer 200 with a director.preflight: what would be made, the prompt-check report in promptCheck, and the quote in credits.quoted (plus perVersion/versions with variants, or clip/packaging for a packaged shot). Nothing is held or rendered. POST /director/prompts/check checks prompts on their own, synchronously and free: { ok, issues[], counts }.

Errors

Every error body has error (a sentence to show) and code (a stable string to branch on), plus extra fields for some codes.
When the studio refuses a request after Pixio has accepted it, the job is still recorded with status failed and error “Could not start.”, and every hold is given back. You may see these in GET /director/jobs.