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.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
{ 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.
Cancelling
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 haserror (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.Related
- Billing and limits — what is held, what is charged, and when
- Recipes — complete walkthroughs with curl
- Director API overview
