{"openapi":"3.1.0","info":{"title":"Pixio API","version":"1.0.0","description":"Generate AI media, manage assets, inspect credits, and run saved workflows. Typical flow: GET /models -> GET /params -> POST /uploads -> POST /generate -> poll GET /generations/{id}. See GET /guide for the full protocol. Every error body is the ApiError envelope: branch on `code`, show `error`."},"servers":[{"url":"https://beta.pixio.myapps.ai/api/v1"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"Pixio API key"}},"schemas":{"Voice":{"type":"object","required":["id","name","provider","category"],"properties":{"id":{"type":"string","description":"The provider voice id"},"name":{"type":"string"},"provider":{"type":"string","enum":["elevenlabs","cartesia"]},"category":{"type":"string","enum":["premade","library","cloned"]},"language":{"type":["string","null"]},"accent":{"type":["string","null"]},"gender":{"type":["string","null"]},"description":{"type":["string","null"]},"previewUrl":{"type":["string","null"]},"assetId":{"type":["string","null"],"description":"Your clone asset id (clones only)"},"use":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Params to merge into POST /generate. Null for a shared-library hit until it is added."},"add":{"type":["object","null"],"description":"Body for POST /voices/add (shared-library hits only)","properties":{"voiceId":{"type":"string"},"publicOwnerId":{"type":"string"},"name":{"type":"string"}}}}},"ApiError":{"type":"object","required":["error","code"],"description":"The one error envelope. Branch on `code` (stable machine string); `error` is a human-readable sentence. For a few legacy bodies (`invalid_media_url`, `invalid_idempotency_key`, `invalid_request` from /generations/estimate, `invalid_workflow_definition`, `invalid_workflow_override`, `model_not_available` from /video-agent/projects/{id}/generate) `error` equals `code` and the sentence is in `message`. Codes: missing_api_key, invalid_api_key (401); service_unavailable (503); invalid_json, invalid_request, invalid_idempotency_key, invalid_media_url, invalid_workflow_override (400); on POST /generate every generation-pipeline failure is also 400: provider_error, model_unavailable, plan_restricted, maker_in_flight, generation_failed, server_error; model_not_available (400, video-agent generate); insufficient_credits (402); not_found, model_not_found (404); request_too_large (413); invalid_workflow_definition, content_policy (422); concurrency_limit (429); internal_error (500); provider_error (502 on /media, /images, /prompts/optimize, /voices), workflow_dispatch_failed (502); optimizer_error (500, 502, 504). Individual operations list the codes they can return.","properties":{"error":{"type":"string","description":"Human-readable sentence (equals `code` on the legacy bodies listed above)."},"code":{"type":"string","description":"Stable machine string. Branch on this."},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true,"description":"On invalid_request: the field-level validation report, { formErrors, fieldErrors }."}},"additionalProperties":true},"InsufficientCreditsError":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","example":"Insufficient credits"},"code":{"type":"string","const":"insufficient_credits"},"availableCredits":{"type":"number"},"requiredCredits":{"type":"number"},"shortfall":{"type":"number"}}},"ContentPolicyError":{"type":"object","required":["error","code","message"],"properties":{"error":{"type":"string","description":"Same sentence as `message`."},"code":{"type":"string","const":"content_policy"},"message":{"type":"string"},"inputHint":{"type":["string","null"],"description":"The input the check identified (prompt, image, video, audio), or null."},"inputsSubmitted":{"type":"array","items":{"type":"string"},"description":"Inputs present on the request: the search space when inputHint is null."}}},"ConcurrencyLimitError":{"type":"object","required":["error","code","message","concurrencyLimit","retryAfter"],"description":"Sent with 429 and a Retry-After: 10 header. A per-account limit on API jobs running at once, shared by every key on the account.","properties":{"error":{"type":"string"},"code":{"type":"string","const":"concurrency_limit"},"message":{"type":"string"},"concurrencyLimit":{"type":"integer"},"retryAfter":{"type":"integer","description":"Seconds."},"generationId":{"type":"string","description":"POST /generate: the running generation to poll (present while one is running)."},"runId":{"type":"string","description":"POST /workflows/{id}/runs: the running workflow run to poll."},"status":{"type":"string"}}},"UploadItem":{"type":"object","properties":{"id":{"type":"string","description":"Asset id. Pass it as `assetIds` to the collections API."},"sourceUrl":{"type":["string","null"]},"filePath":{"type":"string"},"url":{"type":"string"},"signedUrl":{"type":"string"},"signedUrlExpiresAt":{"type":"string","format":"date-time"},"fileName":{"type":"string"},"fileSize":{"type":"integer"},"contentType":{"type":"string"},"mediaType":{"type":"string"}}},"WorkflowDefinition":{"type":"object","required":["version","nodes","edges"],"description":"The graph the app builder saves. GET /workflows/{id} returns it; send the same shape to POST /workflows or PATCH /workflows/{id}.","properties":{"version":{"type":"integer","const":1},"nodes":{"type":"array","items":{"type":"object","additionalProperties":true}},"edges":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"Workflow":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"definition":{"$ref":"#/components/schemas/WorkflowDefinition"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ModelOutputs":{"type":"object","description":"What the model returns. Structured-result models (transcription) answer with `format: \"json\"` and no output file URL.","properties":{"format":{"type":"string","enum":["json","file"]},"hasFileUrl":{"type":"boolean"}}},"PaidDownload":{"type":"object","description":"Songcraft songs only. A song has two paid download tiers, each charged once per song: `preview` (100 credits, the preview MP3) and `official` (300 credits, the official commercial MP3; paying for it also unlocks the preview). While `required` is true the file URL on generations, assets, and workflow runs is null; call `endpoint` with ?tier=preview or ?tier=official to pay and get the file. After either tier is paid the URL is returned as usual.","required":["required","endpoint","creditsDue"],"properties":{"required":{"type":"boolean"},"endpoint":{"type":"string","description":"GET /api/v1/assets/{id}/download for this song."},"creditsDue":{"type":"object","description":"Credits still owed per tier; 0 once that tier is paid.","properties":{"preview":{"type":"integer"},"official":{"type":"integer","nullable":true,"description":"Null for older songs that have no official tier."}}}}},"GenerateRequest":{"type":"object","required":["modelId"],"properties":{"modelId":{"type":"string","description":"Public model id, e.g. pixio/flux/dev"},"providerId":{"type":"string"},"params":{"type":"object","additionalProperties":true}}},"EstimateRequest":{"type":"object","required":["modelId"],"properties":{"modelId":{"type":"string","description":"Public model id, e.g. pixio/flux/dev"},"providerId":{"type":"string"},"params":{"type":"object","additionalProperties":true},"durationSeconds":{"type":"number","exclusiveMinimum":0,"description":"Price a length you have not uploaded yet. Ignored when the request carries media: the server measures the file, and the measurement is what bills."}}},"ImageRequest":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"urls":{"type":"array","items":{"type":"string","format":"uri"}}},"description":"JSON body to mirror one or more remote URLs; or send multipart/form-data with file/url fields."}}},"paths":{"/preferences/models":{"get":{"operationId":"getModelPreferences","summary":"Read saved model preferences","description":"Send Authorization: Bearer <api_key>. Preferences belong to the user associated with that key. Read-only: manage preferences in the app. Returns saved overrides with public model IDs. Entries whose IDs cannot be converted are omitted. Discover all valid action keys and eligible choices at /api/v1/preferences/models/catalog.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Saved preferences","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["actionKey","modelId"],"properties":{"actionKey":{"type":"string","enum":["create-video","grok-edit-image","grok-edit-video","create-3d","image-upscale","upscale-video","next-frame","add-lipsync","generate-voice","remove-bg","upscale-magnific","photo-restoration","caption-video","video-bg-remover","seedance-remove-watermark","lipsync-video","generate-image-t2i","generate-video-t2v","generate-music"],"example":"generate-image-t2i"},"modelId":{"type":"string","pattern":"^pixio/","description":"Public pixio/... model ID, usable directly in generation requests. Preferences can only be changed in the app."},"label":{"type":"string"},"description":{"type":"string"}}}}}},"example":{"data":[{"actionKey":"generate-image-t2i","modelId":"pixio/flux/dev","label":"Generate Image","description":"Default for text-to-image on Generate."}]}}}},"401":{"description":"Missing, invalid, or revoked API key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"example":{"error":"Invalid API key."}}}},"500":{"description":"Database or catalog error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}},"503":{"description":"API key storage unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}}},"/preferences/models/catalog":{"get":{"operationId":"getModelPreferenceCatalog","summary":"Discover all model preference slots and eligible models","description":"Send Authorization: Bearer <api_key>. Preferences belong to the user associated with that key. Lists every configured action, including slots with no eligible models. Choices are enabled, visible to the account plan, and compatible with the action. This endpoint is read-only; preferences are managed in the app. modelId is the public pixio/... ID for generation requests. This is not a guarantee of credits, capacity, or provider availability.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Preference catalog","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["actionKey","label","description","eligibleModels"],"properties":{"actionKey":{"type":"string","enum":["create-video","grok-edit-image","grok-edit-video","create-3d","image-upscale","upscale-video","next-frame","add-lipsync","generate-voice","remove-bg","upscale-magnific","photo-restoration","caption-video","video-bg-remover","seedance-remove-watermark","lipsync-video","generate-image-t2i","generate-video-t2v","generate-music"],"example":"generate-image-t2i"},"label":{"type":"string"},"description":{"type":"string"},"eligibleModels":{"type":"array","items":{"type":"object","required":["modelId","name"],"properties":{"modelId":{"type":"string","pattern":"^pixio/","description":"Public pixio/... model ID, usable directly in generation requests. Preferences can only be changed in the app."},"name":{"type":"string"}}}}}}}}},"example":{"data":[{"actionKey":"generate-image-t2i","label":"Generate Image","description":"Default for text-to-image on Generate.","eligibleModels":[{"modelId":"pixio/flux/dev","name":"FLUX Dev"}]}]}}}},"401":{"description":"Missing, invalid, or revoked API key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"example":{"error":"Invalid API key."}}}},"500":{"description":"Database or catalog error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}},"503":{"description":"API key storage unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}}},"/director/videos/text":{"post":{"summary":"Director: text to video shot","description":"One 5–15 s shot from a prompt (up to 8000 characters). Prompts in the official format are checked first; checker errors return 422 `prompt_check_failed` and nothing is charged. Price: max(8, duration) x 4.73 credits (`quality: \"fast\"`) or x 7.57 (`quality: \"quality\"`), rounded up; x steps/8 above 8 steps; x 1.8 with `vsa: false`. A 5 s fast shot is 38 credits, a 15 s quality shot 114. With `brand_id` / `package` the packaging (1.46 credits a second of video written, at least 16) is held too and becomes its own job (`packageJobId`); `?check=true` shows `credits.clip` and `credits.packaging`.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"parameters":[{"name":"check","in":"query","description":"true: return the prompt-check report and the credit quote instead of starting (free).","schema":{"type":"boolean"}},{"name":"dry_run","in":"query","description":"true: return what would be sent, the report and the quote instead of starting (free).","schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"video_model":{"description":"`montage-basic` (Montage Basic), `montage-premium` (Montage Premium) or `montage-ultra` (Montage Ultra); every value with its name and whether it is offered right now is in GET /director/catalog under `videoModels.models`. Left out, it is always `montage-basic`. Montage Premium is sharper and more lifelike; Montage Ultra uses the highest-quality model on every shot and costs more. Both are offered when Pixio turns them on (`videoModels.premiumAvailable` in GET /director/catalog; `premium_unavailable` otherwise); its renders are priced from the studio’s own quote of the takes plus 30%, plus 76 credits to write the prompts for it, in place of the Basic clip price, so quote with `?check=true` first. Premium makes one version at a time, has no draft/final (it is already full quality) and its retakes cost the part price it was sold at. The job shows `videoModel` and `videoModelName`."},"resolution":{"description":"Premium only: `480p` or `720p` (about twice the cost). Leave it out for Pixio’s default; for more, `upscale`."},"verbatim":{"description":"Boolean (default false). Your prompts are used exactly as sent: no rewrite or added lines (the prompt check may still refuse, never edit). Not with an `idea`, remakes or episodes. On Premium and Ultra it also skips the prompt-writing charge."},"prompt":{"description":"The shot prompt: up to 8000 characters on Montage Basic, 30,000 with `video_model` `montage-premium` or `montage-ultra` in the body (counted as sent: each line break counts as two). Plain prompts always render; prompts in the official format are checked first (422 `prompt_check_failed` on errors)."},"duration":{"description":"Shot length in seconds, 5–15 (default 5). Billed as at least 8 s."},"quality":{"description":"`fast` (default price, 4.73 credits a second) or `quality` (7.57 credits a second)."},"aspect":{"description":"Frame shape, for example `16:9`, `9:16` or `1:1`."},"seed":{"description":"Integer seed, to repeat a result."},"enhancer_strength":{"description":"Advanced tuning. Leave unset for the default."},"speed":{"description":"`draft` renders cheaper and faster for a first look; leave unset for full quality."},"vsa":{"description":"Boolean, on by default. `false` renders about 1.8x slower and is priced 1.8x."},"look":{"description":"A named look from GET /director/catalog: `default`, `realistic_people`, `soft_portrait`, `golden_hour`, `film_teal`, `anime_90s`, `horror_80s`, `raw_skin`."},"steps":{"description":"Sampling steps. More than the default costs more in proportion (never less than the default price)."},"vsa_start":{"description":"Advanced tuning. Leave unset for the default."},"strict_prompt":{"description":"Boolean, default true. `false` renders an official-format prompt even when the checker finds errors."},"fight_flow":{"description":"Shots that read as a fight get Fight Flow automatically (each blow sets up the next). `false` turns it off, `true` forces it."},"fight_motion":{"description":"Advanced tuning. Leave unset for the default."},"fix_prompt":{"description":"`off` (default), `safe` (rule-based, instant) or `ai` (also fixes what the checker still finds). Repairs untrained camera words, grain words and \"no crowd\" lines in your own prompts. `safe` is free; `ai` adds 16 credits."},"brand_id":{"description":"A brand id from POST /director/brands. Only your own brands work (404 otherwise). Turns on packaging."},"package":{"description":"A JSON object of packaging fields (the same fields as POST /director/videos/package, e.g. `tagline`, `cta`, `formats`, `cutdowns`, `captions`, `score`). Turns on packaging; priced like packaging. Text limits apply inside it (tagline 120, cta 60, legal 300, title_card 160, voiceover_text 1500)."}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"video_model":{"description":"`montage-basic` (Montage Basic), `montage-premium` (Montage Premium) or `montage-ultra` (Montage Ultra); every value with its name and whether it is offered right now is in GET /director/catalog under `videoModels.models`. Left out, it is always `montage-basic`. Montage Premium is sharper and more lifelike; Montage Ultra uses the highest-quality model on every shot and costs more. Both are offered when Pixio turns them on (`videoModels.premiumAvailable` in GET /director/catalog; `premium_unavailable` otherwise); its renders are priced from the studio’s own quote of the takes plus 30%, plus 76 credits to write the prompts for it, in place of the Basic clip price, so quote with `?check=true` first. Premium makes one version at a time, has no draft/final (it is already full quality) and its retakes cost the part price it was sold at. The job shows `videoModel` and `videoModelName`."},"resolution":{"description":"Premium only: `480p` or `720p` (about twice the cost). Leave it out for Pixio’s default; for more, `upscale`."},"verbatim":{"description":"Boolean (default false). Your prompts are used exactly as sent: no rewrite or added lines (the prompt check may still refuse, never edit). Not with an `idea`, remakes or episodes. On Premium and Ultra it also skips the prompt-writing charge."},"prompt":{"description":"The shot prompt: up to 8000 characters on Montage Basic, 30,000 with `video_model` `montage-premium` or `montage-ultra` in the body (counted as sent: each line break counts as two). Plain prompts always render; prompts in the official format are checked first (422 `prompt_check_failed` on errors)."},"duration":{"description":"Shot length in seconds, 5–15 (default 5). Billed as at least 8 s."},"quality":{"description":"`fast` (default price, 4.73 credits a second) or `quality` (7.57 credits a second)."},"aspect":{"description":"Frame shape, for example `16:9`, `9:16` or `1:1`."},"seed":{"description":"Integer seed, to repeat a result."},"enhancer_strength":{"description":"Advanced tuning. Leave unset for the default."},"speed":{"description":"`draft` renders cheaper and faster for a first look; leave unset for full quality."},"vsa":{"description":"Boolean, on by default. `false` renders about 1.8x slower and is priced 1.8x."},"look":{"description":"A named look from GET /director/catalog: `default`, `realistic_people`, `soft_portrait`, `golden_hour`, `film_teal`, `anime_90s`, `horror_80s`, `raw_skin`."},"steps":{"description":"Sampling steps. More than the default costs more in proportion (never less than the default price)."},"vsa_start":{"description":"Advanced tuning. Leave unset for the default."},"strict_prompt":{"description":"Boolean, default true. `false` renders an official-format prompt even when the checker finds errors."},"fight_flow":{"description":"Shots that read as a fight get Fight Flow automatically (each blow sets up the next). `false` turns it off, `true` forces it."},"fight_motion":{"description":"Advanced tuning. Leave unset for the default."},"fix_prompt":{"description":"`off` (default), `safe` (rule-based, instant) or `ai` (also fixes what the checker still finds). Repairs untrained camera words, grain words and \"no crowd\" lines in your own prompts. `safe` is free; `ai` adds 16 credits."},"brand_id":{"description":"A brand id from POST /director/brands. Only your own brands work (404 otherwise). Turns on packaging."},"package":{"description":"A JSON object of packaging fields (the same fields as POST /director/videos/package, e.g. `tagline`, `cta`, `formats`, `cutdowns`, `captions`, `score`). Turns on packaging; priced like packaging. Text limits apply inside it (tagline 120, cta 60, legal 300, title_card 160, voiceover_text 1500)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"With ?check=true or ?dry_run=true: a free preflight { object: \"director.preflight\", credits.quoted, promptCheck, … }. Nothing is reserved or rendered."},"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/image":{"post":{"summary":"Director: image to video shot","description":"Animates one picture (`image`) into a 5–15 s shot, guided by `prompt`. Optional `logo` and `packshot` for packaging. Price: max(8, duration) x 4.73 credits (`quality: \"fast\"`) or x 7.57 (`quality: \"quality\"`), rounded up; x steps/8 above 8 steps; x 1.8 with `vsa: false`. A 5 s fast shot is 38 credits, a 15 s quality shot 114. With `brand_id` / `package` the packaging (1.46 credits a second of video written, at least 16) is held too and becomes its own job (`packageJobId`); `?check=true` shows `credits.clip` and `credits.packaging`.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"parameters":[{"name":"check","in":"query","description":"true: return the prompt-check report and the credit quote instead of starting (free).","schema":{"type":"boolean"}},{"name":"dry_run","in":"query","description":"true: return what would be sent, the report and the quote instead of starting (free).","schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"video_model":{"description":"`montage-basic` (Montage Basic), `montage-premium` (Montage Premium) or `montage-ultra` (Montage Ultra); every value with its name and whether it is offered right now is in GET /director/catalog under `videoModels.models`. Left out, it is always `montage-basic`. Montage Premium is sharper and more lifelike; Montage Ultra uses the highest-quality model on every shot and costs more. Both are offered when Pixio turns them on (`videoModels.premiumAvailable` in GET /director/catalog; `premium_unavailable` otherwise); its renders are priced from the studio’s own quote of the takes plus 30%, plus 76 credits to write the prompts for it, in place of the Basic clip price, so quote with `?check=true` first. Premium makes one version at a time, has no draft/final (it is already full quality) and its retakes cost the part price it was sold at. The job shows `videoModel` and `videoModelName`."},"resolution":{"description":"Premium only: `480p` or `720p` (about twice the cost). Leave it out for Pixio’s default; for more, `upscale`."},"verbatim":{"description":"Boolean (default false). Your prompts are used exactly as sent: no rewrite or added lines (the prompt check may still refuse, never edit). Not with an `idea`, remakes or episodes. On Premium and Ultra it also skips the prompt-writing charge."},"prompt":{"description":"The shot prompt: up to 8000 characters on Montage Basic, 30,000 with `video_model` `montage-premium` or `montage-ultra` in the body (counted as sent: each line break counts as two). Plain prompts always render; prompts in the official format are checked first (422 `prompt_check_failed` on errors)."},"duration":{"description":"Shot length in seconds, 5–15 (default 5). Billed as at least 8 s."},"quality":{"description":"`fast` (default price, 4.73 credits a second) or `quality` (7.57 credits a second)."},"aspect":{"description":"Frame shape, for example `16:9`, `9:16` or `1:1`."},"seed":{"description":"Integer seed, to repeat a result."},"enhancer_strength":{"description":"Advanced tuning. Leave unset for the default."},"speed":{"description":"`draft` renders cheaper and faster for a first look; leave unset for full quality."},"vsa":{"description":"Boolean, on by default. `false` renders about 1.8x slower and is priced 1.8x."},"look":{"description":"A named look from GET /director/catalog: `default`, `realistic_people`, `soft_portrait`, `golden_hour`, `film_teal`, `anime_90s`, `horror_80s`, `raw_skin`."},"steps":{"description":"Sampling steps. More than the default costs more in proportion (never less than the default price)."},"vsa_start":{"description":"Advanced tuning. Leave unset for the default."},"strict_prompt":{"description":"Boolean, default true. `false` renders an official-format prompt even when the checker finds errors."},"fight_flow":{"description":"Shots that read as a fight get Fight Flow automatically (each blow sets up the next). `false` turns it off, `true` forces it."},"fight_motion":{"description":"Advanced tuning. Leave unset for the default."},"fix_prompt":{"description":"`off` (default), `safe` (rule-based, instant) or `ai` (also fixes what the checker still finds). Repairs untrained camera words, grain words and \"no crowd\" lines in your own prompts. `safe` is free; `ai` adds 16 credits."},"exif_rotate":{"description":"Boolean. Turn uploaded pictures upright by their EXIF orientation."},"brand_id":{"description":"A brand id from POST /director/brands. Only your own brands work (404 otherwise). Turns on packaging."},"package":{"description":"A JSON object of packaging fields (the same fields as POST /director/videos/package, e.g. `tagline`, `cta`, `formats`, `cutdowns`, `captions`, `score`). Turns on packaging; priced like packaging. Text limits apply inside it (tagline 120, cta 60, legal 300, title_card 160, voiceover_text 1500)."},"image":{"description":"The picture to animate. image: multipart file(s), or URL / asset path string(s); up to 1."},"image_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"logo":{"description":"Logo image (a PNG with transparency works best). Turns on packaging. image: multipart file(s), or URL / asset path string(s); up to 1."},"logo_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"packshot":{"description":"The product picture shown on the end card. image: multipart file(s), or URL / asset path string(s); up to 1."},"packshot_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"200":{"description":"With ?check=true or ?dry_run=true: a free preflight { object: \"director.preflight\", credits.quoted, promptCheck, … }. Nothing is reserved or rendered."},"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/reference":{"post":{"summary":"Director: reference to video shot","description":"A 5–15 s shot built from up to 9 `images` (up to 30 on Montage Premium and Ultra), 3 `videos` and 3 `audios`; refer to pictures in the prompt as <Picture 1>, <Picture 2>… Price: max(8, duration) x 4.73 credits (`quality: \"fast\"`) or x 7.57 (`quality: \"quality\"`), rounded up; x steps/8 above 8 steps; x 1.8 with `vsa: false`. A 5 s fast shot is 38 credits, a 15 s quality shot 114. With `brand_id` / `package` the packaging (1.46 credits a second of video written, at least 16) is held too and becomes its own job (`packageJobId`); `?check=true` shows `credits.clip` and `credits.packaging`.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"parameters":[{"name":"check","in":"query","description":"true: return the prompt-check report and the credit quote instead of starting (free).","schema":{"type":"boolean"}},{"name":"dry_run","in":"query","description":"true: return what would be sent, the report and the quote instead of starting (free).","schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"long_form":{"description":"Boolean (default false). One unbroken 20–60 s Montage Basic take with no cuts — a walk, a dance, a singer coming toward the camera — rendered in 2–4 pieces that carry on from each other, so the joins do not show. One place, at most 3 people. Priced per second of the take (about 18 credits a second, 1.7x at `megapixels: 1.0`) plus a writer round when the AI writes the pieces. Premium and Ultra refuse it; if long takes are switched off it answers 400 `long_form_unavailable` and nothing is held."},"long_form_pieces":{"description":"With `long_form` on `videos/reference`, optional: a JSON list of your own prompts, one per 15 s piece. Left out, the AI writes the pieces from `prompt`."},"video_model":{"description":"`montage-basic` (Montage Basic), `montage-premium` (Montage Premium) or `montage-ultra` (Montage Ultra); every value with its name and whether it is offered right now is in GET /director/catalog under `videoModels.models`. Left out, it is always `montage-basic`. Montage Premium is sharper and more lifelike; Montage Ultra uses the highest-quality model on every shot and costs more. Both are offered when Pixio turns them on (`videoModels.premiumAvailable` in GET /director/catalog; `premium_unavailable` otherwise); its renders are priced from the studio’s own quote of the takes plus 30%, plus 76 credits to write the prompts for it, in place of the Basic clip price, so quote with `?check=true` first. Premium makes one version at a time, has no draft/final (it is already full quality) and its retakes cost the part price it was sold at. The job shows `videoModel` and `videoModelName`."},"resolution":{"description":"Premium only: `480p` or `720p` (about twice the cost). Leave it out for Pixio’s default; for more, `upscale`."},"verbatim":{"description":"Boolean (default false). Your prompts are used exactly as sent: no rewrite or added lines (the prompt check may still refuse, never edit). Not with an `idea`, remakes or episodes. On Premium and Ultra it also skips the prompt-writing charge."},"prompt":{"description":"The shot prompt: up to 8000 characters on Montage Basic, 30,000 with `video_model` `montage-premium` or `montage-ultra` in the body (counted as sent: each line break counts as two). Plain prompts always render; prompts in the official format are checked first (422 `prompt_check_failed` on errors)."},"audio_lock":{"description":"Advanced tuning. Leave unset for the default."},"video_audio":{"description":"Advanced tuning. Leave unset for the default."},"duration":{"description":"Shot length in seconds, 5–15 (default 5). Billed as at least 8 s."},"quality":{"description":"`fast` (default price, 4.73 credits a second) or `quality` (7.57 credits a second)."},"aspect":{"description":"Frame shape, for example `16:9`, `9:16` or `1:1`."},"seed":{"description":"Integer seed, to repeat a result."},"enhancer_strength":{"description":"Advanced tuning. Leave unset for the default."},"speed":{"description":"`draft` renders cheaper and faster for a first look; leave unset for full quality."},"steps":{"description":"Sampling steps. More than the default costs more in proportion (never less than the default price)."},"vsa_start":{"description":"Advanced tuning. Leave unset for the default."},"exif_rotate":{"description":"Boolean. Turn uploaded pictures upright by their EXIF orientation."},"strict_prompt":{"description":"Boolean, default true. `false` renders an official-format prompt even when the checker finds errors."},"fight_flow":{"description":"Shots that read as a fight get Fight Flow automatically (each blow sets up the next). `false` turns it off, `true` forces it."},"fight_motion":{"description":"Advanced tuning. Leave unset for the default."},"realism":{"description":"Number from 0 to 1: how photographic the result is (natural, matte skin). Montage Basic only. Reference clips default to 0 (off); a series episode defaults to the show’s realism; send 0 for animation."},"megapixels":{"description":"Images: picture size in megapixels, priced between 0.5 and 16; default 4. `videos/reference` on Montage Basic: `0.7` (default) or `1.0` for a sharper render (priced 1.7x); refused on Montage Premium and Ultra."},"fix_prompt":{"description":"`off` (default), `safe` (rule-based, instant) or `ai` (also fixes what the checker still finds). Repairs untrained camera words, grain words and \"no crowd\" lines in your own prompts. `safe` is free; `ai` adds 16 credits."},"brand_id":{"description":"A brand id from POST /director/brands. Only your own brands work (404 otherwise). Turns on packaging."},"package":{"description":"A JSON object of packaging fields (the same fields as POST /director/videos/package, e.g. `tagline`, `cta`, `formats`, `cutdowns`, `captions`, `score`). Turns on packaging; priced like packaging. Text limits apply inside it (tagline 120, cta 60, legal 300, title_card 160, voiceover_text 1500)."},"images":{"description":"Reference pictures, numbered in order as <Picture 1>, <Picture 2>… image: multipart file(s), or URL / asset path string(s); up to 30."},"images_urls":{"type":"array","items":{"type":"string"},"maxItems":30},"videos":{"description":"Reference clips. video: multipart file(s), or URL / asset path string(s); up to 3."},"videos_urls":{"type":"array","items":{"type":"string"},"maxItems":3},"audios":{"description":"Reference audio. audio: multipart file(s), or URL / asset path string(s); up to 3."},"audios_urls":{"type":"array","items":{"type":"string"},"maxItems":3},"logo":{"description":"Logo image (a PNG with transparency works best). Turns on packaging. image: multipart file(s), or URL / asset path string(s); up to 1."},"logo_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"packshot":{"description":"The product picture shown on the end card. image: multipart file(s), or URL / asset path string(s); up to 1."},"packshot_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"200":{"description":"With ?check=true or ?dry_run=true: a free preflight { object: \"director.preflight\", credits.quoted, promptCheck, … }. Nothing is reserved or rendered."},"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/music":{"post":{"summary":"Director: make a music video","description":"A lip-synced music video cut to your song (a `song` file or URL, or `song_job`), up to 6 minutes, one 15 s section at a time. Send pictures of the artist as `images` (up to 9; up to 30 on Montage Premium and Ultra, 6–9 a section works best) and either an `idea` (the writer plans the sections) or your own `sections`. Price: sections x 201 (`speed: \"draft\"`: x 180), x steps/8 above the default; plus 151 for the writer with an `idea` and 25 for each picture the studio designs (`make_references`, default on; up to 6 are held, the real count is charged); plus upscale (71 per section), `finish`, `visual_qa` and packaging when asked. Sections = song length / 15 s, rounded up. A 60 s song from an idea holds 1105 credits (1021 as a draft) and is charged less when fewer pictures are designed. If it stops early, only finished sections, the writing and the pictures already designed are charged.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"parameters":[{"name":"check","in":"query","description":"true: return the prompt-check report and the credit quote instead of starting (free).","schema":{"type":"boolean"}},{"name":"dry_run","in":"query","description":"true: return what would be sent, the report and the quote instead of starting (free).","schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"long_form":{"description":"Boolean (default false). One unbroken 20–60 s Montage Basic take with no cuts — a walk, a dance, a singer coming toward the camera — rendered in 2–4 pieces that carry on from each other, so the joins do not show. One place, at most 3 people. Priced per second of the take (about 18 credits a second, 1.7x at `megapixels: 1.0`) plus a writer round when the AI writes the pieces. Premium and Ultra refuse it; if long takes are switched off it answers 400 `long_form_unavailable` and nothing is held."},"long_form_start":{"description":"With `long_form` on `videos/music`: where the take starts in the song, in seconds (default 0)."},"long_form_end":{"description":"With `long_form` on `videos/music`: where the take ends in the song, in seconds (default the end). The part must be 20–60 s."},"megapixels":{"description":"Images: picture size in megapixels, priced between 0.5 and 16; default 4. `videos/reference` on Montage Basic: `0.7` (default) or `1.0` for a sharper render (priced 1.7x); refused on Montage Premium and Ultra."},"video_model":{"description":"`montage-basic` (Montage Basic), `montage-premium` (Montage Premium) or `montage-ultra` (Montage Ultra); every value with its name and whether it is offered right now is in GET /director/catalog under `videoModels.models`. Left out, it is always `montage-basic`. Montage Premium is sharper and more lifelike; Montage Ultra uses the highest-quality model on every shot and costs more. Both are offered when Pixio turns them on (`videoModels.premiumAvailable` in GET /director/catalog; `premium_unavailable` otherwise); its renders are priced from the studio’s own quote of the takes plus 30%, plus 76 credits to write the prompts for it, in place of the Basic clip price, so quote with `?check=true` first. Premium makes one version at a time, has no draft/final (it is already full quality) and its retakes cost the part price it was sold at. The job shows `videoModel` and `videoModelName`."},"resolution":{"description":"Premium only: `480p` or `720p` (about twice the cost). Leave it out for Pixio’s default; for more, `upscale`."},"verbatim":{"description":"Boolean (default false). Your prompts are used exactly as sent: no rewrite or added lines (the prompt check may still refuse, never edit). Not with an `idea`, remakes or episodes. On Premium and Ultra it also skips the prompt-writing charge."},"music_sync":{"description":"Premium music videos: `song` keeps your exact song as the soundtrack and re-times the lips onto it (shorter takes cut at the vocal gaps, so the studio quote and the price are a little higher). Left out, Premium uses its own sung audio, always in sync. Basic always keeps your song."},"speed":{"description":"`draft` (180 credits a section, smaller frame) or full quality (201 credits a section, default). Render a finished draft at full quality later with POST /director/videos/music/{id}/final."},"song_job":{"description":"A finished `music/generate` (or other audio) Director job id to use as the song, instead of a `song` file."},"sections":{"description":"Your own sections as JSON, instead of having the writer plan them from an `idea`."},"idea":{"description":"What the video is about, up to 4000 characters (counted as sent). With an idea the writer plans the sections (151 credits)."},"references":{"description":"What each of your `images` shows, in order, as a JSON list of strings."},"style":{"description":"A look in words for the whole piece, up to 500 characters."},"make_references":{"description":"Boolean, default true. With an `idea`, the studio designs up to 6 pictures of places, props and faces (25 credits each made; the hold covers 6)."},"clip_images":{"description":"Which of your pictures each section or clip uses, as JSON."},"aspect":{"description":"Frame shape, for example `16:9`, `9:16` or `1:1`."},"quality":{"description":"`fast` (default price, 4.73 credits a second) or `quality` (7.57 credits a second)."},"realism":{"description":"Number from 0 to 1: how photographic the result is (natural, matte skin). Montage Basic only. Reference clips default to 0 (off); a series episode defaults to the show’s realism; send 0 for animation."},"seed":{"description":"Integer seed, to repeat a result."},"lipsync":{"description":"`performance` (default), `sung_words` or `none`. `sung_words` uses 12 sampling steps by default instead of 8. `none` makes a story music video: nobody sings, the song is the soundtrack and the writer cuts a story to its sections (needs an `idea`)."},"lock_vocals":{"description":"Advanced tuning. Leave unset for the default."},"steps":{"description":"Sampling steps. More than the default costs more in proportion (never less than the default price)."},"singer_parts":{"description":"Duets, optional: who sings when, in song seconds, with the same keys as `singers` — `{\"first\": [\"0-24.5\", \"40-49\"], \"second\": [\"24.5-40\"]}`. Exact, no detection; use it when the voices are too alike to tell apart. A duet song from `music/generate` (`song_job`) already knows its parts. Free."},"sung_words":{"description":"Advanced tuning. Leave unset for the default."},"sung_subject":{"description":"Advanced tuning. Leave unset for the default."},"vocal_timing":{"description":"Advanced tuning. Leave unset for the default."},"official_audio_wording":{"description":"Advanced tuning. Leave unset for the default."},"finish":{"description":"A finishing pass (grade, grain, loudness) once rendered, as a JSON object of `videos/finish` fields, for example `{\"grade\":\"warm\",\"grain\":0}`. Priced like POST /director/videos/finish."},"upscale":{"description":"Boolean. Upscale to about 1080p when rendered, priced like POST /director/videos/upscale (71 credits per started 15 s)."},"upscale_method":{"description":"Leave unset. Billed at the standard upscale rate (71 credits per started 15 s)."},"exif_rotate":{"description":"Boolean. Turn uploaded pictures upright by their EXIF orientation."},"strict_prompt":{"description":"Boolean, default true. `false` renders an official-format prompt even when the checker finds errors."},"fight_flow":{"description":"Shots that read as a fight get Fight Flow automatically (each blow sets up the next). `false` turns it off, `true` forces it."},"fight_motion":{"description":"Advanced tuning. Leave unset for the default."},"fix_prompt":{"description":"`off` (default), `safe` (rule-based, instant) or `ai` (also fixes what the checker still finds). Repairs untrained camera words, grain words and \"no crowd\" lines in your own prompts. `safe` is free; `ai` adds 16 credits."},"balance_sections":{"description":"Boolean. Evens out a last section under 6 s with the one before it (33 s becomes 15 + 9 + 9). On by default when the AI writes the sections. Send the same value to `music/plan` and `videos/music`."},"visual_qa":{"description":"`local` (4 credits per 15 s part) or `full` (16 credits per 15 s part, adds an AI judge). Findings come back in `qaIssues`; with `<d>` dialogue lines films also get a speech check."},"face_fix":{"description":"`auto`: after rendering, sections whose faces drifted get a face fix as its own job (`faceFixJobId`), billed 59 credits per fixed section. Sections whose drifted shots all show two or more people are skipped and not billed."},"lip_check":{"description":"`off` (default), `measure`, `fix` or `relip`. When the video is done its lip-sync is checked against your song as its own job: `measure` is a lip-sync check (Montage Analyze, 16 credits; its report is that job’s `analysis`), `fix` runs Lip fix auto (held and charged like `videos/lipfix/auto`: only the tries it renders) and makes a fixed copy, `relip` relips the whole video to your song (priced like `videos/relip`) — best for Montage Premium and Ultra. The job is `lipCheckJobId` on the video; retakes and finals are checked the same way. Short of credits, the check is skipped (`lipCheckSkipped`)."},"tier_mix":{"description":"`off` (default), `auto` or `manual`, with Montage Premium or Ultra: some sections (music videos) or clips (films) render on Montage Basic and the rest on Premium, joined in order at their exact lengths. `auto` puts sung or spoken close-ups on Basic (its lip-sync follows your real audio) and wide, action and instrumental parts on Premium; `manual` takes `basic_sections` / `basic_clips`. Basic parts keep the Basic price, Premium parts the Premium price, so a mix costs less than all-Premium."},"basic_sections":{"description":"With `tier_mix: \"manual\"`: the 1-based sections that render on Montage Basic, a JSON list like `[1, 3]`."},"tier_mix_size":{"description":"With `tier_mix`: the one size every part is brought to — `larger` (default), `basic` or `premium`."},"tier_mix_retime":{"description":"Boolean, with `tier_mix` on a music video: re-time each Premium section’s picture onto its slice of your song."},"singers":{"description":"Music videos with an `idea`: a duet. `{\"male\": n, \"female\": m}`, or for two women or two men `{\"first\": n, \"second\": m}` (first = who sings first) — which of your `images` sing (1-based). Singers are told apart by their voice; each line's performance shots and lip-sync go to its singer, the other listening with lips closed. Free."},"brand_id":{"description":"A brand id from POST /director/brands. Only your own brands work (404 otherwise). Turns on packaging."},"package":{"description":"A JSON object of packaging fields (the same fields as POST /director/videos/package, e.g. `tagline`, `cta`, `formats`, `cutdowns`, `captions`, `score`). Turns on packaging; priced like packaging. Text limits apply inside it (tagline 120, cta 60, legal 300, title_card 160, voiceover_text 1500)."},"song":{"description":"The song. Its length sets the number of 15 s sections and the price. audio: multipart file(s), or URL / asset path string(s); up to 1."},"song_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"images":{"description":"Reference pictures, numbered in order as <Picture 1>, <Picture 2>… image: multipart file(s), or URL / asset path string(s); up to 30."},"images_urls":{"type":"array","items":{"type":"string"},"maxItems":30},"logo":{"description":"Logo image (a PNG with transparency works best). Turns on packaging. image: multipart file(s), or URL / asset path string(s); up to 1."},"logo_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"200":{"description":"With ?check=true or ?dry_run=true: a free preflight { object: \"director.preflight\", credits.quoted, promptCheck, … }. Nothing is reserved or rendered."},"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/music/{id}/redo":{"post":{"summary":"Director: re-shoot a music video section","description":"Re-shoots one `section` of a finished music video as a new job (the original is untouched). Price: one section at the source video's speed (201, or 180 for a draft).\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"section":{"description":"Required. The section to re-shoot, 1-based."},"seed":{"description":"A new seed for that section."},"prompt":{"description":"A new prompt for that section, up to 8000 characters."},"clip_images":{"description":"Which of your pictures each section or clip uses, as JSON."},"verbatim":{"description":"Boolean (default false). Your prompts are used exactly as sent: no rewrite or added lines (the prompt check may still refuse, never edit). Not with an `idea`, remakes or episodes. On Premium and Ultra it also skips the prompt-writing charge."},"images":{"description":"Reference pictures, numbered in order as <Picture 1>, <Picture 2>… image: multipart file(s), or URL / asset path string(s); up to 30."},"images_urls":{"type":"array","items":{"type":"string"},"maxItems":30}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"section":{"description":"Required. The section to re-shoot, 1-based."},"seed":{"description":"A new seed for that section."},"prompt":{"description":"A new prompt for that section, up to 8000 characters."},"clip_images":{"description":"Which of your pictures each section or clip uses, as JSON."},"verbatim":{"description":"Boolean (default false). Your prompts are used exactly as sent: no rewrite or added lines (the prompt check may still refuse, never edit). Not with an `idea`, remakes or episodes. On Premium and Ultra it also skips the prompt-writing charge."},"images":{"description":"Reference pictures, numbered in order as <Picture 1>, <Picture 2>… image: multipart file(s), or URL / asset path string(s); up to 30."},"images_urls":{"type":"array","items":{"type":"string"},"maxItems":30}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/film":{"post":{"summary":"Director: make a film, commercial, explainer or documentary","description":"A film of 30 s to 7 min (`duration`, a multiple of 15) from your own `clips` or an `idea`. `film_type` makes it a `commercial`, an `explainer` or a `documentary`; `storyboard: true` stops after writing for your approval; `variants` makes up to 4 versions. Price: clips (duration / 15) x 115 (`speed: \"draft\"`: x 73); with an `idea` plus 151 per writer round (1 round up to 8 clips, otherwise 1 + clips/4 rounded up); plus 76 for a commercial, explainer or documentary, and 76 for a documentary's fact-check (`fact_check`, on by default); with an `idea` plus 25 for each picture the studio designs (up to 9 are held, the real count is charged); plus packaging for explainers, documentaries and branded films; a documentary also gets a score (36 per started 5 minutes); plus upscale, `finish`, `visual_qa` and storyboard stills when asked. A 60 s film from an idea holds 836 credits (668 as a draft, 912 as a commercial); with 6 pictures designed it is charged 761. With `variants`, every version is held and billed like the first. If it stops early, only finished clips, the writing and the pictures already designed are charged.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"parameters":[{"name":"check","in":"query","description":"true: return the prompt-check report and the credit quote instead of starting (free).","schema":{"type":"boolean"}},{"name":"dry_run","in":"query","description":"true: return what would be sent, the report and the quote instead of starting (free).","schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"megapixels":{"description":"Images: picture size in megapixels, priced between 0.5 and 16; default 4. `videos/reference` on Montage Basic: `0.7` (default) or `1.0` for a sharper render (priced 1.7x); refused on Montage Premium and Ultra."},"voice_samples":{"description":"`all` (default): every clip gets every voice sample (`ref_audios`). `used`: each clip gets only the samples its prompt names (`<Audio N>`, in the film’s own numbering), so an unused sample can’t land on a speaker. Use it with `voice_lock`."},"clip_audios":{"description":"Each clip’s own voice samples, like `clip_images`: a JSON list with one list per clip of 1-based positions in `ref_audios`, 0–3 each, e.g. `[[1,2],[2],[],[1,3]]` (`[]` = none). Not with `voice_lock` (use `voice_samples: \"used\"`)."},"no_speech":{"description":"Clips where nobody on screen speaks (narration, montage, establishing shots), as a JSON list of clip numbers, e.g. `[1,11]`: no voice samples there and closed mouths, so nobody mumbles."},"fade":{"description":"Seconds of fade from and to black at the film’s start and end, 0–3 (default 0.5). `0` for films you splice together."},"video_model":{"description":"`montage-basic` (Montage Basic), `montage-premium` (Montage Premium) or `montage-ultra` (Montage Ultra); every value with its name and whether it is offered right now is in GET /director/catalog under `videoModels.models`. Left out, it is always `montage-basic`. Montage Premium is sharper and more lifelike; Montage Ultra uses the highest-quality model on every shot and costs more. Both are offered when Pixio turns them on (`videoModels.premiumAvailable` in GET /director/catalog; `premium_unavailable` otherwise); its renders are priced from the studio’s own quote of the takes plus 30%, plus 76 credits to write the prompts for it, in place of the Basic clip price, so quote with `?check=true` first. Premium makes one version at a time, has no draft/final (it is already full quality) and its retakes cost the part price it was sold at. The job shows `videoModel` and `videoModelName`."},"resolution":{"description":"Premium only: `480p` or `720p` (about twice the cost). Leave it out for Pixio’s default; for more, `upscale`."},"verbatim":{"description":"Boolean (default false). Your prompts are used exactly as sent: no rewrite or added lines (the prompt check may still refuse, never edit). Not with an `idea`, remakes or episodes. On Premium and Ultra it also skips the prompt-writing charge."},"duration":{"description":"Required. Film length in seconds, 30–420, a multiple of 15 (one clip per 15 s)."},"clips":{"description":"Your own clip prompts as a JSON list, one per 15 s clip, instead of an `idea`."},"idea":{"description":"What the piece is about, up to 4000 characters (counted as sent). With an idea the AI writes it (a writer round is charged)."},"references":{"description":"What each of your `images` shows, in order, as a JSON list of strings."},"style":{"description":"A look in words for the whole piece, up to 500 characters."},"realism":{"description":"Number from 0 to 1: how photographic the result is (natural, matte skin). Montage Basic only. Reference clips default to 0 (off); a series episode defaults to the show’s realism; send 0 for animation."},"seed":{"description":"Integer seed, to repeat a result."},"finish":{"description":"A finishing pass (grade, grain, loudness) once rendered, as a JSON object of `videos/finish` fields, for example `{\"grade\":\"warm\",\"grain\":0}`. Priced like POST /director/videos/finish."},"upscale":{"description":"Boolean. Upscale to about 1080p when rendered, priced like POST /director/videos/upscale (71 credits per started 15 s)."},"upscale_method":{"description":"Leave unset. Billed at the standard upscale rate (71 credits per started 15 s)."},"aspect":{"description":"Frame shape, for example `16:9`, `9:16` or `1:1`."},"speed":{"description":"`draft` (73 credits a clip) or full quality (115 credits a clip, default). Render a finished draft at full quality later with POST /director/videos/film/{id}/final."},"clip_images":{"description":"Which of your pictures each section or clip uses, as JSON."},"exif_rotate":{"description":"Boolean. Turn uploaded pictures upright by their EXIF orientation."},"strict_prompt":{"description":"Boolean, default true. `false` renders an official-format prompt even when the checker finds errors."},"film_type":{"description":"`commercial` (an ad structure; adds the ad review, 76 credits), `explainer` (narrated vertical explainer), `documentary` (chapters, interviews, narrator, score) or `short_drama` (a vertical micro-drama episode, 9:16 unless `aspect` is sent: a hook in the first 3 s, one beat per 15 s clip, close-ups and reaction shots, short lines, no on-screen text, a cliffhanger; with `drama_trope` and `cliffhanger`, priced like any written film). Explainers, documentaries and short dramas need an `idea`."},"drama_trope":{"description":"With `film_type: \"short_drama\"`: the story engine — `auto` (default), `revenge`, `hidden_identity`, `rich_poor`, `betrayal`, `second_chance`, `contract_marriage`, `fated_mate` or `secret_baby`."},"cliffhanger":{"description":"Boolean, with `film_type: \"short_drama\"` (default true): end on an unresolved cliffhanger. `false` ends on the payoff, e.g. for a season finale."},"doc_style":{"description":"Documentaries: `dramatic` (default), `observational` or `investigative`."},"interviews":{"description":"Documentaries: `auto`, `few`, `none`, or an exact count 0–6."},"doc_chapters":{"description":"Documentaries: number of chapters, 1–8."},"narration_pace":{"description":"Explainers and documentaries: words a second, 1.5–2.6."},"max_speedup":{"description":"Explainers and documentaries: how much the narrator may be sped up to fit, 1.0–1.3."},"fact_check":{"description":"Documentaries: boolean, default true. A second writer pass checks every factual claim and fixes wrong or overstated ones before the narration is read. 76 credits; send false to skip it."},"interview_label":{"description":"Documentaries: shown after an interviewee’s role on their name card, because interviewees are invented people. Default `dramatized`; send `\"\"` for none. Up to 40 characters."},"storyboard":{"description":"Boolean. With an `idea`: stop after writing, draw one still per shot and wait for POST /director/jobs/{id}/storyboard/approve. Stills are 25 credits each (up to 4 a clip are held, the real count is charged). Not with `variants`."},"ad_style":{"description":"Commercials: `problem_solution`, `product_hero`, `slice_of_life`, `demo`, `cinematic_story`, `comedy`, `sensory`, `montage`, `before_after`, `aspirational`, `reveal`, or `auto` (default: the writer picks)."},"product_pictures":{"description":"Which of your `images` show the product, 1-based, as a JSON list (e.g. `[1]`)."},"variants":{"description":"Versions in all, 1–4. Each extra version is its own job (`versionJobIds`), billed like the first; every version is held up front."},"voices":{"description":"Whose voice each audio sample is, in order, as a JSON list."},"clip_audio_lock":{"description":"Advanced tuning. Leave unset for the default."},"voice_lock":{"description":"Boolean. Each character keeps the voice heard in clip 1 for the whole film (no samples needed; takes about one clip longer)."},"voice_clone":{"description":"How a `voiceover_sample` is cloned: `natural` (default, best match), `fast` or `classic`. Same price."},"fight_flow":{"description":"Shots that read as a fight get Fight Flow automatically (each blow sets up the next). `false` turns it off, `true` forces it."},"fight_motion":{"description":"Advanced tuning. Leave unset for the default."},"fix_prompt":{"description":"`off` (default), `safe` (rule-based, instant) or `ai` (also fixes what the checker still finds). Repairs untrained camera words, grain words and \"no crowd\" lines in your own prompts. `safe` is free; `ai` adds 16 credits."},"visual_qa":{"description":"`local` (4 credits per 15 s part) or `full` (16 credits per 15 s part, adds an AI judge). Findings come back in `qaIssues`; with `<d>` dialogue lines films also get a speech check."},"face_fix":{"description":"`auto`: after rendering, sections whose faces drifted get a face fix as its own job (`faceFixJobId`), billed 59 credits per fixed section. Sections whose drifted shots all show two or more people are skipped and not billed."},"brand_id":{"description":"A brand id from POST /director/brands. Only your own brands work (404 otherwise). Turns on packaging."},"package":{"description":"A JSON object of packaging fields (the same fields as POST /director/videos/package, e.g. `tagline`, `cta`, `formats`, `cutdowns`, `captions`, `score`). Turns on packaging; priced like packaging. Text limits apply inside it (tagline 120, cta 60, legal 300, title_card 160, voiceover_text 1500)."},"inspiration_notes":{"description":"With `inspiration`: what to take from each, as a JSON list in upload order (“the lighting and slow push-ins”, “the chase pacing”) or one text for all."},"cast":{"description":"Optional. One face and one voice per person: a JSON list such as `[{\"name\": \"Mara\", \"pictures\": [1, 2], \"audio\": 1, \"description\": \"the baker\"}, {\"name\": \"Tom\", \"picture\": 3, \"audio\": 2}]` (positions in `images` and `ref_audios`; each picture and voice belongs to one person). The writer, voice lock and the voice check follow it, so every line is spoken in the right voice."},"tier_mix":{"description":"`off` (default), `auto` or `manual`, with Montage Premium or Ultra: some sections (music videos) or clips (films) render on Montage Basic and the rest on Premium, joined in order at their exact lengths. `auto` puts sung or spoken close-ups on Basic (its lip-sync follows your real audio) and wide, action and instrumental parts on Premium; `manual` takes `basic_sections` / `basic_clips`. Basic parts keep the Basic price, Premium parts the Premium price, so a mix costs less than all-Premium."},"basic_clips":{"description":"With `tier_mix: \"manual\"`: the 1-based clips that render on Montage Basic, a JSON list like `[2, 5]`."},"tier_mix_size":{"description":"With `tier_mix`: the one size every part is brought to — `larger` (default), `basic` or `premium`."},"images":{"description":"Reference pictures, numbered in order as <Picture 1>, <Picture 2>… image: multipart file(s), or URL / asset path string(s); up to 30."},"images_urls":{"type":"array","items":{"type":"string"},"maxItems":30},"ref_audios":{"description":"Voice samples of the characters; say whose each is in `voices`. audio: multipart file(s), or URL / asset path string(s); up to 3."},"ref_audios_urls":{"type":"array","items":{"type":"string"},"maxItems":3},"logo":{"description":"Logo image (a PNG with transparency works best). Turns on packaging. image: multipart file(s), or URL / asset path string(s); up to 1."},"logo_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"music_bed":{"description":"A music bed mixed under the film. Turns on packaging. audio: multipart file(s), or URL / asset path string(s); up to 1."},"music_bed_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"voiceover":{"description":"A recorded voiceover. Wins over `voiceover_text`. audio: multipart file(s), or URL / asset path string(s); up to 1."},"voiceover_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"voiceover_sample":{"description":"5–15 s of the narrator speaking, clean: `voiceover_text` (or an explainer’s narration) is read in that voice. audio: multipart file(s), or URL / asset path string(s); up to 1."},"voiceover_sample_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"inspiration":{"description":"With `idea`: 1–3 videos (up to 120 s each) whose camera, lighting, colour, pacing and staging the writer borrows — never their people, faces, logos or exact shots. Each is studied first and priced like `understand/video` (at least 16 each). The videos are not kept. video: multipart file(s), or URL / asset path string(s); up to 3."},"inspiration_urls":{"type":"array","items":{"type":"string"},"maxItems":3}},"additionalProperties":false}}}},"responses":{"200":{"description":"With ?check=true or ?dry_run=true: a free preflight { object: \"director.preflight\", credits.quoted, promptCheck, … }. Nothing is reserved or rendered."},"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/lipfix":{"post":{"summary":"Director: lip fix","description":"Lip fix: makes any 4–14 s window (`start_s`, `end_s`, any start time) of a finished video (`job_id`) or an uploaded `video` again so the lips follow its vocal (or a new `audio` for the window); only the mouths change and the window is spliced back with crossfades. For a Montage Premium music video it works on the version with your original song. Price: the studio's quote of this exact request, plus a 10% margin for overruns, plus 30% (a 10 s window is about 58 credits).\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"start_s":{"description":"Required. Where the window starts, in seconds (any time)."},"end_s":{"description":"Required. Where it ends; the window is 4–14 s."},"source":{"description":"`auto` (default): a Montage Premium music video’s version with your original song when it has one, else the video. `video` or `song` to choose."},"prompt":{"description":"Optional. A prompt of your own; by default one is written that keeps the shot and has the person sing the vocal."},"verbatim":{"description":"Boolean (default false). Your prompts are used exactly as sent: no rewrite or added lines (the prompt check may still refuse, never edit). Not with an `idea`, remakes or episodes. On Premium and Ultra it also skips the prompt-writing charge."},"seed":{"description":"Integer seed, to repeat a result."},"blend_s":{"description":"Crossfade at each seam in seconds (default 0.25)."},"pad_s":{"description":"Context rendered on each side of the window (default 0.5)."},"isolate_vocal":{"description":"Boolean (default true). The music is stripped so the lips follow the voice alone."},"start":{"description":"`none` (default) or `video`: start from the window’s own frames, so even less changes (`start_denoise` 0.3–1.0, default 0.65)."},"start_denoise":{"description":"With `start: \"video\"`: how much is redrawn, 0.3–1.0."},"ref_frames":{"description":"0–4 stills of the window also sent as pictures of the person (default 0)."},"variant":{"description":"`full` (default): the whole video with the window replaced; `window`: just the new window."},"audio_from":{"description":"`auto` (default): a music video’s original song for the window, laid back on the whole result; `song`: the original song; `video`: the video’s own sound."},"steps":{"description":"Sampling steps. More than the default costs more in proportion (never less than the default price)."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"audio":{"description":"Optional. A new sound for the window instead of its own. audio: multipart file(s), or URL / asset path string(s); up to 1."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"start_s":{"description":"Required. Where the window starts, in seconds (any time)."},"end_s":{"description":"Required. Where it ends; the window is 4–14 s."},"source":{"description":"`auto` (default): a Montage Premium music video’s version with your original song when it has one, else the video. `video` or `song` to choose."},"prompt":{"description":"Optional. A prompt of your own; by default one is written that keeps the shot and has the person sing the vocal."},"verbatim":{"description":"Boolean (default false). Your prompts are used exactly as sent: no rewrite or added lines (the prompt check may still refuse, never edit). Not with an `idea`, remakes or episodes. On Premium and Ultra it also skips the prompt-writing charge."},"seed":{"description":"Integer seed, to repeat a result."},"blend_s":{"description":"Crossfade at each seam in seconds (default 0.25)."},"pad_s":{"description":"Context rendered on each side of the window (default 0.5)."},"isolate_vocal":{"description":"Boolean (default true). The music is stripped so the lips follow the voice alone."},"start":{"description":"`none` (default) or `video`: start from the window’s own frames, so even less changes (`start_denoise` 0.3–1.0, default 0.65)."},"start_denoise":{"description":"With `start: \"video\"`: how much is redrawn, 0.3–1.0."},"ref_frames":{"description":"0–4 stills of the window also sent as pictures of the person (default 0)."},"variant":{"description":"`full` (default): the whole video with the window replaced; `window`: just the new window."},"audio_from":{"description":"`auto` (default): a music video’s original song for the window, laid back on the whole result; `song`: the original song; `video`: the video’s own sound."},"steps":{"description":"Sampling steps. More than the default costs more in proportion (never less than the default price)."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"audio":{"description":"Optional. A new sound for the window instead of its own. audio: multipart file(s), or URL / asset path string(s); up to 1."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/relip":{"post":{"summary":"Director: relip","description":"Relip: the lips of a finished video re-done to the original song — made for Montage Premium and Ultra music videos, whose singing can drift off the song. Only the mouth and jaw are replaced, frame by frame, colour-matched and sharpened to the source; every other pixel, the size, frame rate and length stay as they were, under the original song. Send `job_id` (with `source`: video, or song for a Premium music video's original-song version) or a `video` with an optional `audio`. `only_sung` (default true: only where the vocal is heard), `sung_pad_s`, `isolate_vocal`, `soundtrack` (audio or none), `mask_grow`, `feather`, `sharpen`, `color_match`, `offset_s`. Price: the studio's quote of the exact request (about 0.05 dollars a second of video) with a 10% margin and 30%, at least 16 (15 s is about 108); when it runs on the studio's own machine, like finishing (1.46 credits a second, at least 16).\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"source":{"description":"Same meaning as the studio field of this name."},"only_sung":{"description":"Same meaning as the studio field of this name."},"sung_pad_s":{"description":"Same meaning as the studio field of this name."},"isolate_vocal":{"description":"Same meaning as the studio field of this name."},"soundtrack":{"description":"Same meaning as the studio field of this name."},"mask_grow":{"description":"Same meaning as the studio field of this name."},"feather":{"description":"Advanced tuning. Leave unset for the default."},"sharpen":{"description":"Same meaning as the studio field of this name."},"color_match":{"description":"Same meaning as the studio field of this name."},"offset_s":{"description":"Same meaning as the studio field of this name."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"audio":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 1."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"source":{"description":"Same meaning as the studio field of this name."},"only_sung":{"description":"Same meaning as the studio field of this name."},"sung_pad_s":{"description":"Same meaning as the studio field of this name."},"isolate_vocal":{"description":"Same meaning as the studio field of this name."},"soundtrack":{"description":"Same meaning as the studio field of this name."},"mask_grow":{"description":"Same meaning as the studio field of this name."},"feather":{"description":"Advanced tuning. Leave unset for the default."},"sharpen":{"description":"Same meaning as the studio field of this name."},"color_match":{"description":"Same meaning as the studio field of this name."},"offset_s":{"description":"Same meaning as the studio field of this name."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"audio":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 1."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/lipfix/auto":{"post":{"summary":"Director: lip fix auto","description":"Lip fix auto: one call gives back a whole video (`job_id` or an uploaded `video`) with its lip-sync fixed. Its lip-sync is measured frame by frame; every stretch where the mouth is early or late becomes a lip fix of up to 8 s, each fixed window is measured again and made again (up to `tries`, 1–3, default 3) while it is still off, and the best measured try is kept — a fix that measures worse than the original is not used. `max_windows` (1–12, default 12) caps how many windows it fixes; `start_s` / `end_s` limit it to part of the video; `source` as for lip fix. Takes about 10–40 minutes for 30 s. Price: it holds every try it may make (`max_windows` × `tries` × an 8 s lip fix; 12 × 3 on a music video is about 1,600), and is charged only for the tries it renders, each priced as a lip fix of its window, at least 16; the rest is given back.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director video, or send the `video` file."},"source":{"description":"`video` (default): the delivered video; `song`: a Montage Premium music video’s version with your original song; `auto`: that version when there is one."},"start_s":{"description":"Optional. Only fix stretches from here (seconds)."},"end_s":{"description":"Optional. Only fix stretches up to here (seconds)."},"tries":{"description":"Renders per window at most, 1–3 (default 3). It stops early once a window measures in sync."},"max_windows":{"description":"At most this many windows, 1–12 (default 12). Lower it to cap the hold."},"max_window_s":{"description":"Longest fix window, 4–14 s (default 8; long windows fix worse). The hold is priced on it."},"passes":{"description":"After a pass, measure again and fix what is still off with fresh window edges (default 2)."},"tol_ms":{"description":"In sync within this many milliseconds (default 150)."},"min_conf":{"description":"Fix a stretch only at this measuring confidence or more (default 0.5)."},"denoise_ladder":{"description":"How strongly each try redraws the mouth, per try (default `[0.9, 0.8, 1.0]`; lower keeps more of the old mouth)."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director video, or send the `video` file."},"source":{"description":"`video` (default): the delivered video; `song`: a Montage Premium music video’s version with your original song; `auto`: that version when there is one."},"start_s":{"description":"Optional. Only fix stretches from here (seconds)."},"end_s":{"description":"Optional. Only fix stretches up to here (seconds)."},"tries":{"description":"Renders per window at most, 1–3 (default 3). It stops early once a window measures in sync."},"max_windows":{"description":"At most this many windows, 1–12 (default 12). Lower it to cap the hold."},"max_window_s":{"description":"Longest fix window, 4–14 s (default 8; long windows fix worse). The hold is priced on it."},"passes":{"description":"After a pass, measure again and fix what is still off with fresh window edges (default 2)."},"tol_ms":{"description":"In sync within this many milliseconds (default 150)."},"min_conf":{"description":"Fix a stretch only at this measuring confidence or more (default 0.5)."},"denoise_ladder":{"description":"How strongly each try redraws the mouth, per try (default `[0.9, 0.8, 1.0]`; lower keeps more of the old mouth)."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/edit":{"post":{"summary":"Director: Montage Edit","description":"Montage Edit: changes a finished video (`job_id`) or an uploaded `video` from a short text `prompt` (\"make it night with rain\"), with up to 6 reference `images`. With `start_s` and `end_s` only that 1–15 s window changes and is spliced back; without them the whole video (up to 15 s) is edited. `resolution`: `auto` (matches the video), `360p`, `720p`, `1080p` or `4k`. Price: the studio's quote of this exact request, plus a 10% margin for overruns, plus 30%, at least 16 (the studio always works on a 15 s stretch around the window, so any edit at 720p is about 151; 360p about 51, 1080p about 225).\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"prompt":{"description":"Required. What changes, in a few words: “make it night with rain”, “replace the red car with a white horse”."},"start_s":{"description":"Optional. With `end_s`, only this 1–15 s window changes and is spliced back."},"end_s":{"description":"Optional. Where the window ends."},"source":{"description":"`auto` (default): a Montage Premium music video’s version with your original song when it has one, else the video."},"resolution":{"description":"`auto` (default, matches the video), `360p`, `720p`, `1080p` or `4k`. Higher costs more."},"audio":{"description":"`original` (default): the video keeps its sound; `model`: new sound made for the window (e.g. for “add thunder”)."},"job_pictures":{"description":"Boolean. Also send the source job’s own pictures (up to 6 in all)."},"seed":{"description":"Integer seed, to repeat a result."},"keep_rest":{"description":"Boolean (default true). Adds “Keep everything else the same.”"},"single_shot":{"description":"Boolean. Adds “Single continuous shot, no scene cuts.”"},"negatives":{"description":"Plain things to avoid, e.g. “No new people, no text on screen”."},"blend_s":{"description":"Window edits: crossfade at each seam in seconds (default 0.25)."},"pad_s":{"description":"Window edits: context sent on each side (default 0.5)."},"variant":{"description":"`full` (default): the whole video with the window replaced; `window`: just the new window."},"stretch_s":{"description":"Window edits: how much context is sent around the window, at least this long (default 15 s; 0 = just the window). Shorter costs less."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"images":{"description":"Reference pictures, numbered in order as <Picture 1>, <Picture 2>… image: multipart file(s), or URL / asset path string(s); up to 6."},"images_urls":{"type":"array","items":{"type":"string"},"maxItems":6}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"prompt":{"description":"Required. What changes, in a few words: “make it night with rain”, “replace the red car with a white horse”."},"start_s":{"description":"Optional. With `end_s`, only this 1–15 s window changes and is spliced back."},"end_s":{"description":"Optional. Where the window ends."},"source":{"description":"`auto` (default): a Montage Premium music video’s version with your original song when it has one, else the video."},"resolution":{"description":"`auto` (default, matches the video), `360p`, `720p`, `1080p` or `4k`. Higher costs more."},"audio":{"description":"`original` (default): the video keeps its sound; `model`: new sound made for the window (e.g. for “add thunder”)."},"job_pictures":{"description":"Boolean. Also send the source job’s own pictures (up to 6 in all)."},"seed":{"description":"Integer seed, to repeat a result."},"keep_rest":{"description":"Boolean (default true). Adds “Keep everything else the same.”"},"single_shot":{"description":"Boolean. Adds “Single continuous shot, no scene cuts.”"},"negatives":{"description":"Plain things to avoid, e.g. “No new people, no text on screen”."},"blend_s":{"description":"Window edits: crossfade at each seam in seconds (default 0.25)."},"pad_s":{"description":"Window edits: context sent on each side (default 0.5)."},"variant":{"description":"`full` (default): the whole video with the window replaced; `window`: just the new window."},"stretch_s":{"description":"Window edits: how much context is sent around the window, at least this long (default 15 s; 0 = just the window). Shorter costs less."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"images":{"description":"Reference pictures, numbered in order as <Picture 1>, <Picture 2>… image: multipart file(s), or URL / asset path string(s); up to 6."},"images_urls":{"type":"array","items":{"type":"string"},"maxItems":6}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/edit/create":{"post":{"summary":"Director: Montage Create","description":"Montage Create: a new video with its own sound from 1–6 `images` (the people, things and places) and a `prompt` saying what happens. `duration_s` 3–15 (default 10), `aspect_ratio` `16:9` or `9:16`, `resolution` `360p`, `720p` (default), `1080p` or `4k`. Price: the studio's quote, plus a 10% margin for overruns, plus 30%, at least 16 (10 s at 720p is about 100).\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"description":"Required. What happens, naming each picture’s role in words (no <Picture N> tags)."},"duration_s":{"description":"Seconds, 3–15 (default 10)."},"aspect_ratio":{"description":"`16:9` (default) or `9:16`."},"resolution":{"description":"`360p`, `720p` (default), `1080p` or `4k`. Higher costs more."},"seed":{"description":"Integer seed, to repeat a result."},"single_shot":{"description":"Boolean. Adds “Single continuous shot, no scene cuts.”"},"negatives":{"description":"Plain things to avoid."},"images":{"description":"Required. 1–6 pictures: the people, things and places. image: multipart file(s), or URL / asset path string(s); up to 6."},"images_urls":{"type":"array","items":{"type":"string"},"maxItems":6}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/edit/crop":{"post":{"summary":"Director: Montage Crop","description":"Montage Crop: trims a finished video (`job_id`) or an uploaded `video` to a time window (`start_s`, `end_s`) and crops the frame to a box (`x`, `y`, `width`, `height`) or a shape (`aspect_ratio` such as `9:16`, centred on `focus_x` / `focus_y`), optionally scaled (`max_side`), keeping or muting the sound. Frame-exact, done in seconds. Price: like finishing, 1.46 credits a second of the video kept, at least 16 (30 s is 44).\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director video, or send the `video` file."},"source":{"description":"`video` (default): the delivered video; `song`: a Montage Premium music video’s version with your original song; `auto`: that version when there is one."},"start_s":{"description":"Optional. Keep from here (seconds); default the start."},"end_s":{"description":"Optional. Keep up to here (seconds); default the end."},"x":{"description":"Crop box left edge in source pixels. Send `x`, `y`, `width` and `height` together."},"y":{"description":"Crop box top edge in source pixels."},"width":{"description":"Crop box width in source pixels (16–4096)."},"height":{"description":"Crop box height in source pixels (16–4096)."},"aspect_ratio":{"description":"Or crop to a shape instead of a box: the largest `9:16`, `1:1`, `4:5`, `16:9`, `2.39:1`… rectangle around `focus_x` / `focus_y`."},"focus_x":{"description":"With `aspect_ratio`: where the crop centres across the frame (0 left, 0.5 middle, default, 1 right)."},"focus_y":{"description":"With `aspect_ratio`: where the crop centres down the frame (0 top, 0.5 middle, default, 1 bottom)."},"max_side":{"description":"Optional. Scale the result so its longer side is this many pixels (16–4096)."},"audio":{"description":"`keep` (default): the matching slice of the sound; `mute`: no sound."},"audio_fade_s":{"description":"Fade the sound in and out over this long so the cut does not click (default 0.01; 0 = hard cut)."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director video, or send the `video` file."},"source":{"description":"`video` (default): the delivered video; `song`: a Montage Premium music video’s version with your original song; `auto`: that version when there is one."},"start_s":{"description":"Optional. Keep from here (seconds); default the start."},"end_s":{"description":"Optional. Keep up to here (seconds); default the end."},"x":{"description":"Crop box left edge in source pixels. Send `x`, `y`, `width` and `height` together."},"y":{"description":"Crop box top edge in source pixels."},"width":{"description":"Crop box width in source pixels (16–4096)."},"height":{"description":"Crop box height in source pixels (16–4096)."},"aspect_ratio":{"description":"Or crop to a shape instead of a box: the largest `9:16`, `1:1`, `4:5`, `16:9`, `2.39:1`… rectangle around `focus_x` / `focus_y`."},"focus_x":{"description":"With `aspect_ratio`: where the crop centres across the frame (0 left, 0.5 middle, default, 1 right)."},"focus_y":{"description":"With `aspect_ratio`: where the crop centres down the frame (0 top, 0.5 middle, default, 1 bottom)."},"max_side":{"description":"Optional. Scale the result so its longer side is this many pixels (16–4096)."},"audio":{"description":"`keep` (default): the matching slice of the sound; `mute`: no sound."},"audio_fade_s":{"description":"Fade the sound in and out over this long so the cut does not click (default 0.01; 0 = hard cut)."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/edit/analyze":{"post":{"summary":"Director: Montage Analyze","description":"Montage Analyze: a QA report on a finished video (`job_id`) or an uploaded `video`. The job has no video; when it is done its `analysis` holds `overallScore`, `lipsync` stretches (`start_s`, `end_s`, `verdict` such as `in_sync`, `early`, `late`, `mouth_closed_while_singing`, `offset_ms`, `confidence`), visual `issues` (extra person, face drift, warped hands or limbs, on-screen text, flicker, frozen frames, cuts mid-word; with times and severity), `sections` scores and `suggestedFixes`: ready Pixio requests (`endpoint`, `body`) for lip fix, Montage Edit, face fix or a section redo on your job — send one as it is to fix that spot. Nothing is fixed automatically. Price: the studio's quote of this exact request, plus a 10% margin, plus 30%, at least 16 (about 16 for a minute of video, about 57 for five; `checks: [\"lipsync\"]` alone is 16).\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director video, or send the `video` file. With `job_id` the suggested fixes point at this job."},"source":{"description":"`auto` (default): a Montage Premium music video’s version with your original song (what people hear), else the video; `video`: the delivered video."},"start_s":{"description":"Optional. With `end_s`, only this part is checked (times in the report stay in the full video’s seconds)."},"end_s":{"description":"Optional. Where the checked part ends."},"checks":{"description":"Which checks (default all): `lipsync`, `faces`, `artifacts`, `text`, `continuity`, `prompt_match`. A list, or comma-separated in a form. `lipsync` alone is measured frame by frame and costs the minimum."},"prompt":{"description":"What the video should show, for `prompt_match` (default: the job’s own prompts). Sung or spoken lines are removed before checking."},"fps":{"description":"Frames a second the checker sees (default 5; lip-sync needs several). More costs more."},"resolution":{"description":"`high` (default: mouths and hands are visible) or `low` (about a quarter of the price)."},"pictures":{"description":"Boolean (default true). With `job_id`, also compare faces against the job’s own reference pictures."},"min_confidence":{"description":"A bad lip-sync stretch becomes a suggested lip fix only at this confidence or more (default 0.5)."},"max_fixes":{"description":"At most this many suggested fixes (default 6)."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director video, or send the `video` file. With `job_id` the suggested fixes point at this job."},"source":{"description":"`auto` (default): a Montage Premium music video’s version with your original song (what people hear), else the video; `video`: the delivered video."},"start_s":{"description":"Optional. With `end_s`, only this part is checked (times in the report stay in the full video’s seconds)."},"end_s":{"description":"Optional. Where the checked part ends."},"checks":{"description":"Which checks (default all): `lipsync`, `faces`, `artifacts`, `text`, `continuity`, `prompt_match`. A list, or comma-separated in a form. `lipsync` alone is measured frame by frame and costs the minimum."},"prompt":{"description":"What the video should show, for `prompt_match` (default: the job’s own prompts). Sung or spoken lines are removed before checking."},"fps":{"description":"Frames a second the checker sees (default 5; lip-sync needs several). More costs more."},"resolution":{"description":"`high` (default: mouths and hands are visible) or `low` (about a quarter of the price)."},"pictures":{"description":"Boolean (default true). With `job_id`, also compare faces against the job’s own reference pictures."},"min_confidence":{"description":"A bad lip-sync stretch becomes a suggested lip fix only at this confidence or more (default 0.5)."},"max_fixes":{"description":"At most this many suggested fixes (default 6)."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/graphics":{"post":{"summary":"Director: ad graphics","description":"Ad graphics: animates a timeline of graphics over a finished video (`job_id`) or an uploaded `video` — hooks, price tags, arrows, checklists, buttons, an end card, karaoke captions and an optional music bed — never over a face and clear of each platform's buttons. Same size, frame rate and sound as the source. Send `graphics`, or `auto: true` with a `brief` to have them planned first. Price: like finishing, 1.46 credits a second of video, at least 16 (30 s is 44), plus the studio's quote of any extra work with a 10% margin and 30% (`auto` about 16, `music_prompt` about 26).\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director video, or send the `video` file."},"source":{"description":"`video` (default), `song` (a Montage Premium music video’s version with your original song) or `auto`."},"graphics":{"description":"The timeline: a JSON list of up to 40 elements, each `{type, t, d, …}`. Types: `text` (hook or headline), `image` (a `graphics_images` picture by number, or `\"logo\"`; a picture card with `title` / `price`), `badge` (price tag; `pill` or `burst`), `arrow` (`to_x` / `to_y` and a label), `checklist` (`items` tick in one by one), `button` (call to action, `url` under it) and `end_card` (gradient `colors`, `particles` snow / sparkle, logo, `text`, `cta`, `url`). Common: `t` (seconds, or `beat:N` / `downbeat:N`), `d`, `x`, `y`, `w`, `anchor`, `animation_in` / `animation_out` (pop, fade, slide_left / right / up / down, bounce, none), `animation_s`, `color`, `background`, `font`, `size`; `text` and `arrow` take `effect: \"type\"` and `cps`. Get one from `videos/graphics/plan`, or send `auto: true`."},"auto":{"description":"Boolean. Plan the graphics from the video and the `brief`, then render them, in one call."},"brief":{"description":"With `auto`: what is sold, `{product, price, cta, url, tone, hook, audience, points: […], notes}` or plain text."},"brand_id":{"description":"A saved brand: its colours, font and logo are the defaults."},"snap_to_beat":{"description":"Boolean. Move each element onto the nearest beat (within 0.25 s)."},"avoid_faces":{"description":"Boolean (default true). Never cover a face: an element over one moves to the nearest free spot, else hides for those frames."},"fix_layout":{"description":"Boolean (default true). Overlapping elements move; text too short to read stays up longer."},"safe_area":{"description":"`tiktok`, `reels`, `shorts`, `all` or `none` (default `all` on 9:16), or your own `{left, top, right, bottom}` (fractions of the frame, 0–0.45)."},"lyric_captions":{"description":"Boolean. Word-by-word karaoke captions of the song. The words are only drawn into the picture, never stored or returned."},"lyrics":{"description":"With `lyric_captions`: the song’s own lyrics, timed to the singing. Used for the render only."},"captions":{"description":"Boolean. Word-by-word captions of the speech in the video. Private like `lyric_captions`."},"caption_style":{"description":"`subtitle` (default) or `pop` (short word chunks)."},"caption_words":{"description":"Words per caption chunk, 1–8."},"caption_position":{"description":"`bottom`, `center`, `lower_third`, or 0–1 down the frame."},"caption_font":{"description":"`brand` (the brand’s font) or a listed bold font."},"caption_size":{"description":"Caption text size."},"caption_color":{"description":"Caption text colour."},"caption_stroke_color":{"description":"Caption outline colour."},"caption_stroke_width":{"description":"Caption outline width."},"caption_shadow":{"description":"Caption drop shadow."},"caption_highlight_color":{"description":"Karaoke-style colour for the word being spoken."},"caption_uppercase":{"description":"Boolean. Upper-case captions."},"caption_animation":{"description":"`none`, `pop` or `fade`."},"music_prompt":{"description":"A music bed made for this video (an instrumental at the video’s length); it dips under the voice and comes up on the end card."},"music_job":{"description":"Or one of your finished `music/generate` jobs as the music bed."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"graphics_images":{"description":"Pictures for `image` elements (1, 2, … in the order sent), up to 10. image: multipart file(s), or URL / asset path string(s); up to 10."},"graphics_images_urls":{"type":"array","items":{"type":"string"},"maxItems":10}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director video, or send the `video` file."},"source":{"description":"`video` (default), `song` (a Montage Premium music video’s version with your original song) or `auto`."},"graphics":{"description":"The timeline: a JSON list of up to 40 elements, each `{type, t, d, …}`. Types: `text` (hook or headline), `image` (a `graphics_images` picture by number, or `\"logo\"`; a picture card with `title` / `price`), `badge` (price tag; `pill` or `burst`), `arrow` (`to_x` / `to_y` and a label), `checklist` (`items` tick in one by one), `button` (call to action, `url` under it) and `end_card` (gradient `colors`, `particles` snow / sparkle, logo, `text`, `cta`, `url`). Common: `t` (seconds, or `beat:N` / `downbeat:N`), `d`, `x`, `y`, `w`, `anchor`, `animation_in` / `animation_out` (pop, fade, slide_left / right / up / down, bounce, none), `animation_s`, `color`, `background`, `font`, `size`; `text` and `arrow` take `effect: \"type\"` and `cps`. Get one from `videos/graphics/plan`, or send `auto: true`."},"auto":{"description":"Boolean. Plan the graphics from the video and the `brief`, then render them, in one call."},"brief":{"description":"With `auto`: what is sold, `{product, price, cta, url, tone, hook, audience, points: […], notes}` or plain text."},"brand_id":{"description":"A saved brand: its colours, font and logo are the defaults."},"snap_to_beat":{"description":"Boolean. Move each element onto the nearest beat (within 0.25 s)."},"avoid_faces":{"description":"Boolean (default true). Never cover a face: an element over one moves to the nearest free spot, else hides for those frames."},"fix_layout":{"description":"Boolean (default true). Overlapping elements move; text too short to read stays up longer."},"safe_area":{"description":"`tiktok`, `reels`, `shorts`, `all` or `none` (default `all` on 9:16), or your own `{left, top, right, bottom}` (fractions of the frame, 0–0.45)."},"lyric_captions":{"description":"Boolean. Word-by-word karaoke captions of the song. The words are only drawn into the picture, never stored or returned."},"lyrics":{"description":"With `lyric_captions`: the song’s own lyrics, timed to the singing. Used for the render only."},"captions":{"description":"Boolean. Word-by-word captions of the speech in the video. Private like `lyric_captions`."},"caption_style":{"description":"`subtitle` (default) or `pop` (short word chunks)."},"caption_words":{"description":"Words per caption chunk, 1–8."},"caption_position":{"description":"`bottom`, `center`, `lower_third`, or 0–1 down the frame."},"caption_font":{"description":"`brand` (the brand’s font) or a listed bold font."},"caption_size":{"description":"Caption text size."},"caption_color":{"description":"Caption text colour."},"caption_stroke_color":{"description":"Caption outline colour."},"caption_stroke_width":{"description":"Caption outline width."},"caption_shadow":{"description":"Caption drop shadow."},"caption_highlight_color":{"description":"Karaoke-style colour for the word being spoken."},"caption_uppercase":{"description":"Boolean. Upper-case captions."},"caption_animation":{"description":"`none`, `pop` or `fade`."},"music_prompt":{"description":"A music bed made for this video (an instrumental at the video’s length); it dips under the voice and comes up on the end card."},"music_job":{"description":"Or one of your finished `music/generate` jobs as the music bed."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"graphics_images":{"description":"Pictures for `image` elements (1, 2, … in the order sent), up to 10. image: multipart file(s), or URL / asset path string(s); up to 10."},"graphics_images_urls":{"type":"array","items":{"type":"string"},"maxItems":10}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/graphics/plan":{"post":{"summary":"Director: plan ad graphics","description":"Plans ad graphics for a finished video (`job_id`) or an uploaded `video` and a `brief`: it listens (tempo, beats, loudness, where someone sings) and watches (shots, faces, a likely product) and suggests a ready-to-render list — a hook in the first seconds, elements on beats, nothing over a face, the call to action at the end. Nothing is rendered: the done job's `plan.graphics` goes to `videos/graphics` as it is (edit it first if you like); `plan.video` has what it heard and saw. Price: 16.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director video, or send the `video` file."},"source":{"description":"`video` (default), `song` or `auto`."},"brief":{"description":"What is sold: `{product, price, cta, url, tone, hook, audience, points: […], notes}` or plain text."},"brand_id":{"description":"A saved brand: colours, font and logo."},"lyric_captions":{"description":"Boolean. Leave room for lyric captions."},"captions":{"description":"Boolean. Leave room for speech captions."},"image_count":{"description":"How many `graphics_images` you will send with the render (the plan may use them by number)."},"safe_area":{"description":"As on `videos/graphics`."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director video, or send the `video` file."},"source":{"description":"`video` (default), `song` or `auto`."},"brief":{"description":"What is sold: `{product, price, cta, url, tone, hook, audience, points: […], notes}` or plain text."},"brand_id":{"description":"A saved brand: colours, font and logo."},"lyric_captions":{"description":"Boolean. Leave room for lyric captions."},"captions":{"description":"Boolean. Leave room for speech captions."},"image_count":{"description":"How many `graphics_images` you will send with the render (the plan may use them by number)."},"safe_area":{"description":"As on `videos/graphics`."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/assemble":{"post":{"summary":"Director: assemble a video from clips","description":"Assemble: one video from `clips` in order — each a finished job of yours (`job_id`, `source`) or an uploaded `videos` file (`upload`: its number), with `start_s` / `end_s`, `speed` 0.25–4 or a `ramp` {`from`, `to`}, `transition_in` (cut, crossfade, dip_to_black, dip_to_white, wipe_left, wipe_right) and `transition_s`, `audio` (keep, mute, duck) and `volume_db`. `audio_tracks` add music beds and voiceovers (a song or video job, or an `audio` upload, with offsets, fades and ducking under the clips). `replace` {`job_id`, `shot`, `sound`} swaps one shot of a finished film or music video (numbers from GET /director/jobs/{id}/shots) for the clips and keeps the rest. Output: `width` / `height` or `aspect_ratio` with `fit` (crop, letterbox, blur_fill), `fps`, `loudness_lufs`; frame-exact. Price: like finishing, 1.46 credits a second of the finished video, at least 16 (60 s is 88), from the studio's free dry run of this exact request.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clips":{"description":"Your own clip prompts as a JSON list, one per 15 s clip, instead of an `idea`."},"replace":{"description":"Same meaning as the studio field of this name."},"audio_tracks":{"description":"Same meaning as the studio field of this name."},"width":{"description":"Same meaning as the studio field of this name."},"height":{"description":"Same meaning as the studio field of this name."},"aspect_ratio":{"description":"Same meaning as the studio field of this name."},"fit":{"description":"Same meaning as the studio field of this name."},"fps":{"description":"Same meaning as the studio field of this name."},"fps_resample":{"description":"Same meaning as the studio field of this name."},"loudness_lufs":{"description":"Same meaning as the studio field of this name."},"videos":{"description":"Reference clips. video: multipart file(s), or URL / asset path string(s); up to 20."},"videos_urls":{"type":"array","items":{"type":"string"},"maxItems":20},"audio":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 8."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":8}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"clips":{"description":"Your own clip prompts as a JSON list, one per 15 s clip, instead of an `idea`."},"replace":{"description":"Same meaning as the studio field of this name."},"audio_tracks":{"description":"Same meaning as the studio field of this name."},"width":{"description":"Same meaning as the studio field of this name."},"height":{"description":"Same meaning as the studio field of this name."},"aspect_ratio":{"description":"Same meaning as the studio field of this name."},"fit":{"description":"Same meaning as the studio field of this name."},"fps":{"description":"Same meaning as the studio field of this name."},"fps_resample":{"description":"Same meaning as the studio field of this name."},"loudness_lufs":{"description":"Same meaning as the studio field of this name."},"videos":{"description":"Reference clips. video: multipart file(s), or URL / asset path string(s); up to 20."},"videos_urls":{"type":"array","items":{"type":"string"},"maxItems":20},"audio":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 8."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":8}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/audio/transcribe":{"post":{"summary":"Director: transcribe","description":"Transcribe a finished job's sound (`job_id`, with `source`) or an uploaded `audio` file (mp3, wav, m4a, flac or any video), optionally only `start_s`–`end_s`: the done job's `transcript` has segments and words with times and the language, and `files` the SRT, VTT and text versions. When the voice is mostly singing only the timings come back, never the words, unless `content: \"speech\"`. `language` (ISO code; default detected), `vocabulary` (names to spell right), `isolate_voice`, `cue_max_words`, `cue_max_s`. Price: 16.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"source":{"description":"Same meaning as the studio field of this name."},"start_s":{"description":"Same meaning as the studio field of this name."},"end_s":{"description":"Same meaning as the studio field of this name."},"content":{"description":"Same meaning as the studio field of this name."},"language":{"description":"Same meaning as the studio field of this name."},"vocabulary":{"description":"Same meaning as the studio field of this name."},"isolate_voice":{"description":"Same meaning as the studio field of this name."},"cue_max_words":{"description":"Same meaning as the studio field of this name."},"cue_max_s":{"description":"Same meaning as the studio field of this name."},"chunk_s":{"description":"Same meaning as the studio field of this name."},"hold_semitones":{"description":"Same meaning as the studio field of this name."},"music_bonus":{"description":"Same meaning as the studio field of this name."},"music_threshold_db":{"description":"Same meaning as the studio field of this name."},"no_speech_max":{"description":"Same meaning as the studio field of this name."},"note_min_s":{"description":"Same meaning as the studio field of this name."},"singing_threshold":{"description":"Same meaning as the studio field of this name."},"audio":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 1."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"source":{"description":"Same meaning as the studio field of this name."},"start_s":{"description":"Same meaning as the studio field of this name."},"end_s":{"description":"Same meaning as the studio field of this name."},"content":{"description":"Same meaning as the studio field of this name."},"language":{"description":"Same meaning as the studio field of this name."},"vocabulary":{"description":"Same meaning as the studio field of this name."},"isolate_voice":{"description":"Same meaning as the studio field of this name."},"cue_max_words":{"description":"Same meaning as the studio field of this name."},"cue_max_s":{"description":"Same meaning as the studio field of this name."},"chunk_s":{"description":"Same meaning as the studio field of this name."},"hold_semitones":{"description":"Same meaning as the studio field of this name."},"music_bonus":{"description":"Same meaning as the studio field of this name."},"music_threshold_db":{"description":"Same meaning as the studio field of this name."},"no_speech_max":{"description":"Same meaning as the studio field of this name."},"note_min_s":{"description":"Same meaning as the studio field of this name."},"singing_threshold":{"description":"Same meaning as the studio field of this name."},"audio":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 1."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/audio/stems":{"post":{"summary":"Director: split into stems","description":"Splits a finished job's sound (`job_id`, with `source`) or an uploaded `audio` file (mp3, wav, m4a, flac or any video), optionally only `start_s`–`end_s` into `stems`: 4 (default: vocals, drums, bass, other, plus the accompaniment) or 2 (vocals and accompaniment). The main output is the first stem; every stem is in `files`. `bit_depth` 16, 24 or 32. Price: like finishing, 1.46 credits a second of sound, at least 16 (3 min is 263), from the studio's free dry run of this exact request.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"source":{"description":"Same meaning as the studio field of this name."},"start_s":{"description":"Same meaning as the studio field of this name."},"end_s":{"description":"Same meaning as the studio field of this name."},"stems":{"description":"Same meaning as the studio field of this name."},"bit_depth":{"description":"Same meaning as the studio field of this name."},"shifts":{"description":"Same meaning as the studio field of this name."},"overlap":{"description":"Same meaning as the studio field of this name."},"audio":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 1."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"source":{"description":"Same meaning as the studio field of this name."},"start_s":{"description":"Same meaning as the studio field of this name."},"end_s":{"description":"Same meaning as the studio field of this name."},"stems":{"description":"Same meaning as the studio field of this name."},"bit_depth":{"description":"Same meaning as the studio field of this name."},"shifts":{"description":"Same meaning as the studio field of this name."},"overlap":{"description":"Same meaning as the studio field of this name."},"audio":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 1."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/audio/clean":{"post":{"summary":"Director: clean audio","description":"Cleans a finished job's sound (`job_id`, with `source`) or an uploaded `audio` file (mp3, wav, m4a, flac or any video), optionally only `start_s`–`end_s`: noise reduction (`strength` 0–1), hum (`dehum` auto, off, 50 or 60), echo (`dereverb`), rumble (`highpass_hz`), breaths (`keep_breaths`), optional `lufs`. `output`: auto (the cleaned sound, and the video with it when the source is a video; in `files`), audio or video. Price: like finishing, 1.46 credits a second of sound, at least 16, from the studio's free dry run of this exact request.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"source":{"description":"Same meaning as the studio field of this name."},"start_s":{"description":"Same meaning as the studio field of this name."},"end_s":{"description":"Same meaning as the studio field of this name."},"strength":{"description":"How strongly faces are re-rendered."},"keep_breaths":{"description":"Same meaning as the studio field of this name."},"dehum":{"description":"Same meaning as the studio field of this name."},"dereverb":{"description":"Same meaning as the studio field of this name."},"highpass_hz":{"description":"Same meaning as the studio field of this name."},"lufs":{"description":"Target loudness in LUFS."},"output":{"description":"Same meaning as the studio field of this name."},"breath_keep_db":{"description":"Same meaning as the studio field of this name."},"breath_reduction_db":{"description":"Same meaning as the studio field of this name."},"hum_detect_db":{"description":"Same meaning as the studio field of this name."},"hum_harmonics":{"description":"Same meaning as the studio field of this name."},"hum_q":{"description":"Same meaning as the studio field of this name."},"max_reduction_db":{"description":"Same meaning as the studio field of this name."},"noise_percentile":{"description":"Same meaning as the studio field of this name."},"reverb_time_s":{"description":"Same meaning as the studio field of this name."},"smoothing_ms":{"description":"Same meaning as the studio field of this name."},"audio":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 1."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"source":{"description":"Same meaning as the studio field of this name."},"start_s":{"description":"Same meaning as the studio field of this name."},"end_s":{"description":"Same meaning as the studio field of this name."},"strength":{"description":"How strongly faces are re-rendered."},"keep_breaths":{"description":"Same meaning as the studio field of this name."},"dehum":{"description":"Same meaning as the studio field of this name."},"dereverb":{"description":"Same meaning as the studio field of this name."},"highpass_hz":{"description":"Same meaning as the studio field of this name."},"lufs":{"description":"Target loudness in LUFS."},"output":{"description":"Same meaning as the studio field of this name."},"breath_keep_db":{"description":"Same meaning as the studio field of this name."},"breath_reduction_db":{"description":"Same meaning as the studio field of this name."},"hum_detect_db":{"description":"Same meaning as the studio field of this name."},"hum_harmonics":{"description":"Same meaning as the studio field of this name."},"hum_q":{"description":"Same meaning as the studio field of this name."},"max_reduction_db":{"description":"Same meaning as the studio field of this name."},"noise_percentile":{"description":"Same meaning as the studio field of this name."},"reverb_time_s":{"description":"Same meaning as the studio field of this name."},"smoothing_ms":{"description":"Same meaning as the studio field of this name."},"audio":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 1."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/audio/master":{"post":{"summary":"Director: master audio","description":"Mixes 1–16 `tracks` (each a finished job of yours or an uploaded `audio` file, `file`: its number) with `offset_s`, `volume_db`, `duck_under`, `duck_db`, `fade_in_s`, `fade_out_s`, to a finished loudness (`lufs`, default -14; `true_peak_db`), optional `length_s`; `format` wav, flac or m4a; `video_from` also puts the mix on track N's video. Price: like finishing, 1.46 credits a second of the mix, at least 16, from the studio's free dry run of this exact request.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tracks":{"description":"Same meaning as the studio field of this name."},"lufs":{"description":"Target loudness in LUFS."},"true_peak_db":{"description":"Same meaning as the studio field of this name."},"length_s":{"description":"Same meaning as the studio field of this name."},"format":{"description":"Audio file format of the song."},"video_from":{"description":"Same meaning as the studio field of this name."},"audio":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 16."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":16}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"tracks":{"description":"Same meaning as the studio field of this name."},"lufs":{"description":"Target loudness in LUFS."},"true_peak_db":{"description":"Same meaning as the studio field of this name."},"length_s":{"description":"Same meaning as the studio field of this name."},"format":{"description":"Audio file format of the song."},"video_from":{"description":"Same meaning as the studio field of this name."},"audio":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 16."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":16}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/audio/voiceover":{"post":{"summary":"Director: voiceover","description":"Reads `text` (up to 5000 characters) in a preset `voice` (GET /director/voiceover/voices) or a clone of a 5–15 s `voice_sample` (or `voice_sample_job`, with `voice_sample_start_s` / `_end_s`). `speed`, `pause_s`, `lufs`, `format`. Price: like finishing, 1.46 credits a second of reading (15 characters a second), at least 16.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"description":"Same meaning as the studio field of this name."},"voice":{"description":"The brand’s tone of voice, for the writer."},"voice_sample_job":{"description":"Same meaning as the studio field of this name."},"voice_sample_start_s":{"description":"Same meaning as the studio field of this name."},"voice_sample_end_s":{"description":"Same meaning as the studio field of this name."},"speed":{"description":"`draft` renders cheaper and faster for a first look; leave unset for full quality."},"pause_s":{"description":"Same meaning as the studio field of this name."},"lufs":{"description":"Target loudness in LUFS."},"format":{"description":"Audio file format of the song."},"chunk_chars":{"description":"Same meaning as the studio field of this name."},"pad_s":{"description":"Same meaning as the studio field of this name."},"true_peak_db":{"description":"Same meaning as the studio field of this name."},"voice_sample":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 1."},"voice_sample_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"text":{"description":"Same meaning as the studio field of this name."},"voice":{"description":"The brand’s tone of voice, for the writer."},"voice_sample_job":{"description":"Same meaning as the studio field of this name."},"voice_sample_start_s":{"description":"Same meaning as the studio field of this name."},"voice_sample_end_s":{"description":"Same meaning as the studio field of this name."},"speed":{"description":"`draft` renders cheaper and faster for a first look; leave unset for full quality."},"pause_s":{"description":"Same meaning as the studio field of this name."},"lufs":{"description":"Target loudness in LUFS."},"format":{"description":"Audio file format of the song."},"chunk_chars":{"description":"Same meaning as the studio field of this name."},"pad_s":{"description":"Same meaning as the studio field of this name."},"true_peak_db":{"description":"Same meaning as the studio field of this name."},"voice_sample":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 1."},"voice_sample_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/audio/dub":{"post":{"summary":"Director: dub audio","description":"Dubs a finished job's sound (`job_id`, with `source`) or an uploaded `audio` file (mp3, wav, m4a, flac or any video), optionally only `start_s`–`end_s` into `language`: the speech is separated, translated and read again in each speaker's cloned voice over the original music and ambience (`voice_db`, `background_db`). Mostly sung sound is refused unless `content: \"speech\"`. `output`: auto (the dubbed sound, and the dubbed video when the source is a video; in `files`) or audio. The lips do not match. Price: like finishing, 1.46 credits a second of sound, at least 16 (30 s is 44), from the studio's free dry run of this exact request.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"source":{"description":"Same meaning as the studio field of this name."},"start_s":{"description":"Same meaning as the studio field of this name."},"end_s":{"description":"Same meaning as the studio field of this name."},"language":{"description":"Same meaning as the studio field of this name."},"content":{"description":"Same meaning as the studio field of this name."},"voice_db":{"description":"Same meaning as the studio field of this name."},"background_db":{"description":"Same meaning as the studio field of this name."},"output":{"description":"Same meaning as the studio field of this name."},"true_peak_db":{"description":"Same meaning as the studio field of this name."},"audio":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 1."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"source":{"description":"Same meaning as the studio field of this name."},"start_s":{"description":"Same meaning as the studio field of this name."},"end_s":{"description":"Same meaning as the studio field of this name."},"language":{"description":"Same meaning as the studio field of this name."},"content":{"description":"Same meaning as the studio field of this name."},"voice_db":{"description":"Same meaning as the studio field of this name."},"background_db":{"description":"Same meaning as the studio field of this name."},"output":{"description":"Same meaning as the studio field of this name."},"true_peak_db":{"description":"Same meaning as the studio field of this name."},"audio":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 1."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/audio/sfx":{"post":{"summary":"Director: sound effects","description":"Sound effects from a `description` (\"glass shatter\", \"door creak\", \"rain on a tin roof\"…). `engine`: `auto` (default: a sound model makes it, up to 30 s) or `library` (the best matches from the sound library, up to 60 s); `model` always uses the model. `count` takes (default 3, seed, seed+1…) — the main output is the first, every one is in `files`. `duration_s` (default 5 s), `steps`, `cfg` (how closely it follows the description), `negative_prompt` (what to keep out), `fade_in_s`, `fade_out_s`, `lufs`, `seed`, `format`. Price: library 16; made by the model 0.2 credits a second of sound made (count × duration), at least 16 (3 × 5 s is 16, 8 × 30 s is 48).\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"description":"What the brand or product is, for the writer."},"engine":{"description":"Same meaning as the studio field of this name."},"duration_s":{"description":"Same meaning as the studio field of this name."},"count":{"description":"Same meaning as the studio field of this name."},"steps":{"description":"Sampling steps. More than the default costs more in proportion (never less than the default price)."},"cfg":{"description":"Same meaning as the studio field of this name."},"negative_prompt":{"description":"Same meaning as the studio field of this name."},"fade_in_s":{"description":"Same meaning as the studio field of this name."},"fade_out_s":{"description":"Same meaning as the studio field of this name."},"lufs":{"description":"Target loudness in LUFS."},"seed":{"description":"Integer seed, to repeat a result."},"format":{"description":"Audio file format of the song."}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"description":{"description":"What the brand or product is, for the writer."},"engine":{"description":"Same meaning as the studio field of this name."},"duration_s":{"description":"Same meaning as the studio field of this name."},"count":{"description":"Same meaning as the studio field of this name."},"steps":{"description":"Sampling steps. More than the default costs more in proportion (never less than the default price)."},"cfg":{"description":"Same meaning as the studio field of this name."},"negative_prompt":{"description":"Same meaning as the studio field of this name."},"fade_in_s":{"description":"Same meaning as the studio field of this name."},"fade_out_s":{"description":"Same meaning as the studio field of this name."},"lufs":{"description":"Target loudness in LUFS."},"seed":{"description":"Integer seed, to repeat a result."},"format":{"description":"Audio file format of the song."}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/audio/foley":{"post":{"summary":"Director: foley","description":"Foley: sound made in sync with a video — a finished Director video (`job_id`) or an uploaded `video` of up to 30 s. Optional `prompt` (what should be heard; the picture leads either way) and `negative_prompt` (e.g. \"music, speech\"). `output`: video (default, the video with the new sound) or audio (wav). `keep_original` (default true: mixed under the video's own sound), `mix_db`, `foley_lufs`, `true_peak_db`, `steps`, `cfg`, `seed` (another take). Price: like finishing, 1.46 credits a second of video, at least 16 (15 s is 22).\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"prompt":{"description":"The shot prompt: up to 8000 characters on Montage Basic, 30,000 with `video_model` `montage-premium` or `montage-ultra` in the body (counted as sent: each line break counts as two). Plain prompts always render; prompts in the official format are checked first (422 `prompt_check_failed` on errors)."},"negative_prompt":{"description":"Same meaning as the studio field of this name."},"output":{"description":"Same meaning as the studio field of this name."},"keep_original":{"description":"Same meaning as the studio field of this name."},"mix_db":{"description":"Same meaning as the studio field of this name."},"foley_lufs":{"description":"Same meaning as the studio field of this name."},"true_peak_db":{"description":"Same meaning as the studio field of this name."},"steps":{"description":"Sampling steps. More than the default costs more in proportion (never less than the default price)."},"cfg":{"description":"Same meaning as the studio field of this name."},"seed":{"description":"Integer seed, to repeat a result."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"prompt":{"description":"The shot prompt: up to 8000 characters on Montage Basic, 30,000 with `video_model` `montage-premium` or `montage-ultra` in the body (counted as sent: each line break counts as two). Plain prompts always render; prompts in the official format are checked first (422 `prompt_check_failed` on errors)."},"negative_prompt":{"description":"Same meaning as the studio field of this name."},"output":{"description":"Same meaning as the studio field of this name."},"keep_original":{"description":"Same meaning as the studio field of this name."},"mix_db":{"description":"Same meaning as the studio field of this name."},"foley_lufs":{"description":"Same meaning as the studio field of this name."},"true_peak_db":{"description":"Same meaning as the studio field of this name."},"steps":{"description":"Sampling steps. More than the default costs more in proportion (never less than the default price)."},"cfg":{"description":"Same meaning as the studio field of this name."},"seed":{"description":"Integer seed, to repeat a result."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/understand/video":{"post":{"summary":"Director: understand a video","description":"Understand a video: a structured read of a finished job (`job_id`) or an uploaded `video`. The job makes no video; when it is done its `understanding` has a summary, genre, purpose and mood, the visual style (look, camera, lighting, colour palette, pacing, composition), scenes with times (setting, action, shot size, camera move, lighting), people (described, never identified), products, on-screen text (kind and place only), the sound (genre, mood, instruments, structure with energy, voices, effects, mix), how picture and sound fit, the story’s hook and beats, quality, style sentences and tips to make something like it, and measurements (every shot, cuts per minute, tempo, loudness, where voices sing or speak). Sung or spoken words and on-screen text are never returned. `question` gets an `answer`. Price: the studio's quote, plus a 10% margin, plus 30%, at least 16 (up to a few minutes is 16; 5 minutes about 49).\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job, or send the file."},"source":{"description":"`video` (default): the delivered video; `song`: a Montage Premium music video’s version with your original song; `auto`: that version when there is one."},"start_s":{"description":"Optional. With `end_s`, only this part (times in the answer stay in the full file’s seconds)."},"end_s":{"description":"Optional. Where the part ends."},"question":{"description":"Optional. A question to answer about it (`understanding.answer`). Not kept after the job."},"focus":{"description":"Optional. What to pay special attention to, e.g. “the lighting and camera moves”. Not kept after the job."},"fps":{"description":"Frames a second it watches (default 2). More costs more."},"resolution":{"description":"`high` (default) or `low` (cheaper)."},"max_scenes":{"description":"At most this many scenes (default 40)."},"lipsync":{"description":"Boolean (default true). When it has a voice, measure the lip-sync frame by frame (`measured.lipsync`: stretches with verdict and `offset_ms`). Free."},"vocals":{"description":"Boolean (default true). Find where voices sing or speak."},"measure_only":{"description":"Boolean. Only the measurements (shots, tempo, loudness, voices), no deep read: the minimum price."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job, or send the file."},"source":{"description":"`video` (default): the delivered video; `song`: a Montage Premium music video’s version with your original song; `auto`: that version when there is one."},"start_s":{"description":"Optional. With `end_s`, only this part (times in the answer stay in the full file’s seconds)."},"end_s":{"description":"Optional. Where the part ends."},"question":{"description":"Optional. A question to answer about it (`understanding.answer`). Not kept after the job."},"focus":{"description":"Optional. What to pay special attention to, e.g. “the lighting and camera moves”. Not kept after the job."},"fps":{"description":"Frames a second it watches (default 2). More costs more."},"resolution":{"description":"`high` (default) or `low` (cheaper)."},"max_scenes":{"description":"At most this many scenes (default 40)."},"lipsync":{"description":"Boolean (default true). When it has a voice, measure the lip-sync frame by frame (`measured.lipsync`: stretches with verdict and `offset_ms`). Free."},"vocals":{"description":"Boolean (default true). Find where voices sing or speak."},"measure_only":{"description":"Boolean. Only the measurements (shots, tempo, loudness, voices), no deep read: the minimum price."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/understand/audio":{"post":{"summary":"Director: understand a sound","description":"Understand a sound: a structured read of a song, voice-over or soundtrack — a finished job (`job_id`) or an uploaded `audio`. The job's `understanding` has what it is, genre, mood, instruments, tempo feel, the energy arc, the parts in order with times and energy, every voice (kind, tone, when; never the words), sound effects, mix notes, what it would suit, and measurements (tempo and beat length, loudness per second, drops, where voices are). `question` gets an `answer`. Price: the studio's quote, plus a 10% margin, plus 30%, at least 16 (a 3-minute song about 19).\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job, or send the file."},"source":{"description":"`video` (default): the delivered video; `song`: a Montage Premium music video’s version with your original song; `auto`: that version when there is one."},"start_s":{"description":"Optional. With `end_s`, only this part (times in the answer stay in the full file’s seconds)."},"end_s":{"description":"Optional. Where the part ends."},"question":{"description":"Optional. A question to answer about it (`understanding.answer`). Not kept after the job."},"focus":{"description":"Optional. What to pay special attention to, e.g. “the lighting and camera moves”. Not kept after the job."},"vocals":{"description":"Boolean (default true). Find where voices sing or speak."},"measure_only":{"description":"Boolean. Only the measurements (shots, tempo, loudness, voices), no deep read: the minimum price."},"audio":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 1."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job, or send the file."},"source":{"description":"`video` (default): the delivered video; `song`: a Montage Premium music video’s version with your original song; `auto`: that version when there is one."},"start_s":{"description":"Optional. With `end_s`, only this part (times in the answer stay in the full file’s seconds)."},"end_s":{"description":"Optional. Where the part ends."},"question":{"description":"Optional. A question to answer about it (`understanding.answer`). Not kept after the job."},"focus":{"description":"Optional. What to pay special attention to, e.g. “the lighting and camera moves”. Not kept after the job."},"vocals":{"description":"Boolean (default true). Find where voices sing or speak."},"measure_only":{"description":"Boolean. Only the measurements (shots, tempo, loudness, voices), no deep read: the minimum price."},"audio":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 1."},"audio_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/resync":{"post":{"summary":"Director: re-time a music video onto its song","description":"Re-times a music `video` (mp4) onto its `song`, section by section (`section_s`, default 15), and lays the song on unchanged: lips and cuts land on the song again. Price: like `videos/finish` on the video's length (1.46 credits a second, at least 16).\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"section_s":{"description":"Re-sync: the section length in seconds the picture is re-timed by (default 15)."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"song":{"description":"The song. Its length sets the number of 15 s sections and the price. audio: multipart file(s), or URL / asset path string(s); up to 1."},"song_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/remake":{"post":{"summary":"Director: remake a video shot for shot","description":"Remakes a `video` (2 s to 7 min) shot for shot as a new film: its speech is transcribed, the AI watches every shot (framing, camera, people, action, place, light, dialogue) and writes it again — clip k is the source's 15 s window k, the same shots at the same cut times — with your `changes` and up to 9 `images` (<Picture 1>…). The film is the source's length rounded up to 15 s (30 s at least). Everything a film takes after writing works: `storyboard`, `speed`, `upscale`, `visual_qa`, `package`. Price: clips x 115 (`speed: \"draft\"`: x 73); plus 151 per writer round (1 round up to 8 clips, otherwise 1 + clips/4 rounded up) and 16 per clip for watching the source; plus 25 for each picture the studio designs (up to 9 held, the real count charged); plus upscale, `visual_qa`, packaging and storyboard stills when asked. A 1-minute remake holds 900 credits. Retake a clip or render the final of a draft with POST /director/videos/film/{id}/redo and …/final. `?dry_run=true` is a free quote.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"parameters":[{"name":"dry_run","in":"query","description":"true: return what would be sent, the report and the quote instead of starting (free).","schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"video_model":{"description":"`montage-basic` (Montage Basic), `montage-premium` (Montage Premium) or `montage-ultra` (Montage Ultra); every value with its name and whether it is offered right now is in GET /director/catalog under `videoModels.models`. Left out, it is always `montage-basic`. Montage Premium is sharper and more lifelike; Montage Ultra uses the highest-quality model on every shot and costs more. Both are offered when Pixio turns them on (`videoModels.premiumAvailable` in GET /director/catalog; `premium_unavailable` otherwise); its renders are priced from the studio’s own quote of the takes plus 30%, plus 76 credits to write the prompts for it, in place of the Basic clip price, so quote with `?check=true` first. Premium makes one version at a time, has no draft/final (it is already full quality) and its retakes cost the part price it was sold at. The job shows `videoModel` and `videoModelName`."},"resolution":{"description":"Premium only: `480p` or `720p` (about twice the cost). Leave it out for Pixio’s default; for more, `upscale`."},"verbatim":{"description":"Boolean (default false). Your prompts are used exactly as sent: no rewrite or added lines (the prompt check may still refuse, never edit). Not with an `idea`, remakes or episodes. On Premium and Ultra it also skips the prompt-writing charge."},"changes":{"description":"Remakes: what to change, in plain words, up to 4000 characters — \"the man is <Picture 1>\", \"set it in Tokyo at night\", \"make it 3D animation\". Empty remakes it as it is, sharper."},"references":{"description":"What each of your `images` shows, in order, as a JSON list of strings."},"motion":{"description":"Remakes: `loose` (default) follows the AI's shot list — the same shots, framing, camera moves and cut times; `medium` also shows each clip its own 15 s of the source to copy camera moves and timing more closely."},"sound":{"description":"Remakes: `original` (default) keeps the source's sound exactly, speech in sync; `new` makes new sound and speech."},"storyboard":{"description":"Boolean. With an `idea`: stop after writing, draw one still per shot and wait for POST /director/jobs/{id}/storyboard/approve. Stills are 25 credits each (up to 4 a clip are held, the real count is charged). Not with `variants`."},"realism":{"description":"Number from 0 to 1: how photographic the result is (natural, matte skin). Montage Basic only. Reference clips default to 0 (off); a series episode defaults to the show’s realism; send 0 for animation."},"seed":{"description":"Integer seed, to repeat a result."},"speed":{"description":"`draft` renders cheaper and faster for a first look; leave unset for full quality."},"aspect":{"description":"Frame shape, for example `16:9`, `9:16` or `1:1`."},"upscale":{"description":"Boolean. Upscale to about 1080p when rendered, priced like POST /director/videos/upscale (71 credits per started 15 s)."},"visual_qa":{"description":"`local` (4 credits per 15 s part) or `full` (16 credits per 15 s part, adds an AI judge). Findings come back in `qaIssues`; with `<d>` dialogue lines films also get a speech check."},"package":{"description":"A JSON object of packaging fields (the same fields as POST /director/videos/package, e.g. `tagline`, `cta`, `formats`, `cutdowns`, `captions`, `score`). Turns on packaging; priced like packaging. Text limits apply inside it (tagline 120, cta 60, legal 300, title_card 160, voiceover_text 1500)."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"images":{"description":"Reference pictures, numbered in order as <Picture 1>, <Picture 2>… image: multipart file(s), or URL / asset path string(s); up to 9."},"images_urls":{"type":"array","items":{"type":"string"},"maxItems":9}},"additionalProperties":false}}}},"responses":{"200":{"description":"With ?check=true or ?dry_run=true: a free preflight { object: \"director.preflight\", credits.quoted, promptCheck, … }. Nothing is reserved or rendered."},"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/series/{id}/episodes":{"post":{"summary":"Director: make a TV series episode","description":"One episode of one of your saved series: a film the AI writes from the series, its cast and a recap of the earlier episodes, with the series' title card and theme. Send an `idea` (what happens), or leave it out for an episode planned with POST /director/series/{id}/season. Price: an AI-written film of `duration` (with up to 9 designed pictures held, 25 each made) + 76 for the recap + packaging (and the series' laugh track or a `package.score` if set). A 60 s episode holds 1000 credits; a show whose cast already has pictures is usually charged 775. `?dry_run=true` is free. When it is done its recap is saved (GET /director/series/{id}/episodes).\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"dry_run","in":"query","description":"true: return what would be sent, the report and the quote instead of starting (free).","schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"video_model":{"description":"`montage-basic` (Montage Basic), `montage-premium` (Montage Premium) or `montage-ultra` (Montage Ultra); every value with its name and whether it is offered right now is in GET /director/catalog under `videoModels.models`. Left out, it is always `montage-basic`. Montage Premium is sharper and more lifelike; Montage Ultra uses the highest-quality model on every shot and costs more. Both are offered when Pixio turns them on (`videoModels.premiumAvailable` in GET /director/catalog; `premium_unavailable` otherwise); its renders are priced from the studio’s own quote of the takes plus 30%, plus 76 credits to write the prompts for it, in place of the Basic clip price, so quote with `?check=true` first. Premium makes one version at a time, has no draft/final (it is already full quality) and its retakes cost the part price it was sold at. The job shows `videoModel` and `videoModelName`."},"resolution":{"description":"Premium only: `480p` or `720p` (about twice the cost). Leave it out for Pixio’s default; for more, `upscale`."},"verbatim":{"description":"Boolean (default false). Your prompts are used exactly as sent: no rewrite or added lines (the prompt check may still refuse, never edit). Not with an `idea`, remakes or episodes. On Premium and Ultra it also skips the prompt-writing charge."},"idea":{"description":"Required. What happens in this episode, 10–4000 characters. Name the cast members in it: their pictures and voices go first."},"duration":{"description":"Episode length in seconds, 30–420, a multiple of 15 (default 60)."},"number":{"description":"The episode number. Defaults to the next one."},"previously":{"description":"Your own recap of the story so far, up to 3000 characters, instead of the saved recaps."},"film_type":{"description":"`commercial` (an ad structure; adds the ad review, 76 credits), `explainer` (narrated vertical explainer), `documentary` (chapters, interviews, narrator, score) or `short_drama` (a vertical micro-drama episode, 9:16 unless `aspect` is sent: a hook in the first 3 s, one beat per 15 s clip, close-ups and reaction shots, short lines, no on-screen text, a cliffhanger; with `drama_trope` and `cliffhanger`, priced like any written film). Explainers, documentaries and short dramas need an `idea`."},"drama_trope":{"description":"With `film_type: \"short_drama\"`: the story engine — `auto` (default), `revenge`, `hidden_identity`, `rich_poor`, `betrayal`, `second_chance`, `contract_marriage`, `fated_mate` or `secret_baby`."},"cliffhanger":{"description":"Boolean, with `film_type: \"short_drama\"` (default true): end on an unresolved cliffhanger. `false` ends on the payoff, e.g. for a season finale."},"speed":{"description":"`draft` renders cheaper and faster for a first look; leave unset for full quality."},"seed":{"description":"Integer seed, to repeat a result."},"voice_lock":{"description":"`auto` (default: on only when someone in it has no voice yet), `true` or `false`."},"visual_qa":{"description":"`local` (4 credits per 15 s part) or `full` (16 credits per 15 s part, adds an AI judge). Findings come back in `qaIssues`; with `<d>` dialogue lines films also get a speech check."},"face_fix":{"description":"`auto`: after rendering, sections whose faces drifted get a face fix as its own job (`faceFixJobId`), billed 59 credits per fixed section. Sections whose drifted shots all show two or more people are skipped and not billed."},"fight_flow":{"description":"Shots that read as a fight get Fight Flow automatically (each blow sets up the next). `false` turns it off, `true` forces it."},"fight_motion":{"description":"Advanced tuning. Leave unset for the default."},"realism":{"description":"Number from 0 to 1: how photographic the result is (natural, matte skin). Montage Basic only. Reference clips default to 0 (off); a series episode defaults to the show’s realism; send 0 for animation."},"package":{"description":"Extra packaging on top of the series’ title card and theme, as a JSON object of packaging fields."}},"additionalProperties":false}}}},"responses":{"200":{"description":"With ?check=true or ?dry_run=true: a free preflight { object: \"director.preflight\", credits.quoted, promptCheck, … }. Nothing is reserved or rendered."},"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"summary":"Director: a series' episodes with each one's recap, open threads, lasting changes and jobId (free)","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"{ object: \"list\", series, data: [{ object: \"director.episode\", number, title, idea, recap, threads, changes, learned, status, jobId }] }"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. The series’ episodes with each one’s title, idea, recap, open threads, lasting changes, what the show learned, status and `jobId` (the episode’s Director job in this API)."}},"/director/videos/film/{id}/redo":{"post":{"summary":"Director: re-shoot a film clip","description":"Re-shoots one `clip` of a finished film (or episode) as a new job. Price: one clip at the source film's speed (115, or 73 for a draft).\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clip":{"description":"Required. The clip to re-shoot, 1-based."},"seed":{"description":"A new seed for that clip."},"prompt":{"description":"A new prompt for that clip, up to 8000 characters."},"clip_images":{"description":"Which of your pictures each section or clip uses, as JSON."},"audios":{"description":"This clip’s voice samples, in order: a JSON list of 0–3 numbers of the film’s `ref_audios`, e.g. `[2]`."},"no_speech":{"description":"Boolean. Nobody on screen speaks in this clip: no voice samples and closed mouths."},"verbatim":{"description":"Boolean (default false). Your prompts are used exactly as sent: no rewrite or added lines (the prompt check may still refuse, never edit). Not with an `idea`, remakes or episodes. On Premium and Ultra it also skips the prompt-writing charge."},"images":{"description":"Reference pictures, numbered in order as <Picture 1>, <Picture 2>… image: multipart file(s), or URL / asset path string(s); up to 30."},"images_urls":{"type":"array","items":{"type":"string"},"maxItems":30}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"clip":{"description":"Required. The clip to re-shoot, 1-based."},"seed":{"description":"A new seed for that clip."},"prompt":{"description":"A new prompt for that clip, up to 8000 characters."},"clip_images":{"description":"Which of your pictures each section or clip uses, as JSON."},"audios":{"description":"This clip’s voice samples, in order: a JSON list of 0–3 numbers of the film’s `ref_audios`, e.g. `[2]`."},"no_speech":{"description":"Boolean. Nobody on screen speaks in this clip: no voice samples and closed mouths."},"verbatim":{"description":"Boolean (default false). Your prompts are used exactly as sent: no rewrite or added lines (the prompt check may still refuse, never edit). Not with an `idea`, remakes or episodes. On Premium and Ultra it also skips the prompt-writing charge."},"images":{"description":"Reference pictures, numbered in order as <Picture 1>, <Picture 2>… image: multipart file(s), or URL / asset path string(s); up to 30."},"images_urls":{"type":"array","items":{"type":"string"},"maxItems":30}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/music/{id}/final":{"post":{"summary":"Director: render a draft music video at full quality","description":"Renders a finished music video (usually `speed: \"draft\"`) again at full quality as a new job, with the same song, sections, pictures and seeds. Price: every section at 201 (plus upscale, and the draft's packaging and visual QA if it had them). Never the writing or the sets. A 60 s song is 804 credits.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"upscale":{"description":"Boolean. Upscale the final (defaults to what the draft asked for)."},"steps":{"description":"Sampling steps for the final."}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"upscale":{"description":"Boolean. Upscale the final (defaults to what the draft asked for)."},"steps":{"description":"Sampling steps for the final."}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/film/{id}/final":{"post":{"summary":"Director: render a draft film at full quality","description":"Renders a finished film or episode (usually `speed: \"draft\"`) again at full quality as a new job, with the same written clips, pictures and seeds; packaging and finishing carry over. Price: every clip at 115 (plus upscale, and the draft's packaging and visual QA if it had them). Never the writing. A 60 s film is 460 credits.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"upscale":{"description":"Boolean. Upscale the final (defaults to what the draft asked for)."}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"upscale":{"description":"Boolean. Upscale the final (defaults to what the draft asked for)."}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/upscale":{"post":{"summary":"Director: upscale a video to 1080p","description":"Upscales a finished Director job (`job_id`) or an uploaded clip up to 15 s to about 1080p. Price: 71 credits per started 15 s of video (a 30 s video is 142).\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"target_height":{"description":"Output height in pixels, for example `1080`."},"method":{"description":"Leave unset. Billed at the standard upscale rate (71 credits per started 15 s)."},"blend":{"description":"Advanced tuning. Leave unset for the default."},"detail":{"description":"How much added detail is kept, 0–1. 0.6 (default) looks natural on faces; 1.0 is sharper."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"target_height":{"description":"Output height in pixels, for example `1080`."},"method":{"description":"Leave unset. Billed at the standard upscale rate (71 credits per started 15 s)."},"blend":{"description":"Advanced tuning. Leave unset for the default."},"detail":{"description":"How much added detail is kept, 0–1. 0.6 (default) looks natural on faces; 1.0 is sharper."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/finish":{"post":{"summary":"Director: finish a video (grade, grain, loudness)","description":"Grade, grain, loudness and deflicker for a finished job (`job_id`) or an uploaded `video`. Price: video seconds x 1.46, rounded up, at least 16 (a 30 s video is 44).\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"grade":{"description":"Colour grade, for example `neutral`, `warm` or `teal`."},"scope":{"description":"Advanced tuning. Leave unset for the default."},"grain":{"description":"Film grain amount; 0 for none."},"lufs":{"description":"Target loudness in LUFS."},"deflicker":{"description":"Boolean. Remove flicker."},"saturation":{"description":"Colour saturation adjustment."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"grade":{"description":"Colour grade, for example `neutral`, `warm` or `teal`."},"scope":{"description":"Advanced tuning. Leave unset for the default."},"grain":{"description":"Film grain amount; 0 for none."},"lufs":{"description":"Target loudness in LUFS."},"deflicker":{"description":"Boolean. Remove flicker."},"saturation":{"description":"Colour saturation adjustment."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/facefix":{"post":{"summary":"Director: fix small faces in a video","description":"Re-renders small, far-away faces in a finished music video or film (`job_id`): the largest face in each section, or with `people: \"all\"` every person the section names (one pass each). Price held: 59 per section (the `sections` you pick, or every 15 s section); with `people: \"all\"` that times the number of passes, from the studio's own estimate, rounded up to a tenth (a section with two people is about 2x). Charged only for the sections whose likeness visibly changed (`faceFixReport`, a change of 0.05 or more); the rest of the hold goes back.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"sections":{"description":"Which sections to fix, 1-based, as a JSON list. Default: every section."},"strength":{"description":"How strongly faces are re-rendered."},"seed":{"description":"Integer seed, to repeat a result."},"feather":{"description":"Advanced tuning. Leave unset for the default."},"people":{"description":"`largest` (default): one pass on the largest face in each section. `all`: group shots — one pass for every person the section names, each matched to their own picture. Needs `job_id`; priced by the passes it makes."},"face":{"description":"With `people: \"largest\"`: which face to fix, chosen where it first appears and followed from there — `largest` (default), `smallest`, `left`, `right` or `centre`."}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"sections":{"description":"Which sections to fix, 1-based, as a JSON list. Default: every section."},"strength":{"description":"How strongly faces are re-rendered."},"seed":{"description":"Integer seed, to repeat a result."},"feather":{"description":"Advanced tuning. Leave unset for the default."},"people":{"description":"`largest` (default): one pass on the largest face in each section. `all`: group shots — one pass for every person the section names, each matched to their own picture. Needs `job_id`; priced by the passes it makes."},"face":{"description":"With `people: \"largest\"`: which face to fix, chosen where it first appears and followed from there — `largest` (default), `smallest`, `left`, `right` or `centre`."}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/videos/package":{"post":{"summary":"Director: package a video (end card, captions, shapes, cutdowns)","description":"Brands a finished video (`job_id`, or an uploaded `video`): an end card with the logo, tagline and call to action, a corner logo, product packshot, fine print, captions, a music bed or a made `score`, a voiceover (file, typed script or a cloned voice), colour filters and looks, other frame shapes (`formats`) and up to 3 `cutdowns`. The main video keeps its length; the rest come back in `deliverables`. Packaging is priced by the seconds of video it writes: (video seconds + the sum of cutdowns) x (1 + number of extra `formats`) x 1.46, rounded up, at least 16. A `score` adds 36 per started 5 minutes; a `laugh_track` adds 16; a `dub_language` adds 1.46 a second of video (at least 16); a `subtitle_language` adds 16. Filters, looks, captions, fine print, a packshot and a typed voiceover do not change the price. `?dry_run=true` is free.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"parameters":[{"name":"dry_run","in":"query","description":"true: return what would be sent, the report and the quote instead of starting (free).","schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"brand_id":{"description":"A brand id from POST /director/brands. Only your own brands work (404 otherwise). Turns on packaging."},"tagline":{"description":"End-card tagline, up to 120 characters."},"cta":{"description":"End-card call to action, up to 60 characters."},"tagline_size":{"description":"Tagline size as a % of the frame’s short side, 3–20 (default 6.8)."},"cta_size":{"description":"Call-to-action size as a % of the frame’s short side, 2–12 (default 4.5)."},"legal":{"description":"Fine print on the end card, up to 300 characters."},"legal_always":{"description":"Boolean. Show the fine print over the whole video, not only the end card."},"filter":{"description":"A colour filter from GET /director/filters: `sepia`, `black_and_white`, `noir`, `vintage`, `faded`, `warm`, `cool`, `vivid`, `cinematic`, `dreamy`. The logo, captions and end card keep their colours. Same price."},"filter_strength":{"description":"Filter strength, 0–1."},"vignette":{"description":"Vignette strength, 0–1 (0 = none)."},"look_id":{"description":"A look id from POST /director/looks (`look_…`): give the video that reference’s colours. Only your own looks work."},"look_from_job":{"description":"One of your finished Director job ids: copy its look."},"score":{"description":"`auto` or a description: an instrumental of the video’s length is made and mixed under it, dipping under speech. 36 credits per started 5 minutes. An uploaded `music` bed wins."},"laugh_track":{"description":"`light` or `full`: studio-audience laughs after the punchlines (16 credits)."},"laugh_db":{"description":"Laugh track level in dB."},"lower_thirds":{"description":"A JSON list of name cards `{t, text, sub}` or chapter cards `{kind: \"chapter\", label, text, t, d}`."},"title_card":{"description":"An opening title card, up to 160 characters and 3 lines (the first line big)."},"title_card_s":{"description":"Seconds the title card shows, 1–10 (default 4)."},"music_until_s":{"description":"The music bed plays only under the opening for this many seconds, then fades."},"captions":{"description":"`auto` (from the voiceover or the video’s speech), `off`, SRT or WebVTT text, or a JSON list of `{text, start, end}`."},"caption_style":{"description":"`subtitle` (default) or `pop` (short word chunks)."},"caption_words":{"description":"Words per caption chunk, 1–8."},"caption_position":{"description":"`bottom`, `center`, `lower_third`, or 0–1 down the frame."},"caption_font":{"description":"`brand` (the brand’s font) or a listed bold font."},"caption_size":{"description":"Caption text size."},"caption_color":{"description":"Caption text colour."},"caption_stroke_color":{"description":"Caption outline colour."},"caption_stroke_width":{"description":"Caption outline width."},"caption_shadow":{"description":"Caption drop shadow."},"caption_highlight_color":{"description":"Karaoke-style colour for the word being spoken."},"caption_uppercase":{"description":"Boolean. Upper-case captions."},"caption_animation":{"description":"`none`, `pop` or `fade`."},"voiceover_text":{"description":"A typed voiceover script, up to 1500 characters, read by `voiceover_voice` (or by your `voiceover_sample`). An uploaded `voiceover` file wins. Same price."},"voiceover_voice":{"description":"A voice id from GET /director/voiceover/voices (default `af_heart`). Write the script in that voice’s language."},"voice_clone":{"description":"How a `voiceover_sample` is cloned: `natural` (default, best match), `fast` or `classic`. Same price."},"end_card_s":{"description":"Seconds the end card stays on screen."},"end_card_style":{"description":"End-card layout style."},"logo_corner":{"description":"Which corner a corner logo sits in."},"logo_scale":{"description":"Logo size."},"text_color":{"description":"End-card text colour."},"accent_color":{"description":"End-card accent colour."},"background_color":{"description":"End-card background colour."},"keep_original_audio":{"description":"Boolean. Keep the video’s own sound under the new mix."},"original_db":{"description":"Level of the video’s own sound in dB."},"music_db":{"description":"Music bed level in dB."},"voiceover_db":{"description":"Voiceover level in dB."},"duck_db":{"description":"How far the music dips under the voiceover, in dB."},"duck_under_dialogue":{"description":"Boolean. Also dip the music wherever the video’s own characters speak."},"dialogue_duck_db":{"description":"How far the music dips under dialogue, in dB (default -12)."},"voiceover_start_s":{"description":"Seconds into the video the voiceover starts."},"lufs":{"description":"Target loudness in LUFS."},"formats":{"description":"Other frame shapes to deliver as well: any of `9:16`, `1:1`, `4:5` (JSON list or comma-separated). Each is a `deliverables` entry and adds its seconds to the price."},"reframe":{"description":"`crop` (follows faces) or `fit` (blurs the sides) for the other shapes."},"cutdowns":{"description":"Up to 3 shorter lengths in seconds (JSON list or comma-separated), delivered in every shape. A cutdown not at least 1 s shorter than the video is skipped and not charged."},"no_slowmo":{"description":"Boolean. Play accidental slow-motion stretches at real speed (made for fights and action); the video gets shorter."},"no_slowmo_max":{"description":"With `no_slowmo`: the fastest speed-up (default 2)."},"speed_up":{"description":"With `no_slowmo`: also play the whole video this much faster (default 1)."},"dub_language":{"description":"A dub into this language (e.g. `Spanish`): the speech is separated from the music, translated and read again in each speaker’s own cloned voice, over the original music. The lips do not match the new language."},"subtitle_language":{"description":"Subtitles translated into this language (e.g. `Japanese`), line by line with the same times; uses the captions (made automatically if you send none)."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"logo":{"description":"Logo image (a PNG with transparency works best). Turns on packaging. image: multipart file(s), or URL / asset path string(s); up to 1."},"logo_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"packshot":{"description":"The product picture shown on the end card. image: multipart file(s), or URL / asset path string(s); up to 1."},"packshot_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"music":{"description":"A music bed mixed under the video. audio: multipart file(s), or URL / asset path string(s); up to 1."},"music_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"voiceover":{"description":"A recorded voiceover. Wins over `voiceover_text`. audio: multipart file(s), or URL / asset path string(s); up to 1."},"voiceover_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"voiceover_sample":{"description":"5–15 s of the narrator speaking, clean: `voiceover_text` (or an explainer’s narration) is read in that voice. audio: multipart file(s), or URL / asset path string(s); up to 1."},"voiceover_sample_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"font":{"description":"A .ttf or .otf font for the end card. font: multipart file(s), or URL / asset path string(s); up to 1."},"font_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"brand_id":{"description":"A brand id from POST /director/brands. Only your own brands work (404 otherwise). Turns on packaging."},"tagline":{"description":"End-card tagline, up to 120 characters."},"cta":{"description":"End-card call to action, up to 60 characters."},"tagline_size":{"description":"Tagline size as a % of the frame’s short side, 3–20 (default 6.8)."},"cta_size":{"description":"Call-to-action size as a % of the frame’s short side, 2–12 (default 4.5)."},"legal":{"description":"Fine print on the end card, up to 300 characters."},"legal_always":{"description":"Boolean. Show the fine print over the whole video, not only the end card."},"filter":{"description":"A colour filter from GET /director/filters: `sepia`, `black_and_white`, `noir`, `vintage`, `faded`, `warm`, `cool`, `vivid`, `cinematic`, `dreamy`. The logo, captions and end card keep their colours. Same price."},"filter_strength":{"description":"Filter strength, 0–1."},"vignette":{"description":"Vignette strength, 0–1 (0 = none)."},"look_id":{"description":"A look id from POST /director/looks (`look_…`): give the video that reference’s colours. Only your own looks work."},"look_from_job":{"description":"One of your finished Director job ids: copy its look."},"score":{"description":"`auto` or a description: an instrumental of the video’s length is made and mixed under it, dipping under speech. 36 credits per started 5 minutes. An uploaded `music` bed wins."},"laugh_track":{"description":"`light` or `full`: studio-audience laughs after the punchlines (16 credits)."},"laugh_db":{"description":"Laugh track level in dB."},"lower_thirds":{"description":"A JSON list of name cards `{t, text, sub}` or chapter cards `{kind: \"chapter\", label, text, t, d}`."},"title_card":{"description":"An opening title card, up to 160 characters and 3 lines (the first line big)."},"title_card_s":{"description":"Seconds the title card shows, 1–10 (default 4)."},"music_until_s":{"description":"The music bed plays only under the opening for this many seconds, then fades."},"captions":{"description":"`auto` (from the voiceover or the video’s speech), `off`, SRT or WebVTT text, or a JSON list of `{text, start, end}`."},"caption_style":{"description":"`subtitle` (default) or `pop` (short word chunks)."},"caption_words":{"description":"Words per caption chunk, 1–8."},"caption_position":{"description":"`bottom`, `center`, `lower_third`, or 0–1 down the frame."},"caption_font":{"description":"`brand` (the brand’s font) or a listed bold font."},"caption_size":{"description":"Caption text size."},"caption_color":{"description":"Caption text colour."},"caption_stroke_color":{"description":"Caption outline colour."},"caption_stroke_width":{"description":"Caption outline width."},"caption_shadow":{"description":"Caption drop shadow."},"caption_highlight_color":{"description":"Karaoke-style colour for the word being spoken."},"caption_uppercase":{"description":"Boolean. Upper-case captions."},"caption_animation":{"description":"`none`, `pop` or `fade`."},"voiceover_text":{"description":"A typed voiceover script, up to 1500 characters, read by `voiceover_voice` (or by your `voiceover_sample`). An uploaded `voiceover` file wins. Same price."},"voiceover_voice":{"description":"A voice id from GET /director/voiceover/voices (default `af_heart`). Write the script in that voice’s language."},"voice_clone":{"description":"How a `voiceover_sample` is cloned: `natural` (default, best match), `fast` or `classic`. Same price."},"end_card_s":{"description":"Seconds the end card stays on screen."},"end_card_style":{"description":"End-card layout style."},"logo_corner":{"description":"Which corner a corner logo sits in."},"logo_scale":{"description":"Logo size."},"text_color":{"description":"End-card text colour."},"accent_color":{"description":"End-card accent colour."},"background_color":{"description":"End-card background colour."},"keep_original_audio":{"description":"Boolean. Keep the video’s own sound under the new mix."},"original_db":{"description":"Level of the video’s own sound in dB."},"music_db":{"description":"Music bed level in dB."},"voiceover_db":{"description":"Voiceover level in dB."},"duck_db":{"description":"How far the music dips under the voiceover, in dB."},"duck_under_dialogue":{"description":"Boolean. Also dip the music wherever the video’s own characters speak."},"dialogue_duck_db":{"description":"How far the music dips under dialogue, in dB (default -12)."},"voiceover_start_s":{"description":"Seconds into the video the voiceover starts."},"lufs":{"description":"Target loudness in LUFS."},"formats":{"description":"Other frame shapes to deliver as well: any of `9:16`, `1:1`, `4:5` (JSON list or comma-separated). Each is a `deliverables` entry and adds its seconds to the price."},"reframe":{"description":"`crop` (follows faces) or `fit` (blurs the sides) for the other shapes."},"cutdowns":{"description":"Up to 3 shorter lengths in seconds (JSON list or comma-separated), delivered in every shape. A cutdown not at least 1 s shorter than the video is skipped and not charged."},"no_slowmo":{"description":"Boolean. Play accidental slow-motion stretches at real speed (made for fights and action); the video gets shorter."},"no_slowmo_max":{"description":"With `no_slowmo`: the fastest speed-up (default 2)."},"speed_up":{"description":"With `no_slowmo`: also play the whole video this much faster (default 1)."},"dub_language":{"description":"A dub into this language (e.g. `Spanish`): the speech is separated from the music, translated and read again in each speaker’s own cloned voice, over the original music. The lips do not match the new language."},"subtitle_language":{"description":"Subtitles translated into this language (e.g. `Japanese`), line by line with the same times; uses the captions (made automatically if you send none)."},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"logo":{"description":"Logo image (a PNG with transparency works best). Turns on packaging. image: multipart file(s), or URL / asset path string(s); up to 1."},"logo_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"packshot":{"description":"The product picture shown on the end card. image: multipart file(s), or URL / asset path string(s); up to 1."},"packshot_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"music":{"description":"A music bed mixed under the video. audio: multipart file(s), or URL / asset path string(s); up to 1."},"music_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"voiceover":{"description":"A recorded voiceover. Wins over `voiceover_text`. audio: multipart file(s), or URL / asset path string(s); up to 1."},"voiceover_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"voiceover_sample":{"description":"5–15 s of the narrator speaking, clean: `voiceover_text` (or an explainer’s narration) is read in that voice. audio: multipart file(s), or URL / asset path string(s); up to 1."},"voiceover_sample_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"font":{"description":"A .ttf or .otf font for the end card. font: multipart file(s), or URL / asset path string(s); up to 1."},"font_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"200":{"description":"With ?check=true or ?dry_run=true: a free preflight { object: \"director.preflight\", credits.quoted, promptCheck, … }. Nothing is reserved or rendered."},"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/jobs/{id}/edit":{"post":{"summary":"Director: cut a finished video by its shots","description":"Cuts a finished video (any Director job that made a video) by its shots, as listed by GET /director/jobs/{id}/shots: keep, drop, reorder, repeat and trim them (`shots`), with any packaging field (captions, filter, look, score, end card, formats, cutdowns…). The sound is crossfaded at each join; the source is never changed. The result is a new job. Packaging is priced by the seconds of video it writes: (video seconds + the sum of cutdowns) x (1 + number of extra `formats`) x 1.46, rounded up, at least 16. A `score` adds 36 per started 5 minutes; a `laugh_track` adds 16; a `dub_language` adds 1.46 a second of video (at least 16); a `subtitle_language` adds 16. Filters, looks, captions, fine print, a packshot and a typed voiceover do not change the price. The seconds are the edited length. `?dry_run=true` is a free quote.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"dry_run","in":"query","description":"true: return what would be sent, the report and the quote instead of starting (free).","schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shots":{"description":"Required. The shots to keep, in the order they play, as numbered by GET /director/jobs/{id}/shots: `[1, 2, {\"shot\": 4, \"trim_start\": 0.3, \"trim_end\": 0.5}, 3]`. A shot left out is dropped; a shot can be used more than once. `trim_start` / `trim_end` cut seconds off its start or end."},"brand_id":{"description":"A brand id from POST /director/brands. Only your own brands work (404 otherwise). Turns on packaging."},"tagline":{"description":"End-card tagline, up to 120 characters."},"cta":{"description":"End-card call to action, up to 60 characters."},"tagline_size":{"description":"Tagline size as a % of the frame’s short side, 3–20 (default 6.8)."},"cta_size":{"description":"Call-to-action size as a % of the frame’s short side, 2–12 (default 4.5)."},"legal":{"description":"Fine print on the end card, up to 300 characters."},"legal_always":{"description":"Boolean. Show the fine print over the whole video, not only the end card."},"filter":{"description":"A colour filter from GET /director/filters: `sepia`, `black_and_white`, `noir`, `vintage`, `faded`, `warm`, `cool`, `vivid`, `cinematic`, `dreamy`. The logo, captions and end card keep their colours. Same price."},"filter_strength":{"description":"Filter strength, 0–1."},"vignette":{"description":"Vignette strength, 0–1 (0 = none)."},"look_id":{"description":"A look id from POST /director/looks (`look_…`): give the video that reference’s colours. Only your own looks work."},"look_from_job":{"description":"One of your finished Director job ids: copy its look."},"score":{"description":"`auto` or a description: an instrumental of the video’s length is made and mixed under it, dipping under speech. 36 credits per started 5 minutes. An uploaded `music` bed wins."},"laugh_track":{"description":"`light` or `full`: studio-audience laughs after the punchlines (16 credits)."},"laugh_db":{"description":"Laugh track level in dB."},"lower_thirds":{"description":"A JSON list of name cards `{t, text, sub}` or chapter cards `{kind: \"chapter\", label, text, t, d}`."},"title_card":{"description":"An opening title card, up to 160 characters and 3 lines (the first line big)."},"title_card_s":{"description":"Seconds the title card shows, 1–10 (default 4)."},"music_until_s":{"description":"The music bed plays only under the opening for this many seconds, then fades."},"captions":{"description":"`auto` (from the voiceover or the video’s speech), `off`, SRT or WebVTT text, or a JSON list of `{text, start, end}`."},"caption_style":{"description":"`subtitle` (default) or `pop` (short word chunks)."},"caption_words":{"description":"Words per caption chunk, 1–8."},"caption_position":{"description":"`bottom`, `center`, `lower_third`, or 0–1 down the frame."},"caption_font":{"description":"`brand` (the brand’s font) or a listed bold font."},"caption_size":{"description":"Caption text size."},"caption_color":{"description":"Caption text colour."},"caption_stroke_color":{"description":"Caption outline colour."},"caption_stroke_width":{"description":"Caption outline width."},"caption_shadow":{"description":"Caption drop shadow."},"caption_highlight_color":{"description":"Karaoke-style colour for the word being spoken."},"caption_uppercase":{"description":"Boolean. Upper-case captions."},"caption_animation":{"description":"`none`, `pop` or `fade`."},"voiceover_text":{"description":"A typed voiceover script, up to 1500 characters, read by `voiceover_voice` (or by your `voiceover_sample`). An uploaded `voiceover` file wins. Same price."},"voiceover_voice":{"description":"A voice id from GET /director/voiceover/voices (default `af_heart`). Write the script in that voice’s language."},"voice_clone":{"description":"How a `voiceover_sample` is cloned: `natural` (default, best match), `fast` or `classic`. Same price."},"end_card_s":{"description":"Seconds the end card stays on screen."},"end_card_style":{"description":"End-card layout style."},"logo_corner":{"description":"Which corner a corner logo sits in."},"logo_scale":{"description":"Logo size."},"text_color":{"description":"End-card text colour."},"accent_color":{"description":"End-card accent colour."},"background_color":{"description":"End-card background colour."},"keep_original_audio":{"description":"Boolean. Keep the video’s own sound under the new mix."},"original_db":{"description":"Level of the video’s own sound in dB."},"music_db":{"description":"Music bed level in dB."},"voiceover_db":{"description":"Voiceover level in dB."},"duck_db":{"description":"How far the music dips under the voiceover, in dB."},"duck_under_dialogue":{"description":"Boolean. Also dip the music wherever the video’s own characters speak."},"dialogue_duck_db":{"description":"How far the music dips under dialogue, in dB (default -12)."},"voiceover_start_s":{"description":"Seconds into the video the voiceover starts."},"lufs":{"description":"Target loudness in LUFS."},"formats":{"description":"Other frame shapes to deliver as well: any of `9:16`, `1:1`, `4:5` (JSON list or comma-separated). Each is a `deliverables` entry and adds its seconds to the price."},"reframe":{"description":"`crop` (follows faces) or `fit` (blurs the sides) for the other shapes."},"cutdowns":{"description":"Up to 3 shorter lengths in seconds (JSON list or comma-separated), delivered in every shape. A cutdown not at least 1 s shorter than the video is skipped and not charged."},"no_slowmo":{"description":"Boolean. Play accidental slow-motion stretches at real speed (made for fights and action); the video gets shorter."},"no_slowmo_max":{"description":"With `no_slowmo`: the fastest speed-up (default 2)."},"speed_up":{"description":"With `no_slowmo`: also play the whole video this much faster (default 1)."},"dub_language":{"description":"A dub into this language (e.g. `Spanish`): the speech is separated from the music, translated and read again in each speaker’s own cloned voice, over the original music. The lips do not match the new language."},"subtitle_language":{"description":"Subtitles translated into this language (e.g. `Japanese`), line by line with the same times; uses the captions (made automatically if you send none)."}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"shots":{"description":"Required. The shots to keep, in the order they play, as numbered by GET /director/jobs/{id}/shots: `[1, 2, {\"shot\": 4, \"trim_start\": 0.3, \"trim_end\": 0.5}, 3]`. A shot left out is dropped; a shot can be used more than once. `trim_start` / `trim_end` cut seconds off its start or end."},"brand_id":{"description":"A brand id from POST /director/brands. Only your own brands work (404 otherwise). Turns on packaging."},"tagline":{"description":"End-card tagline, up to 120 characters."},"cta":{"description":"End-card call to action, up to 60 characters."},"tagline_size":{"description":"Tagline size as a % of the frame’s short side, 3–20 (default 6.8)."},"cta_size":{"description":"Call-to-action size as a % of the frame’s short side, 2–12 (default 4.5)."},"legal":{"description":"Fine print on the end card, up to 300 characters."},"legal_always":{"description":"Boolean. Show the fine print over the whole video, not only the end card."},"filter":{"description":"A colour filter from GET /director/filters: `sepia`, `black_and_white`, `noir`, `vintage`, `faded`, `warm`, `cool`, `vivid`, `cinematic`, `dreamy`. The logo, captions and end card keep their colours. Same price."},"filter_strength":{"description":"Filter strength, 0–1."},"vignette":{"description":"Vignette strength, 0–1 (0 = none)."},"look_id":{"description":"A look id from POST /director/looks (`look_…`): give the video that reference’s colours. Only your own looks work."},"look_from_job":{"description":"One of your finished Director job ids: copy its look."},"score":{"description":"`auto` or a description: an instrumental of the video’s length is made and mixed under it, dipping under speech. 36 credits per started 5 minutes. An uploaded `music` bed wins."},"laugh_track":{"description":"`light` or `full`: studio-audience laughs after the punchlines (16 credits)."},"laugh_db":{"description":"Laugh track level in dB."},"lower_thirds":{"description":"A JSON list of name cards `{t, text, sub}` or chapter cards `{kind: \"chapter\", label, text, t, d}`."},"title_card":{"description":"An opening title card, up to 160 characters and 3 lines (the first line big)."},"title_card_s":{"description":"Seconds the title card shows, 1–10 (default 4)."},"music_until_s":{"description":"The music bed plays only under the opening for this many seconds, then fades."},"captions":{"description":"`auto` (from the voiceover or the video’s speech), `off`, SRT or WebVTT text, or a JSON list of `{text, start, end}`."},"caption_style":{"description":"`subtitle` (default) or `pop` (short word chunks)."},"caption_words":{"description":"Words per caption chunk, 1–8."},"caption_position":{"description":"`bottom`, `center`, `lower_third`, or 0–1 down the frame."},"caption_font":{"description":"`brand` (the brand’s font) or a listed bold font."},"caption_size":{"description":"Caption text size."},"caption_color":{"description":"Caption text colour."},"caption_stroke_color":{"description":"Caption outline colour."},"caption_stroke_width":{"description":"Caption outline width."},"caption_shadow":{"description":"Caption drop shadow."},"caption_highlight_color":{"description":"Karaoke-style colour for the word being spoken."},"caption_uppercase":{"description":"Boolean. Upper-case captions."},"caption_animation":{"description":"`none`, `pop` or `fade`."},"voiceover_text":{"description":"A typed voiceover script, up to 1500 characters, read by `voiceover_voice` (or by your `voiceover_sample`). An uploaded `voiceover` file wins. Same price."},"voiceover_voice":{"description":"A voice id from GET /director/voiceover/voices (default `af_heart`). Write the script in that voice’s language."},"voice_clone":{"description":"How a `voiceover_sample` is cloned: `natural` (default, best match), `fast` or `classic`. Same price."},"end_card_s":{"description":"Seconds the end card stays on screen."},"end_card_style":{"description":"End-card layout style."},"logo_corner":{"description":"Which corner a corner logo sits in."},"logo_scale":{"description":"Logo size."},"text_color":{"description":"End-card text colour."},"accent_color":{"description":"End-card accent colour."},"background_color":{"description":"End-card background colour."},"keep_original_audio":{"description":"Boolean. Keep the video’s own sound under the new mix."},"original_db":{"description":"Level of the video’s own sound in dB."},"music_db":{"description":"Music bed level in dB."},"voiceover_db":{"description":"Voiceover level in dB."},"duck_db":{"description":"How far the music dips under the voiceover, in dB."},"duck_under_dialogue":{"description":"Boolean. Also dip the music wherever the video’s own characters speak."},"dialogue_duck_db":{"description":"How far the music dips under dialogue, in dB (default -12)."},"voiceover_start_s":{"description":"Seconds into the video the voiceover starts."},"lufs":{"description":"Target loudness in LUFS."},"formats":{"description":"Other frame shapes to deliver as well: any of `9:16`, `1:1`, `4:5` (JSON list or comma-separated). Each is a `deliverables` entry and adds its seconds to the price."},"reframe":{"description":"`crop` (follows faces) or `fit` (blurs the sides) for the other shapes."},"cutdowns":{"description":"Up to 3 shorter lengths in seconds (JSON list or comma-separated), delivered in every shape. A cutdown not at least 1 s shorter than the video is skipped and not charged."},"no_slowmo":{"description":"Boolean. Play accidental slow-motion stretches at real speed (made for fights and action); the video gets shorter."},"no_slowmo_max":{"description":"With `no_slowmo`: the fastest speed-up (default 2)."},"speed_up":{"description":"With `no_slowmo`: also play the whole video this much faster (default 1)."},"dub_language":{"description":"A dub into this language (e.g. `Spanish`): the speech is separated from the music, translated and read again in each speaker’s own cloned voice, over the original music. The lips do not match the new language."},"subtitle_language":{"description":"Subtitles translated into this language (e.g. `Japanese`), line by line with the same times; uses the captions (made automatically if you send none)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"With ?check=true or ?dry_run=true: a free preflight { object: \"director.preflight\", credits.quoted, promptCheck, … }. Nothing is reserved or rendered."},"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/series/{id}/season":{"post":{"summary":"Director: plan a season of a TV series","description":"Plans a season of one of your series: an arc across `episodes` (2–20, default 6) from an `idea` (10–3000 characters: the big story and where it ends), one line per episode, threads that run across them and the new characters it brings in. Saved on the show: each planned episode's writer gets the arc and its own line, and POST /director/series/{id}/episodes needs no `idea` for a planned episode. A new plan replaces the old one. A writer call: it runs in the background for a few minutes and the plan is in the job's `result`. Price: 151 credits, charged when it is done, given back if it fails.\n\nAnswers 202 with a `director.job`. Poll GET /director/jobs/{id}; `result` holds the output when `status` is `done`. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"idea":{"description":"What the piece is about, up to 4000 characters (counted as sent). With an idea the AI writes it (a writer round is charged)."},"episodes":{"description":"How many episodes the season plans, 2–20 (default 6)."},"first":{"description":"The first planned episode’s number, 1–999 (default: the next episode)."}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"idea":{"description":"What the piece is about, up to 4000 characters (counted as sent). With an idea the AI writes it (a writer round is charged)."},"episodes":{"description":"How many episodes the season plans, 2–20 (default 6)."},"first":{"description":"The first planned episode’s number, 1–999 (default: the next episode)."}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/images/text":{"post":{"summary":"Director: text to image","description":"Text to image. Price: ceil(max(16, (96 + 2 x megapixels) x 0.15095) x 1.45475), x 1.55 with `image_model: \"high\"`, x steps/6 above 6 steps. The default (4 megapixels) is 24 credits.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"description":"The shot prompt: up to 8000 characters on Montage Basic, 30,000 with `video_model` `montage-premium` or `montage-ultra` in the body (counted as sent: each line break counts as two). Plain prompts always render; prompts in the official format are checked first (422 `prompt_check_failed` on errors)."},"aspect":{"description":"Frame shape, for example `16:9`, `9:16` or `1:1`."},"megapixels":{"description":"Images: picture size in megapixels, priced between 0.5 and 16; default 4. `videos/reference` on Montage Basic: `0.7` (default) or `1.0` for a sharper render (priced 1.7x); refused on Montage Premium and Ultra."},"seed":{"description":"Integer seed, to repeat a result."},"steps":{"description":"Sampling steps (default 6). More cost more in proportion."},"enhance":{"description":"Boolean. Let the studio enrich the prompt."},"image_model":{"description":"`high` for the higher-quality image model (priced 1.55x). Leave unset for the standard one."}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"description":"The shot prompt: up to 8000 characters on Montage Basic, 30,000 with `video_model` `montage-premium` or `montage-ultra` in the body (counted as sent: each line break counts as two). Plain prompts always render; prompts in the official format are checked first (422 `prompt_check_failed` on errors)."},"aspect":{"description":"Frame shape, for example `16:9`, `9:16` or `1:1`."},"megapixels":{"description":"Images: picture size in megapixels, priced between 0.5 and 16; default 4. `videos/reference` on Montage Basic: `0.7` (default) or `1.0` for a sharper render (priced 1.7x); refused on Montage Premium and Ultra."},"seed":{"description":"Integer seed, to repeat a result."},"steps":{"description":"Sampling steps (default 6). More cost more in proportion."},"enhance":{"description":"Boolean. Let the studio enrich the prompt."},"image_model":{"description":"`high` for the higher-quality image model (priced 1.55x). Leave unset for the standard one."}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/images/edit":{"post":{"summary":"Director: edit an image","description":"Edits one picture (`image`) with a prompt. Price: ceil(max(17, (100 + 2 x megapixels) x 0.15095) x 1.45475), x 1.55 with `image_model: \"high\"`, x steps/6 above 6 steps. The default is 25 credits.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"description":"The shot prompt: up to 8000 characters on Montage Basic, 30,000 with `video_model` `montage-premium` or `montage-ultra` in the body (counted as sent: each line break counts as two). Plain prompts always render; prompts in the official format are checked first (422 `prompt_check_failed` on errors)."},"megapixels":{"description":"Images: picture size in megapixels, priced between 0.5 and 16; default 4. `videos/reference` on Montage Basic: `0.7` (default) or `1.0` for a sharper render (priced 1.7x); refused on Montage Premium and Ultra."},"seed":{"description":"Integer seed, to repeat a result."},"steps":{"description":"Sampling steps (default 6). More cost more in proportion."},"enhance":{"description":"Boolean. Let the studio enrich the prompt."},"exif_rotate":{"description":"Boolean. Turn uploaded pictures upright by their EXIF orientation."},"image_model":{"description":"`high` for the higher-quality image model (priced 1.55x). Leave unset for the standard one."},"image":{"description":"The picture to animate. image: multipart file(s), or URL / asset path string(s); up to 1."},"image_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/images/reference":{"post":{"summary":"Director: image from reference pictures","description":"A new picture from 1–8 reference pictures (`images`). Price: ceil(max(17, (96 + 2 x megapixels + 4 x pictures) x 0.15095) x 1.45475), x 1.55 with `image_model: \"high\"`, x steps/6 above 6 steps. Three pictures at the default size is 26 credits.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"description":"The shot prompt: up to 8000 characters on Montage Basic, 30,000 with `video_model` `montage-premium` or `montage-ultra` in the body (counted as sent: each line break counts as two). Plain prompts always render; prompts in the official format are checked first (422 `prompt_check_failed` on errors)."},"aspect":{"description":"Frame shape, for example `16:9`, `9:16` or `1:1`."},"megapixels":{"description":"Images: picture size in megapixels, priced between 0.5 and 16; default 4. `videos/reference` on Montage Basic: `0.7` (default) or `1.0` for a sharper render (priced 1.7x); refused on Montage Premium and Ultra."},"seed":{"description":"Integer seed, to repeat a result."},"steps":{"description":"Sampling steps (default 6). More cost more in proportion."},"exif_rotate":{"description":"Boolean. Turn uploaded pictures upright by their EXIF orientation."},"fix_prompt":{"description":"`off` (default), `safe` (rule-based, instant) or `ai` (also fixes what the checker still finds). Repairs untrained camera words, grain words and \"no crowd\" lines in your own prompts. `safe` is free; `ai` adds 16 credits."},"image_model":{"description":"`high` for the higher-quality image model (priced 1.55x). Leave unset for the standard one."},"images":{"description":"Reference pictures, numbered in order as <Picture 1>, <Picture 2>… image: multipart file(s), or URL / asset path string(s); up to 8."},"images_urls":{"type":"array","items":{"type":"string"},"maxItems":8}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/music/generate":{"post":{"summary":"Director: generate a song","description":"A complete song from a description (`prompt`, up to 4000) and `lyrics` (up to 6000). Price: 36 credits, or 0.75 credits a second of `duration` when that is more (60 s: 45, 75 s: 57), x steps/30 above 30 steps. The song can come back shorter than `duration` (`durationShort`). Use the finished job as `song_job` on videos/music.\n\nAnswers 202 with a `director.job` (and a `Location` header); the credits are held. Poll GET /director/jobs/{id} until `status` is `done`, `failed` or `cancelled`; the finished file is copied into your assets. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"description":"The style of the song in words (genre, mood, voice), up to 4000 characters."},"lyrics":{"description":"The lyrics, up to 6000 characters. Section tags (for example `[verse]`, `[chorus]`) shape the song."},"instrumental":{"description":"Boolean. No vocals."},"duration":{"description":"Length in seconds. The song ends when its structure is complete, so it can come back shorter (`durationShort`)."},"seed":{"description":"Integer seed, to repeat a result."},"steps":{"description":"Sampling steps (default 30). More cost more in proportion."},"cfg_scale":{"description":"How closely the song follows the prompt."},"format":{"description":"Audio file format of the song."},"voices":{"description":"A duet song: `{\"male\": \"a deep baritone\", \"female\": \"a powerful R&B voice\"}`, or for two women or two men `{\"first\": \"...\", \"second\": \"...\"}`. Tag every lyric section with its singer: `[verse: first]`, `[chorus: second]`. Man and woman: each section is sung by its singer and joined, 36 credits per tagged section. Two women or two men: one song in the first voice with the second singer's sections re-voiced (no joins), the song’s price plus 36 credits. A music video made from it (`song_job`, with `singers` using the same keys) knows exactly who sings when."},"fill":{"description":"`none` (default): the song as the model ends it, which can be shorter than `duration`. `loop`: loop it with 1 s crossfades to exactly `duration`, then fade out (lyrics repeat). Free."}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"prompt":{"description":"The style of the song in words (genre, mood, voice), up to 4000 characters."},"lyrics":{"description":"The lyrics, up to 6000 characters. Section tags (for example `[verse]`, `[chorus]`) shape the song."},"instrumental":{"description":"Boolean. No vocals."},"duration":{"description":"Length in seconds. The song ends when its structure is complete, so it can come back shorter (`durationShort`)."},"seed":{"description":"Integer seed, to repeat a result."},"steps":{"description":"Sampling steps (default 30). More cost more in proportion."},"cfg_scale":{"description":"How closely the song follows the prompt."},"format":{"description":"Audio file format of the song."},"voices":{"description":"A duet song: `{\"male\": \"a deep baritone\", \"female\": \"a powerful R&B voice\"}`, or for two women or two men `{\"first\": \"...\", \"second\": \"...\"}`. Tag every lyric section with its singer: `[verse: first]`, `[chorus: second]`. Man and woman: each section is sung by its singer and joined, 36 credits per tagged section. Two women or two men: one song in the first voice with the second singer's sections re-voiced (no joins), the song’s price plus 36 credits. A music video made from it (`song_job`, with `singers` using the same keys) knows exactly who sings when."},"fill":{"description":"`none` (default): the song as the model ends it, which can be shorter than `duration`. `loop`: loop it with 1 s crossfades to exactly `duration`, then fade out (lyrics repeat). Free."}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/music/plan":{"post":{"summary":"Director: plan a music video","description":"Plans a music video for a song (`song` or `song_job`): sections, vocals and, with an `idea`, a treatment. A writer call: it runs in the background for a few minutes and the plan is in the job's `result`. Price: 151 with an `idea`, 16 without. Charged when it is done; given back if it fails.\n\nAnswers 202 with a `director.job`. Poll GET /director/jobs/{id}; `result` holds the output when `status` is `done`. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"song_job":{"description":"A finished `music/generate` (or other audio) Director job id to use as the song, instead of a `song` file."},"idea":{"description":"What the video is about, up to 4000 characters. Without an idea only the song is analysed (16 credits); with one the writer also writes a treatment (151 credits)."},"references":{"description":"What each of your `images` shows, in order, as a JSON list of strings."},"style":{"description":"A look in words for the whole piece, up to 500 characters."},"aspect":{"description":"Frame shape, for example `16:9`, `9:16` or `1:1`."},"read_emotion":{"description":"Boolean. Also read the emotion of each section."},"balance_sections":{"description":"Boolean. Evens out a last section under 6 s with the one before it (33 s becomes 15 + 9 + 9). On by default when the AI writes the sections. Send the same value to `music/plan` and `videos/music`."},"song":{"description":"The song. Its length sets the number of 15 s sections and the price. audio: multipart file(s), or URL / asset path string(s); up to 1."},"song_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/prompts/write":{"post":{"summary":"Director: write clip prompts","description":"Writes ready-to-shoot clip prompts from a `story` (up to 4000) for a film, a commercial or a single shot. A writer call: it runs in the background for a few minutes and the clips are in the job's `result`. Price: `film` mode 151 per writer round (1 round up to 8 clips, otherwise 1 + clips/4 rounded up); other modes 151; plus 76 for a commercial in film or reference mode. Charged when it is done; given back if it fails.\n\nAnswers 202 with a `director.job`. Poll GET /director/jobs/{id}; `result` holds the output when `status` is `done`. Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`) or a path from your own assets. At most 8 Director jobs run at once per account.","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"story":{"description":"What the film, commercial or shot is about, up to 4000 characters (counted as sent)."},"duration":{"description":"Seconds: the film’s length (30–420) in `film` mode, or 6–15 in `reference` mode."},"section_vocals":{"description":"Advanced tuning. Leave unset for the default."},"mode":{"description":"`film` (default: 15 s clips for a film of `duration`) or `reference` (one 6–15 s shot)."},"references":{"description":"What each reference picture shows, as a JSON list."},"voices":{"description":"Whose voice each audio sample is, in order, as a JSON list."},"style":{"description":"A look in words for the whole piece, up to 500 characters."},"aspect":{"description":"Frame shape, for example `16:9`, `9:16` or `1:1`."},"film_type":{"description":"`commercial` adds the ad self-review pass (76 credits) in film and reference mode. `short_drama` writes a vertical micro-drama (hook in the first 3 s, one beat per 15 s clip, close-ups, short lines, a cliffhanger); with `drama_trope` and `cliffhanger`."},"drama_trope":{"description":"With `film_type: \"short_drama\"`: the story engine — `auto` (default), `revenge`, `hidden_identity`, `rich_poor`, `betrayal`, `second_chance`, `contract_marriage`, `fated_mate` or `secret_baby`."},"cliffhanger":{"description":"Boolean, with `film_type: \"short_drama\"` (default true): end on an unresolved cliffhanger. `false` ends on the payoff, e.g. for a season finale."},"ad_style":{"description":"Commercials: `problem_solution`, `product_hero`, `slice_of_life`, `demo`, `cinematic_story`, `comedy`, `sensory`, `montage`, `before_after`, `aspirational`, `reveal`, or `auto` (default: the writer picks)."},"brand_id":{"description":"A brand id from POST /director/brands. Only your own brands work (404 otherwise). Turns on packaging."},"product_pictures":{"description":"Which of your `references` show the product, 1-based."},"voiceover":{"description":"Boolean. Leave room in the clips for a voiceover."},"balance_sections":{"description":"Boolean. Evens out a last section under 6 s with the one before it (33 s becomes 15 + 9 + 9). On by default when the AI writes the sections. Send the same value to `music/plan` and `videos/music`."},"end_card_s":{"description":"Seconds the end card stays on screen."}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"story":{"description":"What the film, commercial or shot is about, up to 4000 characters (counted as sent)."},"duration":{"description":"Seconds: the film’s length (30–420) in `film` mode, or 6–15 in `reference` mode."},"section_vocals":{"description":"Advanced tuning. Leave unset for the default."},"mode":{"description":"`film` (default: 15 s clips for a film of `duration`) or `reference` (one 6–15 s shot)."},"references":{"description":"What each reference picture shows, as a JSON list."},"voices":{"description":"Whose voice each audio sample is, in order, as a JSON list."},"style":{"description":"A look in words for the whole piece, up to 500 characters."},"aspect":{"description":"Frame shape, for example `16:9`, `9:16` or `1:1`."},"film_type":{"description":"`commercial` adds the ad self-review pass (76 credits) in film and reference mode. `short_drama` writes a vertical micro-drama (hook in the first 3 s, one beat per 15 s clip, close-ups, short lines, a cliffhanger); with `drama_trope` and `cliffhanger`."},"drama_trope":{"description":"With `film_type: \"short_drama\"`: the story engine — `auto` (default), `revenge`, `hidden_identity`, `rich_poor`, `betrayal`, `second_chance`, `contract_marriage`, `fated_mate` or `secret_baby`."},"cliffhanger":{"description":"Boolean, with `film_type: \"short_drama\"` (default true): end on an unresolved cliffhanger. `false` ends on the payoff, e.g. for a season finale."},"ad_style":{"description":"Commercials: `problem_solution`, `product_hero`, `slice_of_life`, `demo`, `cinematic_story`, `comedy`, `sensory`, `montage`, `before_after`, `aspirational`, `reveal`, or `auto` (default: the writer picks)."},"brand_id":{"description":"A brand id from POST /director/brands. Only your own brands work (404 otherwise). Turns on packaging."},"product_pictures":{"description":"Which of your `references` show the product, 1-based."},"voiceover":{"description":"Boolean. Leave room in the clips for a voiceover."},"balance_sections":{"description":"Boolean. Evens out a last section under 6 s with the one before it (33 s becomes 15 + 9 + 9). On by default when the AI writes the sections. Send the same value to `music/plan` and `videos/music`."},"end_card_s":{"description":"Seconds the end card stays on screen."}},"additionalProperties":false}}}},"responses":{"202":{"description":"Job started; credits reserved.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"invalid_request, invalid_json or invalid_media_url; preflight_unavailable when ?check or ?dry_run is sent to an endpoint without a free quote (nothing starts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"insufficient_credits (requiredCredits says how many)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (a referenced job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (a referenced job has not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"prompt_check_failed: an official-format prompt has checker errors; `promptCheck` holds the report. Nothing was charged. Send strict_prompt=false to render anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"concurrency_limit (8 Director jobs at once; see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"studio_error — nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable — the studio is busy; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/prompts/check":{"post":{"summary":"Director: check prompts against the house rules (free)","tags":["Director"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"description":"The shot prompt: up to 8000 characters on Montage Basic, 30,000 with `video_model` `montage-premium` or `montage-ultra` in the body (counted as sent: each line break counts as two). Plain prompts always render; prompts in the official format are checked first (422 `prompt_check_failed` on errors)."},"clips":{"description":"Your own clip prompts as a JSON list, one per 15 s clip, instead of an `idea`."},"refs":{"description":"The reference pictures the prompt uses."},"clip_refs":{"description":"The reference pictures each clip uses."},"duration":{"description":"Length in seconds. Single shots are 5–15 s; with `long_form: true` a reference shot is 20–60 s."}},"additionalProperties":false}}}},"responses":{"200":{"description":"{ ok, issues[], counts }"},"400":{"description":"invalid_json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"service_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free and synchronous. Checks a shot `prompt` (or a film’s `clips`, with `refs`, `clip_refs` and `duration`) against the studio’s house rules before you spend credits. Answers `{ ok, issues[], counts }`: `ok` is false when there is an ERROR; WARN often goes wrong; INFO is a tip. JSON body only (400 `invalid_json` otherwise)."}},"/director/catalog":{"get":{"summary":"Director: endpoints, looks, styles and credit prices","tags":["Director"],"responses":{"200":{"description":"Catalog"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Everything needed to call the Director API: every start endpoint with its path, accepted `fields`, `files` (kind, max, how each is accepted), text `maxLength` limits, which fields take a job id or a brand id; the named `looks`; the `styles` for `styles: [{style, strength}]` (up to 3, strength 0–1, on videos/text and videos/image); and the live credit `prices` (1 credit = 1 cent)."}},"/montage":{"get":{"summary":"Montage (the Director API) for agents: what it makes, how a production runs, a quickstart, limits, prices and links (public, free)","tags":["Director"],"security":[],"responses":{"200":{"description":"The Montage overview"}},"description":"Public, no key needed. What Montage (the product behind the Director API) makes, how a production runs, a quickstart for agents, limits, prices and links."}},"/director/voiceover/voices":{"get":{"summary":"Director: the voices for a packaging `voiceover_text` script (free)","tags":["Director"],"responses":{"200":{"description":"{ object: \"list\", default, data: [{ id, description }] }"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. The voices that can read a packaging `voiceover_text` script: `{ object: \"list\", default, data: [{ id, language, description }], cloning }`. 54 voices in 8 languages; the default is `af_heart`. Write the script in the voice’s language. To use your own narrator instead, send a `voiceover_sample` (5–15 s, clean) and pick `voice_clone`."}},"/director/jobs":{"get":{"summary":"Director: list your jobs (newest first)","tags":["Director"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"before","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"endpoint","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"{ object: \"list\", data: DirectorJob[], hasMore, nextBefore }"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Your Director jobs, newest first: `{ object: \"list\", data: DirectorJob[], hasMore, nextBefore }`. `limit` 1–100 (default 20). Page by passing the last page’s `nextBefore` as `before`. `endpoint` filters by start endpoint (for example `videos/film`); an unknown value is ignored. Listing does not refresh progress: GET one job for live status."}},"/director/brands":{"get":{"summary":"Director: list your saved brands (free)","tags":["Director"],"responses":{"200":{"description":"{ object: \"list\", data: DirectorBrand[] }"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. Your saved brands, newest first: `{ object: \"list\", data: DirectorBrand[] }`. Only you can see or use your brands."},"post":{"summary":"Director: save a brand: logo, font, tagline, cta, colours, end card and sound defaults, writer brief (free)","tags":["Director"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"description":"The name (required when saving)."},"tagline":{"description":"End-card tagline, up to 120 characters."},"cta":{"description":"End-card call to action, up to 60 characters."},"product_name":{"description":"The product’s name, for the writer."},"description":{"description":"What the brand or product is, for the writer."},"audience":{"description":"Who the ads are for, for the writer."},"voice":{"description":"The brand’s tone of voice, for the writer."},"look":{"description":"A named look from GET /director/catalog: `default`, `realistic_people`, `soft_portrait`, `golden_hour`, `film_teal`, `anime_90s`, `horror_80s`, `raw_skin`."},"banned_words":{"description":"Words the writer must never use."},"end_card_s":{"description":"Seconds the end card stays on screen."},"end_card_style":{"description":"End-card layout style."},"logo_corner":{"description":"Which corner a corner logo sits in."},"logo_scale":{"description":"Logo size."},"text_color":{"description":"End-card text colour."},"accent_color":{"description":"End-card accent colour."},"background_color":{"description":"End-card background colour."},"music_db":{"description":"Music bed level in dB."},"voiceover_db":{"description":"Voiceover level in dB."},"duck_db":{"description":"How far the music dips under the voiceover, in dB."},"lufs":{"description":"Target loudness in LUFS."},"remove_logo":{"description":"Boolean. Drop the saved logo."},"remove_font":{"description":"Boolean. Drop the saved font."},"logo":{"description":"Logo image (a PNG with transparency works best). Turns on packaging. image: multipart file(s), or URL / asset path string(s); up to 1."},"logo_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"font":{"description":"A .ttf or .otf font for the end card. font: multipart file(s), or URL / asset path string(s); up to 1."},"font_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The name (required when saving)."},"tagline":{"description":"End-card tagline, up to 120 characters."},"cta":{"description":"End-card call to action, up to 60 characters."},"product_name":{"description":"The product’s name, for the writer."},"description":{"description":"What the brand or product is, for the writer."},"audience":{"description":"Who the ads are for, for the writer."},"voice":{"description":"The brand’s tone of voice, for the writer."},"look":{"description":"A named look from GET /director/catalog: `default`, `realistic_people`, `soft_portrait`, `golden_hour`, `film_teal`, `anime_90s`, `horror_80s`, `raw_skin`."},"banned_words":{"description":"Words the writer must never use."},"end_card_s":{"description":"Seconds the end card stays on screen."},"end_card_style":{"description":"End-card layout style."},"logo_corner":{"description":"Which corner a corner logo sits in."},"logo_scale":{"description":"Logo size."},"text_color":{"description":"End-card text colour."},"accent_color":{"description":"End-card accent colour."},"background_color":{"description":"End-card background colour."},"music_db":{"description":"Music bed level in dB."},"voiceover_db":{"description":"Voiceover level in dB."},"duck_db":{"description":"How far the music dips under the voiceover, in dB."},"lufs":{"description":"Target loudness in LUFS."},"remove_logo":{"description":"Boolean. Drop the saved logo."},"remove_font":{"description":"Boolean. Drop the saved font."},"logo":{"description":"Logo image (a PNG with transparency works best). Turns on packaging. image: multipart file(s), or URL / asset path string(s); up to 1."},"logo_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"font":{"description":"A .ttf or .otf font for the end card. font: multipart file(s), or URL / asset path string(s); up to 1."},"font_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"201":{"description":"The saved brand.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.brand"},"name":{"type":"string"},"tagline":{"type":["string","null"]},"has_logo":{"type":"boolean"},"has_font":{"type":"boolean"},"logoUrl":{"type":["string","null"],"format":"uri"}},"additionalProperties":true}}}},"400":{"description":"invalid_request (name is required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (50 brands per account)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. Saves a brand to use with `brand_id` on shots, films, music videos and packaging: `name` (required), the writer brief (`product_name`, `description`, `audience`, `voice`, `look`, `banned_words`), end-card defaults (`tagline`, `cta`, `end_card_s`, `end_card_style`, `logo_corner`, `logo_scale`, colours) and sound defaults (`music_db`, `voiceover_db`, `duck_db`, `lufs`), plus a `logo` and a `font`. Multipart or JSON. At most 50 brands per account (409 `conflict`)."}},"/director/brands/{id}":{"get":{"summary":"Director: get one of your brands","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The brand.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.brand"},"name":{"type":"string"},"tagline":{"type":["string","null"]},"has_logo":{"type":"boolean"},"has_font":{"type":"boolean"},"logoUrl":{"type":["string","null"],"format":"uri"}},"additionalProperties":true}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. One of your brands, with `has_logo`, `has_font` and `logoUrl`. 404 for anyone else’s."},"post":{"summary":"Director: change a brand (send only what changes)","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"description":"The name (required when saving)."},"tagline":{"description":"End-card tagline, up to 120 characters."},"cta":{"description":"End-card call to action, up to 60 characters."},"product_name":{"description":"The product’s name, for the writer."},"description":{"description":"What the brand or product is, for the writer."},"audience":{"description":"Who the ads are for, for the writer."},"voice":{"description":"The brand’s tone of voice, for the writer."},"look":{"description":"A named look from GET /director/catalog: `default`, `realistic_people`, `soft_portrait`, `golden_hour`, `film_teal`, `anime_90s`, `horror_80s`, `raw_skin`."},"banned_words":{"description":"Words the writer must never use."},"end_card_s":{"description":"Seconds the end card stays on screen."},"end_card_style":{"description":"End-card layout style."},"logo_corner":{"description":"Which corner a corner logo sits in."},"logo_scale":{"description":"Logo size."},"text_color":{"description":"End-card text colour."},"accent_color":{"description":"End-card accent colour."},"background_color":{"description":"End-card background colour."},"music_db":{"description":"Music bed level in dB."},"voiceover_db":{"description":"Voiceover level in dB."},"duck_db":{"description":"How far the music dips under the voiceover, in dB."},"lufs":{"description":"Target loudness in LUFS."},"remove_logo":{"description":"Boolean. Drop the saved logo."},"remove_font":{"description":"Boolean. Drop the saved font."},"logo":{"description":"Logo image (a PNG with transparency works best). Turns on packaging. image: multipart file(s), or URL / asset path string(s); up to 1."},"logo_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"font":{"description":"A .ttf or .otf font for the end card. font: multipart file(s), or URL / asset path string(s); up to 1."},"font_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The name (required when saving)."},"tagline":{"description":"End-card tagline, up to 120 characters."},"cta":{"description":"End-card call to action, up to 60 characters."},"product_name":{"description":"The product’s name, for the writer."},"description":{"description":"What the brand or product is, for the writer."},"audience":{"description":"Who the ads are for, for the writer."},"voice":{"description":"The brand’s tone of voice, for the writer."},"look":{"description":"A named look from GET /director/catalog: `default`, `realistic_people`, `soft_portrait`, `golden_hour`, `film_teal`, `anime_90s`, `horror_80s`, `raw_skin`."},"banned_words":{"description":"Words the writer must never use."},"end_card_s":{"description":"Seconds the end card stays on screen."},"end_card_style":{"description":"End-card layout style."},"logo_corner":{"description":"Which corner a corner logo sits in."},"logo_scale":{"description":"Logo size."},"text_color":{"description":"End-card text colour."},"accent_color":{"description":"End-card accent colour."},"background_color":{"description":"End-card background colour."},"music_db":{"description":"Music bed level in dB."},"voiceover_db":{"description":"Voiceover level in dB."},"duck_db":{"description":"How far the music dips under the voiceover, in dB."},"lufs":{"description":"Target loudness in LUFS."},"remove_logo":{"description":"Boolean. Drop the saved logo."},"remove_font":{"description":"Boolean. Drop the saved font."},"logo":{"description":"Logo image (a PNG with transparency works best). Turns on packaging. image: multipart file(s), or URL / asset path string(s); up to 1."},"logo_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"font":{"description":"A .ttf or .otf font for the end card. font: multipart file(s), or URL / asset path string(s); up to 1."},"font_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"200":{"description":"The updated brand.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.brand"},"name":{"type":"string"},"tagline":{"type":["string","null"]},"has_logo":{"type":"boolean"},"has_font":{"type":"boolean"},"logoUrl":{"type":["string","null"],"format":"uri"}},"additionalProperties":true}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. Changes a brand: send only what changes. `remove_logo=true` or `remove_font=true` drops a file."},"delete":{"summary":"Director: delete a brand (started jobs keep their copy)","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"{ id, object, deleted: true }"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Deletes a brand. Jobs already started keep their own copy of it."}},"/director/brands/{id}/logo":{"get":{"summary":"Director: the brand's logo image","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"image/png"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. The brand’s logo image."}},"/director/series":{"get":{"summary":"Director: list your saved TV series (free)","tags":["Director"],"responses":{"200":{"description":"{ object: \"list\", data: DirectorSeries[] }"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. Your saved TV series, newest first: `{ object: \"list\", data: DirectorSeries[] }`."},"post":{"summary":"Director: save a TV series: name, premise, style, aspect, theme music, title card, cast, and a story or short-drama format (free)","tags":["Director"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"description":"The name (required when saving)."},"premise":{"description":"The show’s world and tone, for the writer."},"style":{"description":"A look in words for the whole piece, up to 500 characters."},"aspect":{"description":"Frame shape, for example `16:9`, `9:16` or `1:1`."},"theme_s":{"description":"Seconds the theme plays under the opening (default 10)."},"title_card":{"description":"An opening title card, up to 160 characters and 3 lines (the first line big)."},"cast":{"description":"A JSON list of `{name, what, kind}` (kind `person`, `place` or `thing`). name up to 60, what up to 400 characters."},"references":{"description":"What each of your `images` shows, in order, as a JSON list of strings."},"voices":{"description":"Whose voice each audio sample is, in order, as a JSON list."},"remove_theme":{"description":"Boolean. Drop the theme music."},"theme":{"description":"Theme music for the opening. audio: multipart file(s), or URL / asset path string(s); up to 1."},"theme_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"pictures":{"description":"1–9 pictures of the cast; say what each shows in `references` (the name is the text before the first comma). New pictures replace all the old ones. image: multipart file(s), or URL / asset path string(s); up to 9."},"pictures_urls":{"type":"array","items":{"type":"string"},"maxItems":9},"voice_samples":{"description":"0–3 voice samples; say whose each is in `voices`. New samples replace all the old ones. audio: multipart file(s), or URL / asset path string(s); up to 3."},"voice_samples_urls":{"type":"array","items":{"type":"string"},"maxItems":3}},"additionalProperties":false}},"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The name (required when saving)."},"premise":{"description":"The show’s world and tone, for the writer."},"style":{"description":"A look in words for the whole piece, up to 500 characters."},"aspect":{"description":"Frame shape, for example `16:9`, `9:16` or `1:1`."},"theme_s":{"description":"Seconds the theme plays under the opening (default 10)."},"title_card":{"description":"An opening title card, up to 160 characters and 3 lines (the first line big)."},"cast":{"description":"A JSON list of `{name, what, kind}` (kind `person`, `place` or `thing`). name up to 60, what up to 400 characters."},"references":{"description":"What each of your `images` shows, in order, as a JSON list of strings."},"voices":{"description":"Whose voice each audio sample is, in order, as a JSON list."},"remove_theme":{"description":"Boolean. Drop the theme music."},"theme":{"description":"Theme music for the opening. audio: multipart file(s), or URL / asset path string(s); up to 1."},"theme_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"pictures":{"description":"1–9 pictures of the cast; say what each shows in `references` (the name is the text before the first comma). New pictures replace all the old ones. image: multipart file(s), or URL / asset path string(s); up to 9."},"pictures_urls":{"type":"array","items":{"type":"string"},"maxItems":9},"voice_samples":{"description":"0–3 voice samples; say whose each is in `voices`. New samples replace all the old ones. audio: multipart file(s), or URL / asset path string(s); up to 3."},"voice_samples_urls":{"type":"array","items":{"type":"string"},"maxItems":3}},"additionalProperties":false}}}},"responses":{"201":{"description":"The saved series.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.series"},"name":{"type":"string"},"premise":{"type":["string","null"]},"style":{"type":["string","null"]},"aspect":{"type":"string","enum":["16:9","9:16","1:1"]},"theme_s":{"type":"number"},"title_card":{"type":"boolean"},"cast":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":60},"what":{"type":["string","null"],"maxLength":400},"kind":{"type":"string","enum":["person","place","thing"]},"episodes":{"type":"array","items":{"type":"integer"}},"voice_what":{"type":["string","null"],"maxLength":200},"learned":{"type":["string","null"]},"pictureUrl":{"type":["string","null"],"format":"uri"},"voiceUrl":{"type":["string","null"],"format":"uri"}},"additionalProperties":true}}},"additionalProperties":true}}}},"400":{"description":"invalid_request (name is required; cast text limits)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (50 series per account)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Saves a TV series (free): `name` (required, up to 200), `premise`, `style`, `aspect` (16:9, 9:16 or 1:1), a `theme` file (plays under the opening for `theme_s`, default 10 s), `title_card` (on by default: \"NAME / Episode N: Title\"), `laugh_track` for every episode, and the cast: `cast` (JSON list of `{name, what, kind}`), or `pictures` (1–9) with `references` and `voice_samples` (0–3) with `voices`. `theme_auto=true` or a `theme_brief` has the theme made once: 36 credits, held first and charged when the studio takes it. Multipart or JSON. At most 50 series per account (409 `conflict`). Cast limits: name 60, what 400, voice_what 200 characters."}},"/director/series/{id}":{"get":{"summary":"Director: get one of your series, with its cast","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The series.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.series"},"name":{"type":"string"},"premise":{"type":["string","null"]},"style":{"type":["string","null"]},"aspect":{"type":"string","enum":["16:9","9:16","1:1"]},"theme_s":{"type":"number"},"title_card":{"type":"boolean"},"cast":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":60},"what":{"type":["string","null"],"maxLength":400},"kind":{"type":"string","enum":["person","place","thing"]},"episodes":{"type":"array","items":{"type":"integer"}},"voice_what":{"type":["string","null"],"maxLength":200},"learned":{"type":["string","null"]},"pictureUrl":{"type":["string","null"],"format":"uri"},"voiceUrl":{"type":["string","null"],"format":"uri"}},"additionalProperties":true}}},"additionalProperties":true}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. One of your series with its cast; each member has `pictureUrl` and `voiceUrl` when set. 404 for anyone else’s."},"post":{"summary":"Director: change a series (send only what changes; new pictures or voice_samples replace the old ones; remove_theme=true drops the theme)","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"description":"The name (required when saving)."},"premise":{"description":"The show’s world and tone, for the writer."},"style":{"description":"A look in words for the whole piece, up to 500 characters."},"aspect":{"description":"Frame shape, for example `16:9`, `9:16` or `1:1`."},"theme_s":{"description":"Seconds the theme plays under the opening (default 10)."},"title_card":{"description":"An opening title card, up to 160 characters and 3 lines (the first line big)."},"cast":{"description":"A JSON list of `{name, what, kind}` (kind `person`, `place` or `thing`). name up to 60, what up to 400 characters."},"references":{"description":"What each of your `images` shows, in order, as a JSON list of strings."},"voices":{"description":"Whose voice each audio sample is, in order, as a JSON list."},"remove_theme":{"description":"Boolean. Drop the theme music."},"theme":{"description":"Theme music for the opening. audio: multipart file(s), or URL / asset path string(s); up to 1."},"theme_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"pictures":{"description":"1–9 pictures of the cast; say what each shows in `references` (the name is the text before the first comma). New pictures replace all the old ones. image: multipart file(s), or URL / asset path string(s); up to 9."},"pictures_urls":{"type":"array","items":{"type":"string"},"maxItems":9},"voice_samples":{"description":"0–3 voice samples; say whose each is in `voices`. New samples replace all the old ones. audio: multipart file(s), or URL / asset path string(s); up to 3."},"voice_samples_urls":{"type":"array","items":{"type":"string"},"maxItems":3}},"additionalProperties":false}},"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The name (required when saving)."},"premise":{"description":"The show’s world and tone, for the writer."},"style":{"description":"A look in words for the whole piece, up to 500 characters."},"aspect":{"description":"Frame shape, for example `16:9`, `9:16` or `1:1`."},"theme_s":{"description":"Seconds the theme plays under the opening (default 10)."},"title_card":{"description":"An opening title card, up to 160 characters and 3 lines (the first line big)."},"cast":{"description":"A JSON list of `{name, what, kind}` (kind `person`, `place` or `thing`). name up to 60, what up to 400 characters."},"references":{"description":"What each of your `images` shows, in order, as a JSON list of strings."},"voices":{"description":"Whose voice each audio sample is, in order, as a JSON list."},"remove_theme":{"description":"Boolean. Drop the theme music."},"theme":{"description":"Theme music for the opening. audio: multipart file(s), or URL / asset path string(s); up to 1."},"theme_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"pictures":{"description":"1–9 pictures of the cast; say what each shows in `references` (the name is the text before the first comma). New pictures replace all the old ones. image: multipart file(s), or URL / asset path string(s); up to 9."},"pictures_urls":{"type":"array","items":{"type":"string"},"maxItems":9},"voice_samples":{"description":"0–3 voice samples; say whose each is in `voices`. New samples replace all the old ones. audio: multipart file(s), or URL / asset path string(s); up to 3."},"voice_samples_urls":{"type":"array","items":{"type":"string"},"maxItems":3}},"additionalProperties":false}}}},"responses":{"200":{"description":"The changed series.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.series"},"name":{"type":"string"},"premise":{"type":["string","null"]},"style":{"type":["string","null"]},"aspect":{"type":"string","enum":["16:9","9:16","1:1"]},"theme_s":{"type":"number"},"title_card":{"type":"boolean"},"cast":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":60},"what":{"type":["string","null"],"maxLength":400},"kind":{"type":"string","enum":["person","place","thing"]},"episodes":{"type":"array","items":{"type":"integer"}},"voice_what":{"type":["string","null"],"maxLength":200},"learned":{"type":["string","null"]},"pictureUrl":{"type":["string","null"],"format":"uri"},"voiceUrl":{"type":["string","null"],"format":"uri"}},"additionalProperties":true}}},"additionalProperties":true}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Changes a series: send only what changes. New `pictures` (or `voice_samples`) replace all the old ones; `remove_theme=true` drops the theme. Free, except a made theme (`theme_auto` / `theme_brief`): 36 credits."},"delete":{"summary":"Director: delete a series (episodes already made stay as your jobs)","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"{ id, object: \"director.series\", deleted }"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Deletes a series. Episodes already made stay as your jobs."}},"/director/series/{id}/picture":{"get":{"summary":"Director: one of a series' pictures","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"n","in":"query","schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"image"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. One of the series’ pictures, 1-based (`n`, default 1)."}},"/director/series/{id}/cast":{"post":{"summary":"Director: add one cast member, or change one matched by name (free)","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"description":"The name (required when saving)."},"what":{"description":"What this cast member is or looks like, up to 400 characters."},"kind":{"description":"`person`, `place` or `thing`."},"voice_what":{"description":"What their voice is like, up to 200 characters."},"picture":{"description":"A picture. image: multipart file(s), or URL / asset path string(s); up to 1."},"picture_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"voice":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 1."},"voice_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"application/json":{"schema":{"type":"object","properties":{"name":{"description":"The name (required when saving)."},"what":{"description":"What this cast member is or looks like, up to 400 characters."},"kind":{"description":"`person`, `place` or `thing`."},"voice_what":{"description":"What their voice is like, up to 200 characters."},"picture":{"description":"A picture. image: multipart file(s), or URL / asset path string(s); up to 1."},"picture_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"voice":{"description":"audio: multipart file(s), or URL / asset path string(s); up to 1."},"voice_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"200":{"description":"The whole series.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.series"},"name":{"type":"string"},"premise":{"type":["string","null"]},"style":{"type":["string","null"]},"aspect":{"type":"string","enum":["16:9","9:16","1:1"]},"theme_s":{"type":"number"},"title_card":{"type":"boolean"},"cast":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":60},"what":{"type":["string","null"],"maxLength":400},"kind":{"type":"string","enum":["person","place","thing"]},"episodes":{"type":"array","items":{"type":"integer"}},"voice_what":{"type":["string","null"],"maxLength":200},"learned":{"type":["string","null"]},"pictureUrl":{"type":["string","null"],"format":"uri"},"voiceUrl":{"type":["string","null"],"format":"uri"}},"additionalProperties":true}}},"additionalProperties":true}}}},"400":{"description":"invalid_request (name 60, what 400, voice_what 200)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. Adds one cast member, or changes one matched by `name` (1–60 characters): `what` (up to 400), `kind` (`person`, `place` or `thing`), a `picture`, a `voice` (5–15 s of them speaking) and `voice_what` (up to 200). Answers with the whole series."}},"/director/series/{id}/cast/{name}":{"delete":{"summary":"Director: remove a cast member, or only their picture or voice","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"name","in":"path","required":true,"description":"The cast member’s name (URL-encoded).","schema":{"type":"string","maxLength":60}},{"name":"part","in":"query","schema":{"type":"string","enum":["picture","voice"]}}],"responses":{"200":{"description":"The whole series.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.series"},"name":{"type":"string"},"premise":{"type":["string","null"]},"style":{"type":["string","null"]},"aspect":{"type":"string","enum":["16:9","9:16","1:1"]},"theme_s":{"type":"number"},"title_card":{"type":"boolean"},"cast":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":60},"what":{"type":["string","null"],"maxLength":400},"kind":{"type":"string","enum":["person","place","thing"]},"episodes":{"type":"array","items":{"type":"integer"}},"voice_what":{"type":["string","null"],"maxLength":200},"learned":{"type":["string","null"]},"pictureUrl":{"type":["string","null"],"format":"uri"},"voiceUrl":{"type":["string","null"],"format":"uri"}},"additionalProperties":true}}},"additionalProperties":true}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Removes a cast member, or only their picture or voice (`?part=picture` / `?part=voice`). Answers with the whole series."}},"/director/series/{id}/cast/{name}/{part}":{"get":{"summary":"Director: a cast member's picture or voice sample","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"name","in":"path","required":true,"description":"The cast member’s name (URL-encoded).","schema":{"type":"string","maxLength":60}},{"name":"part","in":"path","required":true,"schema":{"type":"string","enum":["picture","voice"]}}],"responses":{"200":{"description":"image or audio"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. A cast member’s `picture` or `voice` sample. The name is URL-encoded."}},"/director/filters":{"get":{"summary":"Director: the colour filters packaging can lay over a video (filter, filter_strength, vignette; free)","tags":["Director"],"responses":{"200":{"description":"The filters and their looks"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. The colour filters packaging can lay over a video, with their looks: sepia, black_and_white, noir, vintage, faded, warm, cool, vivid, cinematic, dreamy. Use them as `filter` with `filter_strength` (0–1) and `vignette` (0–1)."}},"/director/looks":{"post":{"summary":"Director: measure the look of a reference (picture, video or job_id), say the closest filter and save it; use the id as package look_id (free)","tags":["Director"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"picture":{"description":"A picture. image: multipart file(s), or URL / asset path string(s); up to 1."},"picture_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}},"application/json":{"schema":{"type":"object","properties":{"job_id":{"description":"A finished Director job id from this API (409 `conflict` if it has not finished, 404 if it is not yours)."},"picture":{"description":"A picture. image: multipart file(s), or URL / asset path string(s); up to 1."},"picture_urls":{"type":"array","items":{"type":"string"},"maxItems":1},"video":{"description":"A video to work on, instead of `job_id`. video: multipart file(s), or URL / asset path string(s); up to 1."},"video_urls":{"type":"array","items":{"type":"string"},"maxItems":1}},"additionalProperties":false}}}},"responses":{"201":{"description":"{ id, object: \"director.look\", closest filter, measurements }"},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (job_id)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. Measures the look of a reference (a `picture`, a `video`, or `job_id`: one of your finished jobs), says which filter it is closest to and saves it. Use the returned `id` (`look_…`) as `look_id` in packaging to give any video that look. Only your own looks work."}},"/director/looks/{id}":{"get":{"summary":"Director: one of your measured looks","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"description":"A look id from POST /director/looks (look_…).","schema":{"type":"string"}}],"responses":{"200":{"description":"The look"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. One of your measured looks (`look_…`). 404 for a look measured on another account."}},"/director/jobs/{id}/filter_preview":{"get":{"summary":"Director: one frame of a finished job as a JPEG with a filter (or all side by side) or a matched look (free, about a second)","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"filter","in":"query","schema":{"type":"string"}},{"name":"filter_strength","in":"query","schema":{"type":"number","minimum":0,"maximum":1}},{"name":"vignette","in":"query","schema":{"type":"number","minimum":0,"maximum":1}},{"name":"t","in":"query","schema":{"type":"number","minimum":0}},{"name":"look_id","in":"query","schema":{"type":"string"}},{"name":"look_from_job","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"image/jpeg"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free, about a second. One frame (at `t` seconds) of one of your finished jobs as a JPEG, with a `filter` (or `filter=all` for every filter side by side), a matched look (`look_id` or `look_from_job`), `filter_strength` and `vignette`. Try looks here before packaging the whole video. 409 `conflict` if the job has not finished."}},"/director/jobs/{id}/shots":{"get":{"summary":"Director: the shots of a finished video, with thumbnails (free); cut them with POST .../edit","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. The shots of a finished video (its hard cuts): `{ object: \"list\", jobId, fps, data: [{ shot, startSeconds, endSeconds, seconds, thumbnailUrl }] }`. Use the shot numbers with POST /director/jobs/{id}/edit. 409 `conflict` until the job is done."}},"/director/jobs/{id}/shots/{n}":{"get":{"summary":"Director: one shot thumbnail (JPEG), 1-based","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"n","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"image/jpeg"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. One shot’s thumbnail (JPEG), 1-based."}},"/director/jobs/{id}/poster":{"get":{"summary":"Director: a small still of a finished video (JPEG, at most 480 px), for thumbnails","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"image/jpeg"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (not finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/director/jobs/{id}/storyboard":{"get":{"summary":"Director: a film's storyboard (storyboard: true): every shot's text and still, waiting while it waits for approval (free)","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (no storyboard on this job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. The storyboard of a film started with `storyboard: true` and an `idea`: `{ object: \"director.storyboard\", jobId, waiting, stills, sheetUrl, storyboard }`, every shot’s text with a link to its still. `waiting` is true while it waits for your approval. 404 if the job has no storyboard."}},"/director/jobs/{id}/storyboard/sheet.jpg":{"get":{"summary":"Director: the storyboard contact sheet (JPEG)","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (no storyboard on this job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. Every storyboard still on one contact sheet (JPEG)."}},"/director/jobs/{id}/storyboard/{clip}/{shot}":{"get":{"summary":"Director: one storyboard still (PNG), 1-based","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"clip","in":"path","required":true,"schema":{"type":"integer","minimum":1}},{"name":"shot","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (no storyboard on this job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. One storyboard still (PNG), by clip and shot, both 1-based."}},"/director/jobs/{id}/storyboard/redo":{"post":{"summary":"Director: draw one still again; a note has the writer rewrite that shot first (charged: setPicture, plus storyboardNote with a note)","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["clip","shot"],"properties":{"clip":{"type":"integer","minimum":1},"shot":{"type":"integer","minimum":1},"note":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (no storyboard on this job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"JSON body `{ clip, shot, note? }` (clip 1–28, shot 1–12, note up to 500 characters). Draws that still again; with a `note` the writer first rewrites that shot and the film follows the new shot. Price: 25 credits, plus 16 with a note; held first, charged when the studio takes it, given back if it refuses (402 when short). Answers with the storyboard once the new still is ready."}},"/director/jobs/{id}/storyboard/approve":{"post":{"summary":"Director: render the film as storyboarded; answers with the job","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (no storyboard on this job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Renders the film as storyboarded and answers with the job; poll it as usual. The stills are counted first: the job then settles at its quote with the storyboard allowance replaced by the stills actually drawn."}},"/director/jobs/{id}/song/rebuild":{"post":{"summary":"Director: rebuild a Montage Premium music video’s version with your original song; answers with the job","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found (no storyboard on this job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. For a finished Montage Premium music video: makes its version with your original song again, re-timed onto the song shot by shot, and replaces the `withOriginalSong` link when done. The job’s `songRebuild` goes `running`, then `done` or `failed`; poll the job. 409 for any other job."}},"/director/jobs/{id}/pictures/{n}":{"get":{"summary":"Director: one reference picture a film or music video used (yours or designed)","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"n","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":40}}],"responses":{"200":{"description":"image"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. One reference picture (1–40) a film or music video used, in <Picture n> order: your own and the ones the studio designed. The job’s `pictures` list says which is which."}},"/director/queue":{"get":{"summary":"Director: your waiting and rendering jobs with their place in line","tags":["Director"],"responses":{"200":{"description":"{ object: \"list\", data: DirectorJob[] } (oldest first)"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Free. Your own jobs that are waiting or rendering, oldest first, each with `queue.ahead` (jobs in front of it; 0 once rendering) and `queue.estimatedCompletionAt`. Other accounts’ jobs are never shown."}},"/director/jobs/{id}":{"get":{"summary":"Director: get a job (synced with the studio on read)","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The job.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"One job, synced with the studio on read, so polling it moves it along. `status` is `queued`, `running`, `done`, `failed` or `cancelled` and nothing else (a film waiting for storyboard approval stays `running` with `storyboard.waiting: true`). `stage` is a plain-words step (\"Waiting to start\", \"3 of 12 parts done\", \"Sharpening\", \"Finishing the cut\", \"Cancelling\"…). When done, `output.url` is a signed URL valid 6 hours and `output.assetPath` the durable copy in your assets. `credits.quoted` was held at the start; `credits.charged` is what was settled. Poll every 10–30 s; on a timeout keep polling the same id rather than starting again."},"delete":{"summary":"Director: cancel a job (finished parts are still charged)","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The cancelled job.","content":{"application/json":{"schema":{"type":"object","required":["id","object","endpoint","status","credits"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"director.job"},"endpoint":{"type":"string","example":"videos/music"},"status":{"type":"string","enum":["queued","running","done","failed","cancelled"]},"stage":{"type":"string","example":"3 of 12 parts done"},"cancelRequested":{"type":"boolean","description":"A cancel was accepted and lands at the end of the current render step."},"progress":{"type":"number","minimum":0,"maximum":1},"etaSeconds":{"type":["number","null"]},"queue":{"type":["object","null"],"description":"Only while waiting or rendering. Your own place in line; other jobs are never shown.","properties":{"ahead":{"type":"integer","description":"Jobs waiting in front of this one; 0 once rendering."},"estimatedCompletionAt":{"type":["string","null"],"format":"date-time"}}},"credits":{"type":"object","properties":{"quoted":{"type":"integer","description":"Reserved when the job started."},"charged":{"type":"integer","description":"Settled: the quote when done, finished parts only when stopped."}}},"output":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["video","image","audio"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string","description":"Durable path in your Pixio assets."},"generationId":{"type":["string","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"qa":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"ok":{"type":["boolean","null"]},"lipSync":{"type":["number","null"]},"borders":{"type":"integer"},"blendedFrames":{"type":"integer"},"fightStillShots":{"type":"integer","description":"Films: shots where a planned blow stays nearly still for 1.5 s or more. Never fails a film."}}}},"result":{"type":["object","null"],"description":"music/plan and prompts/write: the plan or the written clips.","additionalProperties":true},"error":{"type":["string","null"]},"deliverables":{"type":"array","description":"Packaging only: the other frame shapes and cutdowns, each copied into your assets.","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string","example":"6s_9x16"},"aspect":{"type":["string","null"],"example":"9:16"},"cutdownSeconds":{"type":["number","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]},"url":{"type":"string","format":"uri","description":"Signed URL, valid 6 hours."},"assetPath":{"type":"string"}}}},"qaIssues":{"type":"array","description":"Films and music videos with visual_qa: clones, extra faces and unwanted on-screen text found after rendering. Notes only; reshoot a part with .../{id}/redo.","items":{"type":"object","properties":{"type":{"type":["string","null"]},"part":{"type":["integer","null"]},"timeSeconds":{"type":["number","null"]},"severity":{"type":["string","null"]},"evidence":{"type":["string","null"]},"suggestedFix":{"type":["string","null"]},"checkByEye":{"type":"boolean"}}}},"faceFixJobId":{"type":["string","null"],"description":"With face_fix \"auto\": the face fix the studio started for drifted sections, billed per fixed section like videos/facefix."},"packageJobId":{"type":["string","null"],"description":"Single shots with `brand_id` / `package`: the packaging job the studio started when the clip was done. Its credits were held when the shot started; poll it for the packaged video and `deliverables`."},"pictures":{"type":"array","description":"Films and music videos: every reference picture used, in <Picture n> order, yours and the ones the studio designed, each with a Pixio url.","items":{"type":"object","properties":{"number":{"type":"integer"},"tag":{"type":"string"},"designed":{"type":"boolean"},"what":{"type":["string","null"]},"url":{"type":"string"}}}},"faceFixReport":{"type":"array","description":"Face fixes: per re-rendered section, likeness before and after, the change, and whether it is visible (a change under 0.05 is not). Face fix handles one face per shot.","items":{"type":"object","properties":{"section":{"type":["integer","null"]},"likenessBefore":{"type":["number","null"]},"likenessAfter":{"type":["number","null"]},"change":{"type":["number","null"]},"visible":{"type":["boolean","null"]},"note":{"type":["string","null"]}}}},"durationShort":{"type":"object","description":"Songs (music/generate) that came back shorter than asked: requestedSeconds and actualSeconds. The song ends when its structure is complete; add sections or tags to the lyrics for a longer one.","properties":{"requestedSeconds":{"type":"number"},"actualSeconds":{"type":"number"}}},"packageSkipped":{"type":"string","description":"Why a requested packaging was not made (the hold was given back)."},"versionJobIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Films with `variants`: the other versions, each its own job (billed like this one)."},"versionOf":{"type":["string","null"],"description":"On an extra version: the job it was made with."},"sourceJobId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Cancels a queued or running job and answers with it. A cancel lands at the end of the current render step (`cancelRequested: true`, stage \"Cancelling\" until then). Finished clips or sections (plus any writing) are still charged; the rest of the hold goes back. Cancelling a finished job changes nothing."}},"/director/jobs/{id}/parts/{part}":{"get":{"summary":"Director: stream one clip or section (Range supported)","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"part","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":28}}],"responses":{"200":{"description":"video/mp4"},"206":{"description":"Partial content"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Streams one 15 s clip or section (1-based, 1–28) of a music video or film as video/mp4, as soon as it is rendered, even while the rest is still going. Supports Range requests (206), so it plays in a <video> element. 404 until that part is ready; 400 `invalid_request` for a part outside 1–28."}},"/director/jobs/{id}/video":{"get":{"summary":"Director: redirect to the finished video","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"302":{"description":"Signed URL"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (not done yet)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Redirects (302) to a fresh signed URL for the finished video in your assets. 409 `conflict` until the job is done; 404 if the job does not make a video."}},"/director/jobs/{id}/image":{"get":{"summary":"Director: redirect to the finished image","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"302":{"description":"Signed URL"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (not done yet)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Redirects (302) to a fresh signed URL for the finished image in your assets. 409 `conflict` until the job is done; 404 if the job does not make an image."}},"/director/jobs/{id}/audio":{"get":{"summary":"Director: redirect to the finished audio","tags":["Director"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"302":{"description":"Signed URL"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"conflict (not done yet)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Redirects (302) to a fresh signed URL for the finished song in your assets. 409 `conflict` until the job is done; 404 if the job does not make audio."}},"/guide":{"get":{"summary":"Agent guide in Markdown or JSON","security":[],"responses":{"200":{"description":"Protocol guide"}}}},"/openapi.json":{"get":{"summary":"OpenAPI 3.1 schema for the public API","security":[],"responses":{"200":{"description":"OpenAPI document"}}}},"/capabilities":{"get":{"summary":"Supported and unsupported API surfaces, with contract links","responses":{"200":{"description":"{ authentication: { model, scopes, revocation }, contracts: { media, projects }, supported: string[], unsupported: string[] }","content":{"application/json":{"schema":{"type":"object","properties":{"authentication":{"type":"object","properties":{"model":{"type":"string"},"scopes":{"type":"boolean"},"revocation":{"type":"string"}}},"contracts":{"type":"object","properties":{"media":{"type":"string"},"projects":{"type":"string"}}},"supported":{"type":"array","items":{"type":"string"}},"unsupported":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/agent":{"post":{"summary":"Run the Pixio agent (the in-app chat agent) and stream its events","description":"The same tool-calling agent that powers Pixio Chat: generation with credit estimates, boards, canvas, editor projects, model recommendations. Keep your own history and send it back each turn. The response is a Server-Sent-Events stream (text deltas, tool calls, generation ids, completion); poll any generation id it reports with GET /generations/{id}. Requires at least 5 credits. Agent-driven generations bill like any other generation. The conversation is capped at 1,000,000 characters of message text (string content plus `text` parts).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["messages"],"properties":{"messages":{"type":"array","minItems":1,"items":{"type":"object","required":["content"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"description":"Message text, or an array of parts."}},"additionalProperties":true}}},"additionalProperties":true}}}},"responses":{"200":{"description":"Server-Sent-Events stream of agent events","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"`invalid_json` or `invalid_request` (ApiError). A body that passes that check but not the chat schema returns a plain-text 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Fewer than 5 credits. Body is `{ error }` only, with no `code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"{ error, code: \"request_too_large\", limitChars: 1000000, receivedChars } — trim older messages and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/generate":{"post":{"summary":"Generate media","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateRequest"}}}},"responses":{"200":{"description":"Idempotent replay: { contentId, status, idempotentReplay: true, createdAt, providerId?, modelId? }. Returned when the Idempotency-Key matches a generation submitted in the last 24h — the original job, not a new one. providerId and modelId are included while the model can still be resolved.","content":{"application/json":{"schema":{"type":"object","properties":{"contentId":{"type":"string"},"status":{"type":"string"},"idempotentReplay":{"type":"boolean","const":true},"createdAt":{"type":"string","format":"date-time"},"providerId":{"type":"string"},"modelId":{"type":"string"}}}}}},"202":{"description":"Generation queued: { success, message, contentId, providerId, modelId, creditsCharged, freeAllowance, notCoveredBy }","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"contentId":{"type":"string","description":"Poll GET /generations/{id} with this."},"providerId":{"type":"string","example":"pixio"},"modelId":{"type":"string"},"creditsCharged":{"type":["integer","null"],"description":"Credits this job debits when it succeeds; 0 when your plan or a daily free pool covered it. Null if it could not be read."},"freeAllowance":{"type":["object","null"],"description":"This model's daily free pool after this job, or null when the model has none for your plan.","properties":{"slug":{"type":["string","null"]},"label":{"type":["string","null"]},"dailyLimit":{"type":"integer"},"remainingToday":{"type":"integer"},"nextAllowanceAt":{"type":["string","null"],"description":"When the next free use opens (rolling window), or null when one is available now."}}},"notCoveredBy":{"type":["object","null"],"description":"Set when your plan includes this model but a setting is never free (freeExcept on /models) or a value is over the free limit (freeUpTo), so this job bills full price.","properties":{"settings":{"type":"object","additionalProperties":{"type":"string"},"example":{"resolution":"1080p"}},"message":{"type":"string"}}}}}}}},"400":{"description":"Invalid request, or a failure from the generation pipeline (all 400; branch on `code`). Codes: `invalid_json` (body is not JSON), `invalid_request` (failed validation, with `details`, or a pre-dispatch rule such as an input limit or media duration, returned unchanged), `invalid_media_url` (a media URL could not be fetched or is not allowed, or a Pixio storage path or storage URL in params belongs to another account — including its signed storage links such as a public gallery output — with message \"One or more media inputs reference a file that does not belong to this account.\"; download such a file and upload it through POST /media first, public third-party https URLs are unaffected; `error` equals the code, sentence in `message`), `invalid_idempotency_key` (`error` equals the code), `provider_error` (the model provider rejected the request; the message is sanitized and never names the provider), `model_unavailable` (\"Model is unavailable on the Pixio API.\"), `plan_restricted` (\"This model is not available on your current plan.\"), `maker_in_flight` (\"Please wait until your current Maker generation finishes before starting another.\"; wait for it, then retry), `generation_failed` (\"Generation request failed\"), `server_error` (\"Pixio Server Error. Please try again later.\" — a Pixio-side outage such as an upstream account, quota, or timeout problem; retry later).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing/invalid key (`missing_api_key`, `invalid_api_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Insufficient credits (code `insufficient_credits`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientCreditsError"}}}},"404":{"description":"`model_not_found`: the model id did not resolve (unknown, hidden, disabled, or not on your plan), or a loose id matched more than one model (\"Ambiguous Pixio API model: <id>. Use the id listed by GET /api/v1/models.\")","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"{ error, code: \"content_policy\", message, inputHint, inputsSubmitted } — rejected by a content check. The request will not succeed unchanged. `inputHint` names the input when the check identified one; `inputsSubmitted` is the search space when it did not.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentPolicyError"}}}},"429":{"description":"`concurrency_limit`: { error, code, message, concurrencyLimit, generationId, status, retryAfter } with a Retry-After header. A per-account limit on API generations running at once, shared by every key on the account — NOT a Maker daily allowance. The value is concurrencyLimit on GET /me (1 on most plans, 10 on Maker, 30 with the Agency add-on).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConcurrencyLimitError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Opt-in replay protection. A repeat with the same key returns the original generation instead of starting another, for 24h. Without it, identical requests are treated as distinct jobs on purpose."}]}},"/images":{"post":{"summary":"Clean public URL for an image (upload file or mirror URL)","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}},"application/json":{"schema":{"$ref":"#/components/schemas/ImageRequest"}}}},"responses":{"201":{"description":"{ url } — clean public URL (or { url, urls } for several)"},"400":{"description":"`invalid_json`: the body is not valid JSON (error: \"Request body must be valid JSON or multipart/form-data.\"). `invalid_request`: no file or url provided, too many items, an unparseable multipart body, or an uploaded file that is not image, video, or audio, is empty, or exceeds its cap (image 10MB, video 250MB, audio 30MB). `invalid_media_url` ({ error: \"invalid_media_url\", code: \"invalid_media_url\", message }): a URL source must be public internet media — a private or internal address, a redirect (not followed), non image/video/audio content, a file over the same caps, or a failed download is refused; the message never repeats the URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"`provider_error`: the upload service failed; the request was fine, retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/media":{"post":{"summary":"Clean public URL for ANY media (image/video/audio)","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}},"application/json":{"schema":{"$ref":"#/components/schemas/ImageRequest"}}}},"responses":{"201":{"description":"{ url } — clean public URL (or { url, urls } for several)"},"400":{"description":"`invalid_json`: the body is not valid JSON (error: \"Request body must be valid JSON or multipart/form-data.\"). `invalid_request`: no file or url provided, too many items, an unparseable multipart body, or an uploaded file that is not image, video, or audio, is empty, or exceeds its cap (image 10MB, video 250MB, audio 30MB). `invalid_media_url` ({ error: \"invalid_media_url\", code: \"invalid_media_url\", message }): a URL source must be public internet media — a private or internal address, a redirect (not followed), non image/video/audio content, a file over the same caps, or a failed download is refused; the message never repeats the URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"`provider_error`: the upload service failed; the request was fine, retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/media/resolve":{"post":{"summary":"Resolve media references stored in a project into displayable URLs","description":"Board nodes and canvas image layers persist durable storage keys rather than URLs, because a signed URL would expire while the document lives on. Send those references to get URLs you can display. Only references in your own storage resolve; already-public URLs pass through unchanged, and anything else comes back null. The returned URLs expire — display them, never write them back into project content.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["refs"],"properties":{"refs":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"{ urls: { \"<ref>\": \"https://…\" | null } } — null where the reference is not yours or not storage-backed"},"400":{"description":"Missing or oversized refs array (`invalid_request`, with `details`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/uploads":{"post":{"summary":"Upload media to user assets (stored + signed URLs)","parameters":[{"name":"collectionId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"File every upload from this request into this collection (folder) in one step. If the folder cannot be used the uploads still succeed and the failure is reported under `collection.error`."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}},"application/json":{"schema":{"$ref":"#/components/schemas/ImageRequest"}}}},"responses":{"201":{"description":"{ uploads: [{ id, sourceUrl, filePath, url, signedUrl, signedUrlExpiresAt, fileName, fileSize, contentType, mediaType }], collection? }. `id` is the asset id for the collections API. `collection` is present when ?collectionId= was sent: { id, added, skipped, error? }.","content":{"application/json":{"schema":{"type":"object","properties":{"uploads":{"type":"array","items":{"$ref":"#/components/schemas/UploadItem"}},"collection":{"type":"object","properties":{"id":{"type":"string"},"added":{"type":"integer"},"skipped":{"type":"array","items":{"type":"string"}},"error":{"type":"string"}}}}}}}},"400":{"description":"Invalid media (`invalid_media_url`; `error` equals the code, sentence in `message`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/assets":{"get":{"summary":"List your assets (uploads + generated), newest first","description":"Songcraft songs carry `paidDownload` (see the PaidDownload schema): until a download tier is paid for, the file URL is null and the song is only available from GET /assets/{id}/download?tier=preview|official.","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["image","video","audio","3d"]}},{"name":"source","in":"query","schema":{"type":"string","enum":["upload","generated"]}},{"name":"search","in":"query","schema":{"type":"string","maxLength":200},"description":"Matches upload file names, prompts, and the model name or public id."},{"name":"modelId","in":"query","schema":{"type":"string","maxLength":240},"description":"Only this model’s generations. Accepts the public id or the model name (GET /assets/models lists valid values). Uploads have no model, so they are excluded whenever this is set."},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"{ data: Asset[], page, limit, total, hasMore }"},"400":{"description":"Invalid query parameters (`invalid_request`, with `details`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"summary":"Upload media into your assets (alias of /uploads)","description":"Same body and response as POST /uploads, without the `collectionId` shortcut: use POST /uploads?collectionId=… or POST /assets/collections/{id}/items to file the result.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}},"application/json":{"schema":{"$ref":"#/components/schemas/ImageRequest"}}}},"responses":{"201":{"description":"{ uploads: [{ id, sourceUrl, filePath, url, signedUrl, signedUrlExpiresAt, fileName, fileSize, contentType, mediaType }] }","content":{"application/json":{"schema":{"type":"object","properties":{"uploads":{"type":"array","items":{"$ref":"#/components/schemas/UploadItem"}}}}}}},"400":{"description":"Invalid media (`invalid_media_url`; `error` equals the code, sentence in `message`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"summary":"Bulk-delete assets you own","parameters":[{"name":"ids","in":"query","schema":{"type":"string"},"description":"Comma-separated ids (or send JSON { ids })"},{"name":"source","in":"query","schema":{"type":"string","enum":["upload","generated"]}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"},"maxItems":100},"source":{"type":"string","enum":["upload","generated"]}}}}}},"responses":{"200":{"description":"{ deletedCount, deleted: [...], notFound: [...] }"},"400":{"description":"No ids provided (`invalid_request`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/assets/models":{"get":{"summary":"Models that produced assets in your library, with counts","description":"The list a \"filter by model\" control is built from. Only models with assets appear. Pass a returned `modelId` to GET /assets?modelId=… to filter.","responses":{"200":{"description":"{ data: [{ modelId, name, company, count }] }","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"modelId":{"type":"string"},"name":{"type":"string"},"company":{"type":["string","null"]},"count":{"type":"integer"}}}}}}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Failed to load (`internal_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/styles":{"get":{"summary":"Style gallery as data: prompt styles (append) and viral templates (replace, with a generate-ready recipe)","parameters":[{"name":"kind","in":"query","schema":{"type":"string","enum":["image","video","3d"]}},{"name":"category","in":"query","description":"e.g. viral, cinematic, motion","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"{ data: [{ id, label, category, applies, promptMode, tokens, recipe, sampleUrl }], total }"},"400":{"description":"Invalid query parameters (`invalid_request`, with `details`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/voices":{"get":{"summary":"Text-to-speech voices by name: premade, library, and your own clones, each with the params to use it","description":"Merge a voice's `use` into `POST /generate` `params`. Library voices use `{ voice_id }`; your clones use `{ voice_id: \"custom\", audio_voice_clone_asset }`. With `search`, ElevenLabs shared-library matches are included with `use: null` and an `add` body for `POST /voices/add`. Exact name matches come first.","parameters":[{"name":"provider","in":"query","schema":{"type":"string","enum":["elevenlabs","cartesia"]}},{"name":"category","in":"query","schema":{"type":"string","enum":["premade","library","cloned"]}},{"name":"search","in":"query","description":"Matches name, id, accent, language, and description","schema":{"type":"string","maxLength":100}},{"name":"page","in":"query","description":"1-based page number","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","description":"Page size","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"`total` counts every match; keep requesting `page + 1` while `hasMore` is true. `unavailable` names providers that could not be reached","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Voice"}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"hasMore":{"type":"boolean"},"unavailable":{"type":"array","items":{"type":"string","enum":["elevenlabs","cartesia"]}}}}}}},"400":{"description":"Invalid query parameters (`invalid_request`, with `details`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (`missing_api_key`, `invalid_api_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Failed to load voices (`internal_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Every requested voice provider is unavailable (`provider_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/voices/add":{"post":{"summary":"Make an ElevenLabs shared-library voice usable for text-to-speech","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["voiceId","publicOwnerId"],"description":"The `add` object from a `GET /voices` hit","properties":{"voiceId":{"type":"string"},"publicOwnerId":{"type":"string"},"name":{"type":"string","minLength":1,"maxLength":100}}}}}},"responses":{"200":{"description":"The voice is ready to use","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string","enum":["elevenlabs"]},"use":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"400":{"description":"Invalid body (`invalid_json`, `invalid_request`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (`missing_api_key`, `invalid_api_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Shared voice not found (`not_found`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Could not add the voice (`provider_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/assets/collections":{"get":{"summary":"List your asset collections (folders)","responses":{"200":{"description":"{ data: Collection[] }"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"summary":"Create a collection","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"parentId":{"type":"string","format":"uuid","nullable":true,"description":"Omit or null for a top-level collection"},"color":{"type":"string","nullable":true}}}}}},"responses":{"201":{"description":"Collection"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"A sibling collection already has that name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/assets/collections/{id}":{"get":{"summary":"Fetch one collection","responses":{"200":{"description":"Collection"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"summary":"Rename, recolour, or re-parent a collection","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"parentId":{"type":"string","format":"uuid","nullable":true,"description":"null moves it to the top level"},"color":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"Collection"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"A sibling collection already has that name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"summary":"Delete a collection (sub-collections cascade; assets are kept)","responses":{"200":{"description":"{ id, deleted: true }"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/assets/collections/{id}/items":{"get":{"summary":"List the assets filed in this collection, newest first","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"{ data: Asset[], page, limit, total, hasMore }"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"summary":"File assets into a collection","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["assetIds"],"properties":{"assetIds":{"type":"array","maxItems":100,"items":{"type":"string","format":"uuid"},"description":"Uploads or generated content; ids you do not own are returned in skipped"}}}}}},"responses":{"200":{"description":"{ added: number, skipped: string[] }"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"summary":"Unfile assets from a collection (accepts ?ids=a,b,c or a JSON body)","parameters":[{"name":"ids","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"{ removed: number }"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/assets/{id}/download":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"source","in":"query","schema":{"type":"string","enum":["upload","generated"]}},{"name":"redirect","in":"query","schema":{"type":"string","enum":["true","false"]},"description":"302 straight to the file when true"}],"get":{"summary":"Signed attachment download URL for an asset","description":"Songcraft songs: ?tier=preview (100 credits, default) or ?tier=official (300 credits, the official commercial MP3). Each tier is charged once per song; re-downloads are free.","responses":{"200":{"description":"{ url, expiresAt, fileName, creditsCharged }"},"302":{"description":"Redirect to file (when redirect=true)"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Insufficient credits for a Songcraft song download (preview 100 / official 300)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/assets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"source","in":"query","schema":{"type":"string","enum":["upload","generated"]}}],"get":{"summary":"Get one asset with a signed URL","responses":{"200":{"description":"Asset"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"summary":"Delete an asset you own","responses":{"200":{"description":"{ deleted, id, source }"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"summary":"Rename an asset (uploads only)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated asset"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Generated assets cannot be renamed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/params":{"get":{"summary":"Inputs for one model","parameters":[{"name":"modelId","in":"query","required":true,"schema":{"type":"string"}},{"name":"providerId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"{ model, params, outputs }. `outputs` says what the model returns: { format: \"json\" | \"file\", hasFileUrl }. Structured-result models (transcription) answer with format \"json\" and no output file URL.","content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"object","additionalProperties":true},"params":{"type":"array","items":{"type":"object","additionalProperties":true}},"outputs":{"$ref":"#/components/schemas/ModelOutputs"}}}}}},"400":{"description":"Missing modelId (`invalid_request`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found (`model_not_found`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/generations":{"get":{"summary":"List your generations (all statuses), newest first","description":"Songcraft songs carry `paidDownload` (see the PaidDownload schema): until a download tier is paid for, the file URL is null and the song is only available from GET /assets/{id}/download?tier=preview|official.","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","processing","succeeded","failed"]}},{"name":"type","in":"query","schema":{"type":"string","enum":["image","video","audio","3d"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"{ data: Generation[], page, limit, total, hasMore } Each item includes `creditsCost` (quoted) and `billedAt` (null unless credits were debited). `params` echoes your inputs without internal bookkeeping keys, and `error` is a sanitized sentence that never names a provider."},"400":{"description":"Invalid query parameters (`invalid_request`, with `details`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/generations/estimate":{"post":{"summary":"What this request will cost, measured the way it bills","description":"Runs the same pre-dispatch measurement and rounding that charges for the generation. For a model billed per second of a file you supply, the file is measured here exactly as it will be at generation time.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateRequest"}}}},"responses":{"200":{"description":"{ success, modelId, currency, quote, baseCost, estimatedCost, pricing, note? }. `success` is always true. `pricing` is the model’s billing basis (rate, rateUnit, rounding, measured, …). `note` appears only for a model billed per second of a file you supply, and spells out the rate. `quote.status` is \"measured\" when the billed quantity came from your file, or \"provisional\" when it came from a rule default or a durationSeconds hint — `quote.provisionalReason` says which. `quote` also carries billingUnit, rate, rounding, minimumCredits (a floor on the total, not on the quantity), maximumUnits (a ceiling on the billed quantity), measured.decodedSeconds (the raw value the rounding was applied to), billedUnits, listCost, planDiscount, allowance (including nextAllowanceAt), expectedDebit, and notCoveredBy when a never-free setting (freeExcept on /models) makes it bill full price. `baseCost`/`estimatedCost` are retained for older callers and equal quote.listCost / quote.expectedDebit.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"modelId":{"type":"string"},"currency":{"type":"string","const":"credits"},"quote":{"type":"object","additionalProperties":true},"baseCost":{"type":"number"},"estimatedCost":{"type":"number"},"pricing":{"type":"object","additionalProperties":true},"note":{"type":"string"}}}}}},"400":{"description":"`invalid_json` or `invalid_request` with `details` (the body failed validation), or { error: \"invalid_request\", code: \"invalid_request\", message } — the params or media cannot be billed as sent, e.g. a clip over the model limit. The same rejection you would get from /generate, before submitting. { error: \"invalid_media_url\", code: \"invalid_media_url\", message: \"One or more media inputs reference a file that does not belong to this account.\" } when a Pixio storage path or storage URL in params belongs to another account (including its signed storage links, such as a public gallery output); download it and upload it through POST /media first. Public third-party https URLs are unaffected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Model not found (`model_not_found`), or a loose id matched more than one model (\"Ambiguous Pixio API model: <id>. Use the id listed by GET /api/v1/models.\")","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Estimate failed (`internal_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/generations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Poll a generation","responses":{"200":{"description":"Generation status + output, plus `billing` and `media`. `params` echoes your inputs without internal bookkeeping keys (internal keys are withheld). `error` is a sanitized sentence that never names a provider or carries a raw upstream body. `billing` = { settledCost, refundedCredits, billedAt, ledger: { entryIds, matchedBy } }: `matchedBy` is \"source_id\" when the ledger movement carries a direct link, \"timestamp\" when it was matched on billing time and amount (a probable match, not proof), or \"none\". `media` = { input, billedSeconds, rounding } for per-second models — use POST /generations/estimate on the same file to see the decoded value it was rounded up from. `billedAt` is set only once credits were actually debited (failed runs stay null). Songcraft songs carry `paidDownload` (see the PaidDownload schema): until a download tier is paid for, the file URL is null and the song is only available from GET /assets/{id}/download?tier=preview|official."},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"summary":"Delete a generation you own","description":"Deletes the record and its stored output. It does NOT stop provider work already in flight and does NOT avoid or reverse a charge — deletion and cancellation are different operations.","responses":{"200":{"description":"{ deleted, id }"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/models":{"get":{"summary":"List models","description":"Every `id` listed here always resolves to the listed model on /generate, /generations/estimate, and the other model-taking routes; send it verbatim. A loose or partial id that matches more than one model is 404 `model_not_found` (\"Ambiguous Pixio API model: <id>. Use the id listed by GET /api/v1/models.\"). The `modelId` returned on generations, assets, and the prompt library is this canonical id and can be passed back to /generate.","parameters":[{"name":"modelId","in":"query","schema":{"type":"string"},"description":"Optional full public model id; when set, returns { model } instead of { models }."}],"responses":{"200":{"description":"{ models: [{ id, providerId, name, description, type, credits, defaultCredits, fromCredits, pricing, company, freeForPlans, freeForCurrentPlan, makerCap, freeExcept, freeUpTo, inputs }] }. `credits` is the raw catalog price: exact only for a flat-priced model, a rate for a per-second model, a floor for an option-priced one. `defaultCredits` is what a request with no params costs: budget against it. `fromCredits` is the cheapest option combination, or null where options do not drive the price. `pricing` is the billing basis (rate, rateUnit, rounding). `freeForCurrentPlan` says whether your plan pays the list price, `makerCap` names the daily free-use pool (see /me makerCaps) or is null, `freeExcept` lists settings that are never free even then (e.g. { resolution: [\"1080p\"] }), and `freeUpTo` gives numeric limits on the free allowance (e.g. { audio_duration_seconds: 30 }, measured server-side); each is null when nothing applies or your plan pays for the model anyway."},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"modelId given but not found (`model_not_found`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/models/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Full public id, e.g. pixio/flux/dev. Slash-delimited ids are captured as a catch-all route."}],"get":{"summary":"Model detail + inputs","responses":{"200":{"description":"{ model, params, outputs }. `outputs` says what the model returns: { format: \"json\" | \"file\", hasFileUrl }. Structured-result models (transcription) answer with format \"json\" and no output file URL.","content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"object","additionalProperties":true},"params":{"type":"array","items":{"type":"object","additionalProperties":true}},"outputs":{"$ref":"#/components/schemas/ModelOutputs"}}}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found (`model_not_found` or `not_found`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/models/favorites":{"get":{"summary":"List your favorite models","description":"The same list the star buttons in the app’s model selector maintain. Ids are public pixio/... ids; favorites for models your plan cannot see, or that left the catalog, are omitted.","responses":{"200":{"description":"{ data: [{ modelId, name, type, createdAt }] }, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"modelId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Failed to load (`internal_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"summary":"Favorite a model (idempotent)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["modelId"],"properties":{"modelId":{"type":"string","maxLength":200,"description":"Public pixio/... model id."}}}}}},"responses":{"201":{"description":"{ modelId, favorited: true }","content":{"application/json":{"schema":{"type":"object","properties":{"modelId":{"type":"string"},"favorited":{"type":"boolean","const":true}}}}}},"400":{"description":"Body missing or not valid (`invalid_request`, with `details`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Model not found (`model_not_found`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Failed to save (`internal_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"summary":"Remove a favorite model","parameters":[{"name":"modelId","in":"query","required":true,"schema":{"type":"string"},"description":"Public pixio/... model id."}],"responses":{"200":{"description":"{ modelId, favorited: false }","content":{"application/json":{"schema":{"type":"object","properties":{"modelId":{"type":"string"},"favorited":{"type":"boolean","const":false}}}}}},"400":{"description":"Missing modelId (`invalid_request`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Failed to remove (`internal_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/pricing":{"get":{"summary":"Live price list for your account","description":"Every model you can reach with both the list price and what YOU are charged, plus plan and credit-pack prices. Prices move with the catalog, so read this rather than caching a copy.","parameters":[{"name":"type","in":"query","schema":{"type":"string"},"description":"Optional model type filter, e.g. text-to-image, image-to-video."},{"name":"modelId","in":"query","schema":{"type":"string"},"description":"Optional full public model id; returns only that model, or 404."}],"responses":{"200":{"description":"{ generatedAt, currency, account: { plan, credits }, usdPerCredit, plans: [...], creditPacks: [...], dailyFreePools: [...], models: [{ id, name, type, company, listCredits, yourCredits, fromCredits, pricedFromParams, free, freeReason, discountPercent, creditsAfterPool, pricing, yourRate, freeForPlans, freeForCurrentPlan, makerCap, freeExcept, freeUpTo }], notes }. `yourCredits` is the charge at the pricing rule defaults; when `pricing.rate` is set it quotes `yourRate` credits per `pricing.rateQuantity` of `pricing.rateUnit`. Unit rules round quantity / rateQuantity with `pricing.rounding` before multiplying and apply `pricing.minCredits`. Generation means one request including its outputs. Use /generations/estimate for exact quotes including options and addons. `fromCredits` is the cheapest option combination, set only where options drive the price. `pricedFromParams` marks a model whose price comes entirely from what you send, so its 0 is an empty request rather than a free model."},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Unknown modelId (`model_not_found`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Failed to load pricing (`internal_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/credits":{"get":{"summary":"Account credit balance","responses":{"200":{"description":"Credits"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/credits/ledger":{"get":{"summary":"Credit ledger entries (top-ups, debits, refunds)","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"generationId","in":"query","schema":{"type":"string","format":"uuid"},"description":"Only movements linked to this generation."}],"responses":{"200":{"description":"{ entries: [{ id, reason, deltaRecurring, deltaPermanent, sourceId, generationId, debitedCredits, creditedCredits, createdAt }], hasMore }. `debitedCredits` and `creditedCredits` split what moved by direction; a positive entry is usually a top-off or credit pack, not a refund. `generationId` (same value as `sourceId`) is null where no link was recorded against the movement — that means unlinked, not unbilled. `hasMore` is true when older entries exist beyond `limit`.","content":{"application/json":{"schema":{"type":"object","required":["entries","hasMore"],"properties":{"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"reason":{"type":"string"},"deltaRecurring":{"type":"number"},"deltaPermanent":{"type":"number"},"sourceId":{"type":["string","null"]},"generationId":{"type":["string","null"]},"debitedCredits":{"type":"number"},"creditedCredits":{"type":"number"},"createdAt":{"type":"string","format":"date-time"}}}},"hasMore":{"type":"boolean"}}}}}},"400":{"description":"Invalid query parameters (`invalid_request`, with `details`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/subscription":{"get":{"summary":"Plan, add-ons, credit quota, and API concurrency limit","responses":{"200":{"description":"{ plan, addons, credits, apiConcurrencyLimit }. `addons` lists active add-ons, e.g. [\"agency\"]."},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/me":{"get":{"summary":"Identify the API key account: plan, add-ons, credits, concurrency limit, and Maker daily caps","responses":{"200":{"description":"{ id, name, email, pictureUrl, createdAt, plan, credits: { recurring, recurringQuota, permanent, total }, concurrencyLimit, addons, makerCaps: [{ slug, label, dailyLimit, usedToday, remainingToday, rollingWindowSeconds, nextAllowanceAt }] }. `addons` lists active add-ons on top of `plan`, e.g. [\"agency\"]. `nextAllowanceAt` is when the next free use frees up in that pool’s rolling window, or null. `makerCaps` is empty off the Maker plan.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"pictureUrl":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"plan":{"type":"string"},"credits":{"type":"object","properties":{"recurring":{"type":"number"},"recurringQuota":{"type":"number"},"permanent":{"type":"number"},"total":{"type":"number"}}},"concurrencyLimit":{"type":"integer"},"addons":{"type":"array","items":{"type":"string","enum":["agency"]}},"makerCaps":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"label":{"type":"string"},"dailyLimit":{"type":"integer"},"usedToday":{"type":"integer"},"remainingToday":{"type":"integer"},"rollingWindowSeconds":{"type":"integer"},"nextAllowanceAt":{"type":["string","null"],"format":"date-time","description":"When the next free use in this pool frees up, or null."}}}}}}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/prompts/optimize":{"get":{"summary":"Optimizer configuration: message types (model-family prompts), modes, limits","responses":{"200":{"description":"{ messageTypes: [{ type, label }], modes: [\"standard\",\"screenplay\"], legacyTypes, limits: { maxAttachments, maxPromptChars, creditsPerCall } }"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"summary":"Optimize a prompt with the full app optimizer (model-family prompts, screenplay mode, attachments, grounding)","description":"Costs 5 credits per call (`limits.creditsPerCall`), debited only after validation passes (prompt present, messageType exists, every attachment resolves and is an allowed size and type), immediately before the model call. Validation failures (400s, unknown messageType, bad attachment, optimizer not configured) are not charged; a model failure after the charge (502) is not refunded. Success bodies carry `cost: { credits }`. An account that cannot cover it gets 402 `insufficient_credits`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"Your idea. Optional only when attachments are sent."},"messageType":{"type":"string","description":"Model-family system prompt, e.g. flux, midjourney, video, seedance-long, suno. GET this path for the list. Defaults from `type`."},"mode":{"type":"string","enum":["standard","screenplay"]},"attachments":{"type":"array","maxItems":6,"items":{"type":"string"},"description":"Public URLs or storage keys you own: images, audio, video, PDF, Markdown, text. Used as source material. A URL must be a public internet address pointing directly at the file; redirects are not followed."},"googleSearch":{"type":"boolean"},"urlContext":{"type":"boolean"},"type":{"type":"string","enum":["image","video","audio","3d"],"description":"Legacy media type; still honoured."},"context":{"type":"string"}}}}}},"responses":{"200":{"description":"Legacy body ({ prompt, type?, context? }) returns { optimizedPrompt, improvements, reasoning, cost }. Any full-optimizer field returns { optimizedPrompt, messageType, mode, model, attachmentsUsed, cost }. `cost` is { credits }: the 5 credits charged."},"400":{"description":"`invalid_json`, or `invalid_request`: unknown messageType, unresolvable or unsupported attachment, an attachment URL that is not a public internet address (\"Attachment URL is not allowed: …\") or that redirects (redirects are not followed), or neither prompt nor attachments. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"`insufficient_credits`: fewer than 5 credits. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"`optimizer_error`: the optimizer is not configured or its configuration could not be loaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"`provider_error` (standard path) or `optimizer_error` (full optimizer). A model-call failure comes after the charge and is not refunded; an attachment upload failure comes before it and is not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"504":{"description":"`optimizer_error`: the optimizer timed out processing an attachment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/assets/download":{"get":{"summary":"Batch signed attachment download URLs","description":"Songcraft songs: ?tier=preview (100 credits, default) or ?tier=official (300 credits), charged once per song; songs that could not be charged are returned under `failed`.","parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated asset ids"},{"name":"source","in":"query","schema":{"type":"string","enum":["upload","generated"]}}],"responses":{"200":{"description":"{ downloads: [{ id, url, expiresAt, fileName, creditsCharged }], notFound: [...], failed: [{ id, code, error }] }"},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/workflows":{"get":{"summary":"List saved workflows","responses":{"200":{"description":"{ workflows: [{ id, name, description, updatedAt, latestRun }] }, most recently updated first. `latestRun` is { id, status, createdAt, startedAt, finishedAt } or null.","content":{"application/json":{"schema":{"type":"object","properties":{"workflows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"updatedAt":{"type":["string","null"]},"latestRun":{"type":["object","null"],"additionalProperties":true}}}}}}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"summary":"Create a saved workflow from a definition","description":"Send the same definition JSON the app builder saves and GET /workflows/{id} returns. Internal-only params in node params are silently dropped, as on run-time overrides. Run it afterwards with POST /workflows/{id}/runs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","definition"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":["string","null"],"maxLength":2000},"definition":{"$ref":"#/components/schemas/WorkflowDefinition"}}}}}},"responses":{"201":{"description":"{ id, name, description, definition, createdAt, updatedAt }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workflow"}}}},"400":{"description":"Body missing or not valid (`invalid_request`, with `details`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Failed to create (`internal_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/workflows/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a saved workflow and its node definition","responses":{"200":{"description":"{ id, name, description, definition, createdAt, updatedAt }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workflow"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Workflow not found (`not_found`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"`invalid_workflow_definition`: the saved definition no longer validates. `error` equals the code, sentence in `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"summary":"Update a workflow’s name, description, and/or definition","description":"Internal-only params in a new definition’s node params are silently dropped, as on create.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"description":"Send at least one of name, description, definition.","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":["string","null"],"maxLength":2000},"definition":{"$ref":"#/components/schemas/WorkflowDefinition"}}}}}},"responses":{"200":{"description":"{ id, name, description, definition, createdAt, updatedAt }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workflow"}}}},"400":{"description":"Nothing to update, or a body that is not valid (`invalid_request`, with `details`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Workflow not found (`not_found`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"summary":"Delete a saved workflow (its run history goes with it)","responses":{"200":{"description":"{ deleted: true, id }","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Workflow not found (`not_found`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/workflows/{id}/runs":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Run a workflow","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string"},"negativePrompt":{"type":"string"},"overrides":{"type":"object","additionalProperties":true}}}}}},"responses":{"202":{"description":"Queued: { runId, workflowId, status: \"queued\" }. Poll GET /workflows/{id}/runs/{runId}.","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string"},"workflowId":{"type":"string"},"status":{"type":"string","const":"queued"}}}}}},"400":{"description":"`invalid_json`, `invalid_request` (with `details`), `invalid_workflow_override` (an override or its media was rejected; `error` equals the code, sentence in `message`), or `invalid_media_url` ({ error: \"invalid_media_url\", code, message: \"One or more media inputs reference a file that does not belong to this account.\" }) when the run body or the saved workflow’s nodes carry a Pixio storage path or storage URL belonging to another account, including its signed storage links such as a public gallery output. Nothing is queued; download the file and upload it through POST /media first. Public third-party https URLs are unaffected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Workflow not found (`not_found`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"`invalid_workflow_definition`: the saved definition no longer validates; open it in the editor and re-save. `error` equals the code, sentence in `message`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`concurrency_limit`: { error, code, message, concurrencyLimit, retryAfter, runId?, status? } with a Retry-After: 10 header. Same shape as POST /generate; `runId` is the running workflow run to poll. Shared with generations: every key on the account counts toward concurrencyLimit on GET /me.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConcurrencyLimitError"}}}},"502":{"description":"`workflow_dispatch_failed`: the run row exists but could not be started. The body also carries { runId, workflowId, status: \"queued\" }.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"summary":"List a workflow’s runs","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Newest first. Out-of-range values are clamped to 1..50 and non-numeric values fall back to 20; never an error."}],"responses":{"200":{"description":"{ workflowId, hasMore, runs: [{ id, status, error, createdAt, startedAt, finishedAt }] }. `hasMore` is true when older runs exist beyond `limit`. `error` is a sanitized sentence or null.","content":{"application/json":{"schema":{"type":"object","required":["workflowId","hasMore","runs"],"properties":{"workflowId":{"type":"string"},"hasMore":{"type":"boolean"},"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"error":{"type":["string","null"]},"createdAt":{"type":["string","null"]},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]}}}}}}}}},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Workflow not found (`not_found`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/workflows/{id}/runs/{runId}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Poll a workflow run","responses":{"200":{"description":"Run status + outputs[]. { id, workflowId, status, error, createdAt, startedAt, finishedAt, steps, outputs }. `error` (run and per-step) is a sanitized sentence that never names a provider."},"401":{"description":"Missing or invalid API key (code `missing_api_key` or `invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Workflow run not found (`not_found`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"API key storage unavailable (code `service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}