One request. A finished film.
Send a song or an idea. Montage writes it, casts it, shoots it in sections, lip-syncs the singer and cuts the final. You get a job, poll it, and download a video, with every step after that, from one-section redos to dubbing, a call away.
- endpoints
- 85endpoints
- model tiers
- 3model tiers
- jobs at once
- 8jobs at once
- longest film
- 7 minlongest film
# 1. Start a music video from a song
curl -X POST https://beta.pixio.myapps.ai/api/v1/director/videos/music \
-H "Authorization: Bearer $PIXIO_API_KEY" \
-F song=@night-drive.mp3 \
-F idea="She drives a red convertible through a neon city at night" \
-F aspect=16:9 \
-F lipsync=performance
# 202 Accepted
# Location: /api/v1/director/jobs/3f2c…
# 2. Poll until status is "done"
curl https://beta.pixio.myapps.ai/api/v1/director/jobs/3f2c… \
-H "Authorization: Bearer $PIXIO_API_KEY"Quickstart
Three calls from nothing to a finished music video. Every example on this page works with cURL, Node 18+ or Python.
- Step 1
Authenticate
Create a key in Integrations and send it on every call as
Authorization: Bearer pxio_live_…. A key acts for the whole account. - Step 2
Start a job
POST JSON or multipart to an endpoint. You get
202with adirector.joband aLocationheader. Credits for the quote are held, never more. - Step 3
Poll, then download
GET
/jobs/{id}every 10–30 s; each read moves the job forward. Whenstatusisdone,output.urlis your video, signed for 6 hours.
Build a request
Pick what to make and set the main fields; the request and its credit hold update as you go. Nothing is sent from this page.
1,105credits
4 sections × 201 · writer 151 · designed pictures held 150. Charged for what renders, never more.
curl -X POST "https://beta.pixio.myapps.ai/api/v1/director/videos/music" \
-H "Authorization: Bearer $PIXIO_API_KEY" \
-F song=@song.mp3 \
-F idea="She drives a red convertible through a neon city at night" \
-F aspect="16:9" \
-F lipsync="performance"Jobs and polling
Every production is a job. There are no webhooks: poll the job, and reading it is what advances it. Reads are free.
- queued
- Accepted and waiting, or preparing the shoot.
- running
- Rendering, sharpening or finishing.
stagesays which. - done
output.urlis ready. The quote is charged, never more.- failed
errorsays why. Unused credits go back.- cancelled
- Stopped by you. Finished parts are charged.
progressruns 0–1 and holds at 0.99 until done;etaSecondsandqueuesay how long.stagereads like “9 of 15 parts done” or “Finishing the cut”.- You are never charged more than
credits.quoted. Cancel withDELETE /jobs/{id}: finished parts are charged, the rest is returned. If the final can't be delivered, the job fails and is refunded. - Rendered sections and clips are listed in
parts, andGET /jobs/{id}/parts/{n}streams any one of them with range requests.
{
"id": "3f2c9a4e-6b1d-4c2a-9f0e-8d7b5a1c2e33",
"object": "director.job",
"endpoint": "videos/music",
"videoModel": "montage-basic",
"videoModelName": "Montage Basic",
"status": "queued",
"stage": "Preparing the shoot",
"progress": 0,
"etaSeconds": 1140,
"credits": { "quoted": 3316, "charged": 0 },
"output": null,
"parts": [],
"error": null,
"createdAt": "2026-11-18T09:12:04.551Z",
"completedAt": null
}The job object
Every start, poll, list and cancel returns this shape. Fields marked optional appear only for the endpoints that fill them.
| Field | Description |
|---|---|
| iduuid | The job id. Poll GET /jobs/{id}. |
| object"director.job" | Always director.job. |
| endpointstring | The start endpoint, e.g. videos/music. |
| videoModelmontage-basic | montage-premium | montage-ultra | The tier it renders on; videoModelName is the display name. |
| statusqueued | running | done | failed | cancelled | Where the job is. Only done has an output. |
| stagestring | Plain words, e.g. “9 of 15 parts done” or “Finishing the cut”. |
| progressnumber 0–1 | Held at 0.99 until the job is done. |
| etaSecondsnumber | null | Estimated seconds left; queue adds jobs ahead and an ETA. |
| credits{ quoted, charged } | quoted is held at start; charged is what you paid, never more. |
| output{ type, url, assetPath, generationId } | null | The finished file. url is signed for 6 hours. |
| parts[{ index, label, url }] | Rendered sections or clips. |
| deliverables[{ …, url, assetPath }] | Extra formats and cut-downs from packaging. |
| storyboardoptional{ waiting, stills, url, sheetUrl } | Present when the job holds for storyboard approval. |
| resultoptionalobject | null | What a writer endpoint wrote, once done. |
| analysis · understanding · transcript · planoptionalobject | The answer from study, transcribe and plan endpoints. |
| versionJobIds · versionOf · sourceJobIdstring[] · string | Links between redos, finals and their source jobs. |
| errorstring | null | Why it failed, in plain words. |
| createdAt · completedAtISO date | completedAt is null until the job ends. |
Endpoints
85 endpoints, all under /api/v1/director. Open a row for its key fields, files and price. The catalog endpoint returns the full field list for every one.
Make
Start a production. Every call answers 202 with a job and a Location header to poll.
Redo, fix and finish
Work on a finished job by id. Only the part you change is rendered and billed.
Edit with words
Change what is on screen, crop, add graphics or stitch cuts.
Audio
Every sound tool the studio uses, on its own.
Write, check and study
The writer and the critic, without rendering anything.
Jobs
Poll, list, cancel and download. Reads are free.
Brands, series and looks
Save what should stay the same across productions.
Sending media
Uploads, links and earlier jobs are interchangeable.
- Send JSON or
multipart/form-datato any start endpoint. In a form,"true"/"false"become booleans, numbers become numbers, and values starting with[or{are parsed as JSON. - Every file field takes an upload, a public
httpsURL, or a path in your Pixio assets. Use<field>_urlor<field>_urlsto pass links in JSON. - Any field that takes a
job_idworks on your finished jobs, so redo, upscale, package and dub chain without downloading anything. - Text is measured as sent, and each line break counts as two characters. Over a limit you get
400withfield,maxLengthandlength. - Unknown fields are ignored, so check spelling against
GET /catalogwhen a setting seems to have no effect.
curl -X POST https://beta.pixio.myapps.ai/api/v1/director/videos/reference \
-H "Authorization: Bearer $PIXIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "The woman from the first picture opens the bakery from the second at dawn",
"duration": 10,
"images_urls": ["https://example.com/hero.jpg", "https://example.com/bakery.jpg"],
"package": { "tagline": "Fresh at five", "captions": true }
}'Free quotes
Add ?dry_run=true (or ?check=true on the make endpoints) to get the exact credit quote and a prompt check. Nothing starts and nothing is held.
Free quotes work on these 9 endpoints. On any other endpoint the query string is ignored and the job starts, so quote with the endpoints below or read prices from GET /catalog.
- POST /videos/music
- POST /videos/film
- POST /videos/text
- POST /videos/image
- POST /videos/reference
- POST /videos/remake
- POST /series/{id}/episodes
- POST /videos/package
- POST /jobs/{id}/edit
POST /prompts/check checks prompts on their own, free and synchronous.
curl -X POST "https://beta.pixio.myapps.ai/api/v1/director/videos/film?dry_run=true" \
-H "Authorization: Bearer $PIXIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"idea": "A lighthouse keeper finds a message in a bottle from herself",
"duration": 60,
"aspect": "16:9"
}'Errors
Every error is JSON with a sentence in error and a stable code to branch on. When a call fails before starting, nothing is charged.
| Status | code | |
|---|---|---|
| 400 | invalid_requestA field is wrong. details lists each one as {field, message}. | A field is wrong. details lists each one as {field, message}. |
| 400 | invalid_jsonThe body is not a JSON object or multipart form. | The body is not a JSON object or multipart form. |
| 400 | invalid_media_urlA media URL could not be fetched, or the asset is not yours. | A media URL could not be fetched, or the asset is not yours. |
| 401 | missing_api_keyNo Authorization header. | No Authorization header. |
| 401 | invalid_api_keyThe key is malformed, unknown or revoked. | The key is malformed, unknown or revoked. |
| 402 | insufficient_creditsThe hold is more than your balance. requiredCredits says how much. | The hold is more than your balance. requiredCredits says how much. |
| 404 | not_foundThe job, brand, series or look is not yours or does not exist. | The job, brand, series or look is not yours or does not exist. |
| 409 | conflictThe job you referenced has not finished, or the output is not ready. | The job you referenced has not finished, or the output is not ready. |
| 422 | prompt_check_failedThe prompt check found blocking issues. promptCheck lists them. | The prompt check found blocking issues. promptCheck lists them. |
| 429 | concurrency_limit8 jobs are already running. Retry after Retry-After seconds. | 8 jobs are already running. Retry after Retry-After seconds. |
| 503 | premium_unavailableA paid tier could not take the job. Nothing was charged. | A paid tier could not take the job. Nothing was charged. |
| 503 | service_unavailableThe studio is briefly offline. Nothing was charged. | The studio is briefly offline. Nothing was charged. |
{
"error": "The request has invalid fields.",
"code": "invalid_request",
"details": [
{ "field": "duration", "message": "Must be a multiple of 15 between 30 and 420." }
]
}Pricing
Credits, at 1 credit = $0.01. A job holds its quote when it starts and charges what it rendered when it ends, never more than the hold.
| Item | Credits | Draft |
|---|---|---|
| Music video section (15 s) | 201 | 180 |
| Film clip (15 s) | 115 | 73 |
| Single shot, fast | 4.73 / s | — |
| Single shot, quality | 7.57 / s | — |
| Writer round | 151 | — |
| Commercial review · fact-check · recap | 76 | — |
| Upscale to 1080p, per 15 s | 71 | — |
| Face fix, per section | 59 | — |
| Song | 36 + | — |
| Finish · package, per second | 1.46 | — |
| Storyboard still | 25 | — |
| Visual QA, per section | 16 full · 4 local | — |
| AI prompt fix (fix_prompt: "ai") | +16 | — |
| Minimum for any paid call | 16 | — |
Worked example: a 60 s film from an idea quotes 836 — four clips at 115, one writer round at 151, and 225 held for designed pictures. Prices here are Montage Basic; paid tiers are quoted per job.
Model tiers
Pick a tier with video_model on the make endpoints. Redo, fix and finish calls use the tier of the job they work on.
- montage-basic
Montage Basic
The default. Up to 9 pictures. Every price on this page is Basic.
- montage-premium
Montage Premium
Up to 30 pictures, 480p or 720p. Quoted per job, plus 76 for prompts unless
verbatim. - montage-ultra
Montage Ultra
The top tier, quoted per job like Premium.
Limits
There is no per-key rate limit; the cap is jobs running at once. A repeated POST starts a second job, so retry only after a 429 or a 5xx.
- Jobs at once
- 8per account; 429 with Retry-After: 30
- Lip-synced song
- 6:00sections of 15 s
- Film length
- 30 s – 7 minmultiples of 15 s
- Pictures
- 9 · 30Basic · Premium and Ultra
- Prompt
- 8,000 charsidea 4,000 · style 500
- Output links
- 6 hourssigned; request again for a fresh one
For agents
Montage is built to be driven by your own agent: machine-readable docs, a catalog of every field, and plain-English errors.
- GET /api/v1/montage
A no-auth JSON overview of what Montage makes, its workflow, limits and prices. Hand it to an agent first.
- OpenAPI 3 spec
Every Director path with schemas, for code generators and tool-calling agents.
- The full guide
Every field of every endpoint, with worked prices and recipes.
Ship your first film today.
Create a key, run the quickstart, and watch it render.
