# Pixio API — Agent Guide

Generate AI media and run saved workflows over HTTP.

Base URL: `https://beta.pixio.myapps.ai`
Auth: every request needs `Authorization: Bearer <PIXIO_API_KEY>`.
OpenAPI: `https://beta.pixio.myapps.ai/api/v1/openapi.json`

## Generate media (the common flow)
1. **Find a model** — `GET /api/v1/models`. Ids start with `pixio/`
   (e.g. `pixio/xai/grok-imagine-video/image-to-video`).
2. **Learn its inputs** — `GET /api/v1/params?modelId=pixio/<model>` returns each
   input's name, whether it's required, allowed options, and ranges.
3. **Upload or import media** — `POST /api/v1/uploads`. Send multipart
   `file=@photo.jpg`, or JSON `{"url":"https://..."}` / `{"urls":[...]}`.
   Returns stored asset metadata including `filePath`, `url`, `signedUrl`,
   and `signedUrlExpiresAt`. Pass `filePath` or `url` into the model's file
   param (`image_url`, `video_url`, `audio_url`, …). If you specifically need
   a clean public URL with no signed query string, use `POST /api/v1/images`
   (images) or `POST /api/v1/media` (image/video/audio).
4. **Generate** — `POST /api/v1/generate` with `{ "modelId": "...", "params": { ... } }`
   → `{ "contentId": "..." }`.
5. **Poll** — `GET /api/v1/generations/{id}` until `status` is `succeeded`; read the output url(s).

### Example — photo → Grok image-to-video
```bash
# 1. upload/import media
URL=$(curl -s -X POST https://beta.pixio.myapps.ai/api/v1/uploads \
  -H "Authorization: Bearer $PIXIO_API_KEY" -F "file=@photo.jpg" | jq -r '.uploads[0].url')

# 2. generate
curl -s -X POST https://beta.pixio.myapps.ai/api/v1/generate \
  -H "Authorization: Bearer $PIXIO_API_KEY" -H "Content-Type: application/json" \
  -d "{\"modelId\":\"pixio/xai/grok-imagine-video/image-to-video\",
       \"params\":{\"image_url\":\"$URL\",\"prompt\":\"slow cinematic push-in\",\"resolution\":\"720p\"}}"
# 3. poll GET https://beta.pixio.myapps.ai/api/v1/generations/{contentId}
```

## Run a saved workflow
Workflows are a graph of model nodes run in dependency order; each node's output
is wired into a named input of the next, so multi-step pipelines (e.g. text-to-speech
→ lipsync → video) run as one call. Build one in the app editor or with
`POST /api/v1/workflows` and a definition, then drive it from the API.
1. `GET /api/v1/workflows` — your workflows + each one's latest run.
   `GET /api/v1/workflows/{id}` shows the node ids you'll target with overrides.
2. `POST /api/v1/workflows/{id}/runs` — start a run. Optional body `overrides`
   is keyed by node id and sets `prompt`, `fileUrl`, or `params` on that node for
   this run only — a TTS node takes its narration as `params.text`. Audio/video
   duration flows downstream automatically, so a lipsync step is priced correctly.
3. `GET /api/v1/workflows/{id}/runs/{runId}` — poll until `succeeded`; `outputs[]`
   has the final media URLs.

## Optimize a prompt (the full optimizer)
`POST /api/v1/prompts/optimize` is the same engine the app's Prompt Optimizer uses:
- `messageType` picks a model-family system prompt (e.g. `flux`, `midjourney`, `video`,
  `seedance-long`, `sora2-short`, `suno`, `music`, `3d-model`). `GET /api/v1/prompts/optimize`
  lists them; a Seedance prompt and a Midjourney prompt are shaped very differently.
- `mode: "screenplay"` returns a cinematic video-script treatment instead of one prompt.
- `attachments` (up to 6) are public URLs or storage keys you own — images, audio, video,
  PDF, Markdown, or text — used as source material. The model looks at them.
- `googleSearch` / `urlContext` let the optimizer ground itself in live information.
- Sending only `{ prompt, type?, context? }` runs the original optimizer and returns
  `{ optimizedPrompt, improvements, reasoning }` exactly as before. Any field above
  switches to the full optimizer, which returns `{ optimizedPrompt, messageType, mode,
  model, attachmentsUsed }`.

```bash
curl -s -X POST https://beta.pixio.myapps.ai/api/v1/prompts/optimize \
  -H "Authorization: Bearer $PIXIO_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"a blob narrator in a cozy studio, warm light",
       "messageType":"seedance-long",
       "attachments":["https://example.com/reference.png"]}'
```

## Plan, pricing, and Maker caps
- `GET /api/v1/pricing` is the whole price list, already priced for this key. Each
  model carries `listCredits` (the list price) and `yourCredits` (what you are
  actually charged, after plan discounts and plan-free models), plus `free`,
  `freeReason`, `discountPercent`, and `creditsAfterPool` — the price once today's
  free pool runs out. `pricing` says how the price is built; when it carries a
  `rate`, the model bills `yourRate` x quantity of `pricing.rateUnit`, so the single
  credit figure is only the default-quantity price. `plans`, `creditPacks`, and
  `usdPerCredit` turn credits into dollars. Prices move with the catalog — read it,
  do not cache it.
  The ten cheapest models for you:
  `curl -s https://beta.pixio.myapps.ai/api/v1/pricing -H "Authorization: Bearer $KEY" | jq '[.models[] | {id, yourCredits}] | sort_by(.yourCredits) | .[:10]'`
- `GET /api/v1/me` tells you what this key is and what it can do: `plan`, `credits`
  (`recurring`, `permanent`, `total`), `concurrencyLimit` (the parallel-generation
  ceiling behind 429s), and `makerCaps` — one entry per daily free-use pool with
  `slug`, `dailyLimit`, `usedToday`, `remainingToday`, and `rollingWindowSeconds`.
- Every model in `GET /api/v1/models` reports `credits` (list price) alongside
  `freeForPlans`, `freeForCurrentPlan`, and `makerCap` (`{ slug, label, dailyLimit,
  rollingWindowSeconds }` or `null`). A model with `freeForCurrentPlan: true` costs
  nothing while its pool has uses left; look the pool up by `slug` in `/me`.
  `freeExcept` lists settings that are never free even then, e.g.
  `{ "resolution": ["1080p"] }`: a request using one bills full price and does not
  use a free slot. An omitted setting counts as its default. It is `null` when your
  plan pays for the model anyway. `freeUpTo` sets numeric limits the same way, e.g.
  `{ "audio_duration_seconds": 30 }`: above it the run bills full price. Durations
  are measured server-side from your file.
- `POST /api/v1/generate` answers with `creditsCharged` (0 when the plan or a free
  pool covered it), `freeAllowance` (that model's pool after this job: `remainingToday`,
  `nextAllowanceAt`, or `null`), and `notCoveredBy` when a `freeExcept` setting made
  it bill full price, or a value went over `freeUpTo`. The estimate quote carries the
  same `notCoveredBy`.
  Your plan's included models in one line:
  `curl -s https://beta.pixio.myapps.ai/api/v1/models -H "Authorization: Bearer $KEY" | jq '[.models[] | select(.freeForCurrentPlan) | .id]'`
- On generations, `creditsCost` is the quoted price; `billedAt` is when credits were
  actually debited. Credits are only charged when a run reaches `succeeded`, so a
  failed run has a `creditsCost` but a `null` `billedAt`. The ledger
  (`/api/v1/credits/ledger`) is authoritative.

## Cancellation semantics
`DELETE /api/v1/generations/{id}` deletes the generation record and its stored
output. That is all it does.
- It does **not** stop provider work already in flight.
- It does **not** avoid or reverse a charge. Deletion and cancellation are
  different operations — deleting a generation after it has billed does not
  refund it.
- Provider-side cancellation of in-flight work is not currently available.

## Safe retries
On a gateway timeout or a dropped connection, do not resubmit — resume polling
the **original** `contentId`. Long jobs routinely outlive a client poll timeout,
so a timed-out request is not evidence the job failed.
Before submitting a replacement generation, check for a matching in-flight job:
`GET /api/v1/generations?status=pending` and `GET /api/v1/generations?status=processing`.

## Concurrency limits
Each account has a limit on API generations running at once, shared by every key
on the account, across every `/generate` route. Exceeding it returns `429` from
`POST /api/v1/generate` — the request is rejected, not queued.
This is **not** the Maker daily-allowance rejection (`makerCaps` in
`GET /api/v1/me`). A concurrency 429 means "too many at once right now";
a Maker cap rejection means "out of free daily uses" — they are unrelated and
easy to confuse.

## Duration and audio-clock reference
For models billed per second:
- Billing measures the **decoded duration** of the file you supply. A
  caller-supplied duration value is ignored for billing.
- Billed seconds are the decoded duration **rounded up** to the next whole
  second, subject to a per-model minimum and sometimes a maximum.
- Output length can differ slightly from the driving audio.
- Pixio never re-times the original soundtrack.

## Stylized (non-photoreal) character guidance
Animating a stylized/cartoon/toy character that speaks? Reference-image
quality governs character fidelity far more than prompt wording.
- Artifacts present in the reference — unwanted facial hair, ambiguous
  eyes/goggles, props near the mouth — tend to be reproduced or misread in
  the output.
- Keep the mouth region unobstructed and unambiguous in the reference image.
- Quiet/listening poses and open-mouth laughter are the hardest cases.
  Generate them as separate takes from speaking footage so an approved take
  can be reused instead of re-rolling.
- This is practical guidance to improve your odds, not a guarantee of output
  quality.

## Director (music videos, films, studio shots)
New to it? `GET /api/v1/montage` (public) explains Montage, the product
behind the Director API: what it makes, how a production runs, a quickstart
for agents, limits and prices.
`/api/v1/director/*` is Pixio's own video studio: lip-synced music videos cut
to your song, 30 s – 7 min films, single shots, images, songs, upscale and
finishing. Field names follow the studio's; `GET /api/v1/director/catalog`
lists every endpoint with its fields, looks, styles and credit prices.
- Text limits (characters): `prompt` 8000 on shots, images and redos;
  `idea` 4000 and `style` 500 on music videos, films and `music/plan`;
  `story` 4000 on `prompts/write`; `prompt` 4000 and `lyrics` 6000 on
  `music/generate`; packaging `tagline` 120, `cta` 60, `legal` 300 and
  `voiceover_text` 1500 (also inside a `package` object). Longer text gets
  `400 invalid_request` naming the field before anything is held. The
  catalog lists them per endpoint as `maxLength`.
- Face fixes report `faceFixReport`: per re-rendered section, likeness
  before and after and whether the change is visible (under 0.05 is not).
  Face fix handles one face per shot, so two-person shots change little.
- A song from `music/generate` ends when its structure is complete, so it
  can come back shorter than `duration`; the job then has `durationShort`
  (`requestedSeconds`, `actualSeconds`). Add sections or tags to the lyrics
  for a longer one.
- Dialogue: put who-speaks and silence directions before the line or at the
  start of the shot, and only camera or action after `</d>`; the prompt
  check warns about speech words right after a line.
- End cards: `tagline_size` (3–20, default 6.8) and `cta_size` (2–12,
  default 4.5), as a % of the frame's short side.
- Looks and filters: packaging takes `filter` (sepia, black_and_white,
  noir, vintage, faded, warm, cool, vivid, cinematic, dreamy; `GET
  /api/v1/director/filters`), `filter_strength` (0–1) and `vignette`
  (0–1); the logo, captions and end card keep their colours. To match a
  reference, `POST /api/v1/director/looks` with a `picture`, a `video` or
  `job_id` (free) and send its `id` as `look_id`, or send
  `look_from_job` with one of your finished jobs. `GET
  /api/v1/director/jobs/{id}/filter_preview` shows one frame with a filter
  (or `filter=all`) before you package (free). Same price.
- Music and laughs: packaging `score` (`"auto"` or a description) has
  the music model make an instrumental of the video's length, mixed under it
  and dipping under speech (`score` in the catalog, per started 5 minutes;
  an uploaded bed wins). `laugh_track` (`light` or `full`, with
  `laugh_db`) adds studio-audience laughs after the punchlines
  (`laughTrack`). Series take `laugh_track` for every episode, and
  `theme_auto=true` or a `theme_brief` to have the theme made once
  (`score`, charged when the series is saved).
- TV series: save a show once with `POST /api/v1/director/series` (free):
  `name`, `premise` (its world and tone, for the writer), `style` (a
  look for every episode), `aspect`, a `theme` (music under the opening
  for `theme_s`, default 10 s) and `title_card` (on by default: "NAME /
  Episode N: Title"). The cast: `cast` (a JSON list of `{name, what,
  kind}`, kind person, place or thing), then a picture and voice for each
  member with `POST /api/v1/director/series/{id}/cast` (`name`,
  `what`, `kind`, `picture`, `voice` of 5–15 s, `voice_what`);
  or the simple way, `pictures` (1–9) with `references` (what each
  shows; the name is the text before the first comma) and `voice_samples`
  (0–3) with `voices` (whose each is). Without pictures or voices, the
  first episode's become the show's own. Cast limits: `name` 60, `what`
  400, `voice_what` 200. At most 50 series per account.
- Episodes: `POST /api/v1/director/series/{id}/episodes` with an `idea`
  (10–4000; name the cast members in it, their pictures and voices go first),
  `duration` (30–420, a multiple of 15, default 60), `speed`,
  `number`, `previously` (your own recap, up to 3000), `voice_lock`
  (`auto` by default: on only when someone in it has no voice yet),
  `face_fix: "auto"`, `visual_qa` and an extra `package`. Each
  episode is a normal film job: the writer gets the series and a recap of the
  earlier episodes, and when it is done its recap (what happened, open
  threads, lasting changes) is saved and the show learns new faces and
  voices from it (`GET /api/v1/director/series/{id}/episodes`). Priced as
  an AI-written film plus the recap (`episodeRecap`) and packaging (title
  card and theme); `?dry_run=true` is free. Redo and final work on an
  episode like on a film.
- Explainers: `film_type: "explainer"` with an `idea` makes a narrated
  vertical-video explainer: the AI writes the narration, a studio voice (or
  your `voiceover_sample`) reads it, one shot per sentence, word-by-word
  captions, no end card. It is priced like a film plus the narration writing
  (`adReview` in the catalog) and packaging.
- Voices: films take `voice_lock: true` (each character keeps the voice
  heard in clip 1 for the whole film, no samples needed; the film takes about
  one clip longer). Typed narration (`voiceover_text`) has 54 voices in 8
  languages (`GET /api/v1/director/voiceover/voices` lists them with their
  language; write the script in that language), or send a
  `voiceover_sample` (5–15 s of the narrator) to have it read in that voice;
  `voice_clone` picks how: `natural` (default, best match), `fast` or
  `classic`. Same price.
- Music bed under dialogue: packaging `duck_under_dialogue: true` dips the
  bed wherever the video's own characters speak, not only under a voiceover
  (`dialogue_duck_db`, default -12). Same price.
- Films with `visual_qa` and `<d>` lines get a speech check: `qaIssues`
  can report `speech_extra_words`, `speech_missing`, `speech_cut_off` and
  `speech_unscripted`, each with the clip to redo. `face_fix: "auto"`
  skips sections whose drifted shots all show two or more people (face fix
  redraws one face per shot), so they are not billed.
- Draft, then final: a film with `speed: "draft"` is cheaper per clip.
  `POST /api/v1/director/videos/film/{id}/final` renders that finished film
  again at full quality as a new job, with the same written clips, the same
  pictures (yours and the designed ones) and the same seeds; packaging and
  finishing carry over. It costs a final render of every clip (plus packaging
  and visual QA when the draft had them), never the writing. Optional:
  `upscale`.
- Music videos have a draft too: `speed: "draft"` renders every section at a
  smaller frame for less (see `musicSectionDraft` in the catalog);
  `POST /api/v1/director/videos/music/{id}/final` renders that finished
  music video again at full quality with the same song, sections, pictures
  and seeds, priced as a full render of every section (plus packaging and
  visual QA when the draft had them), never the writing or the sets.
- Extra work you ask for is priced in proportion: `steps` above the default
  (shots and music videos 8, sung-word music videos 12, images 6, songs 30),
  `vsa: false` on a shot (about 1.8x), `finish` on a film or music video
  (priced like `videos/finish`) and `visual_qa: "local"` (`visualQaLocal`
  per clip or section). The quote (`?check=true`) always shows the total.
  `music/plan` without an `idea` (the song analysis alone) costs
  `songAnalysis`.
- Single shots are billed as at least 8 seconds (the GPU startup costs the
  same however short the shot).
- A face fix is charged only for the sections it visibly changed
  (`faceFixReport`); the rest of the hold goes back.
- Films and music videos list the pictures they used in `pictures`
  (`number`, `tag`, `designed`, `what`, `url`); each is served at
  `GET /api/v1/director/jobs/{id}/pictures/{n}`.
- Every start call returns `202` with a `director.job` (and a `Location`
  header). Poll `GET /api/v1/director/jobs/{id}` until `status` is `done`,
  `failed` or `cancelled`; reading a job syncs it.
- Media fields take a multipart file, a URL (`<field>_url` / `<field>_urls`),
  or a path from your own assets. Fields like `song_job` and `job_id` take a
  finished Director job id from this API.
- Credits: the quote is reserved when the job starts (`402` when short) and
  settles once — the quote when done, only finished clips/sections (plus any
  writing) when a music video or film stops early, nothing when a job fails
  before rendering anything.
- Finished files are copied into your assets (`output.assetPath`,
  `output.generationId`); `output.url` is a signed URL valid 6 hours.
- `music/plan` and `prompts/write` are writer calls: they run in the
  background for a few minutes and return the plan or clips in `result`.
- At most 8 Director jobs run at once per account (`429 concurrency_limit`
  with `Retry-After`). This is separate from the `/generate` limit.
- `DELETE /api/v1/director/jobs/{id}` cancels; finished parts are still charged.
- Prompts in the studio's official format are checked before rendering. If
  the checker finds errors you get `422 prompt_check_failed` with the full
  report in `promptCheck`, and nothing is charged. Warnings never block,
  and plain prompts ("a lighthouse at dusk") always render. Send
  `strict_prompt=false` to render anyway. Applies to text, image and
  reference shots, and to music videos and films when you send your own
  prompts.
- Add `?check=true` (or `?dry_run=true`) to `videos/text|image|reference|music|film` (`videos/package` takes `?dry_run=true`)
  to get the report and the credit quote for free, without starting a job.
- While a job waits or renders, `queue.ahead` says how many jobs are in
  front of it (0 once rendering) and `queue.estimatedCompletionAt` when it
  should finish. `GET /api/v1/director/queue` lists only your own active jobs.
- Fights: shots that read as a fight get the studio's Fight Flow look
  automatically (each blow sets up the next). Send `fight_flow=false` to
  turn it off, `true` to force it.
- `fix_prompt` (`off` default, `safe`, `ai`) repairs your own prompts
  before rendering: untrained camera words, grain words, "no crowd" lines.
  `safe` is rule-based and instant; `ai` also fixes what the checker
  still finds. Prices do not change.
- `balance_sections` (music videos and `music/plan`) evens out a last
  section under 6 s with the one before it; on by default when the AI
  writes the sections. Send the same value to both calls.
- Commercials: save a brand once with `POST /api/v1/director/brands` (logo,
  font, tagline, call to action, colours, end-card and sound defaults, and a
  brief for the writer: description, audience, tone, look, banned words).
  Brands are free and only you can see or use yours.
- `POST /api/v1/director/videos/package` brands a finished video (`job_id`
  or an uploaded `video`): an end card with the logo, tagline and call to
  action, an optional corner logo, a music bed and a voiceover mixed under
  the sound, other frame shapes (`formats`: 9:16, 1:1, 4:5) and up to 3
  shorter `cutdowns`. The main video keeps its length; the rest come back in
  `deliverables`, each copied into your assets. Priced like finishing, by
  the seconds of video it writes. `?dry_run=true` is free.
- Films and music videos take `brand_id`, a `package` object (the same
  fields) and a `logo`; films also take `music_bed`, `voiceover`,
  `film_type: "commercial"` (an ad structure for the writer),
  `product_pictures` (which of your `images` show the product) and
  `variants` (2–4 versions in all). Each extra version is its own job in
  `versionJobIds`, billed like the first; all of them are held up front.
- Packaging also takes `legal` (fine print on the end card, or the whole
  video with `legal_always`), `captions` (`"auto"`, SRT/WebVTT text or
  a list of `{text, start, end}`), a typed `voiceover_text` read by a studio
  voice (`voiceover_voice`, listed at `GET /api/v1/director/voiceover/voices`;
  a `voiceover` file wins) and a `packshot` image (the product on the end
  card; on films `package.packshot_picture` = the number of one of your
  `images`). An opening `title_card` (up to 3 lines, the first big;
  `title_card_s` 1–10, default 4) and `music_until_s` (the music bed plays
  only under the opening, then fades). Same price.
- `prompts/write` writes commercials too: `film_type: "commercial"`,
  `brand_id`, `product_pictures` (1-based, in `references`), `voiceover`
  (leave room for one) and `end_card_s`. With `mode: "reference"` and a
  6–15 s `duration` it writes a one-shot ad.
- When the AI writes a commercial (`film_type: "commercial"` with an `idea`
  on `videos/film`, or on `prompts/write` in film or reference mode), the
  studio adds a self-review pass that checks the clips against the ad rules
  and fixes only what breaks one (about 20–40 s more writing). It costs
  `adReview` credits once per write (see the catalog's prices).
- `ad_style` (commercials on `videos/film` with an `idea`, and
  `prompts/write`) picks the ad's format: `problem_solution`,
  `product_hero`, `slice_of_life`, `demo`, `cinematic_story`, `comedy`,
  `sensory`, `montage`, `before_after`, `aspirational`, `reveal`, or
  `auto` (default: the writer picks, so two ads from one brief differ; with
  `variants` each version gets its own format).
- Caption looks (packaging): `caption_style` (`subtitle` default, or `pop`:
  short word chunks), `caption_words` (1–8), `caption_position` (`bottom`,
  `center`, `lower_third` or 0–1), `caption_font` (`brand` or a listed bold
  font), `caption_size`, `caption_color`, `caption_stroke_color`,
  `caption_stroke_width`, `caption_shadow`, `caption_highlight_color`
  (karaoke-style word highlight), `caption_uppercase` and
  `caption_animation` (`none`, `pop`, `fade`). Same price.
- Single shots (`videos/text`, `videos/image`, `videos/reference`) take
  `brand_id` and a `package` object too (image and reference also a
  `logo` and a `packshot`). When the clip is done the studio packages it as
  its own job: the shot's `packageJobId` is a `videos/package` job to poll for
  the packaged video and `deliverables`. Its credits are held with the
  shot's when you start (a `402` means nothing started) and given back if
  the clip stops or the packaging never starts (`packageSkipped` says why).
  `?check=true` quotes both: `credits.clip` and `credits.packaging`.

## Endpoints
- `GET  /api/v1/guide` — this guide (Markdown, or `?format=json`)
- `GET  /api/v1/openapi.json` — OpenAPI 3.1 schema
- `POST /api/v1/generate` — `{ modelId, params }`
- `POST /api/v1/images` — clean public URL for an image input
- `POST /api/v1/media` — clean public URL for any media (image/video/audio)
- `POST /api/v1/uploads` — upload to user assets
- `GET  /api/v1/assets` — list your assets (uploads + generated); `?type=&source=&search=&page=&limit=`
- `POST /api/v1/assets` — upload media into your assets (alias of /uploads)
- `DELETE /api/v1/assets` — bulk-delete; JSON `{ ids }` or `?ids=a,b,c`
- `GET  /api/v1/assets/{id}` — get one asset (signed URL)
- `GET  /api/v1/assets/{id}/download` — signed attachment URL (`?redirect=true` to stream). Songcraft songs: `?tier=preview` 100 credits or `?tier=official` 300 credits, each charged once per song (402 when short)
- `GET  /api/v1/assets/download?ids=a,b,c` — batch signed download URLs (Songcraft songs: `?tier=` preview 100 / official 300, once per song; unpaid ones come back under `failed`)
- `DELETE /api/v1/assets/{id}` — delete an asset you own
- `PATCH /api/v1/assets/{id}` — rename an asset (uploads only)
- `GET  /api/v1/styles` — style gallery as data; `?kind=&category=&search=`. Styles append `tokens` to a prompt; viral templates (`promptMode: "replace"`) carry a `recipe` ready for /generate
- `GET  /api/v1/voices` — TTS voices by name; `?provider=&category=&search=&page=&limit=` (paged, follow `hasMore`). Merge a voice's `use` into /generate `params` (`pixio/text-to-speech` takes `{ voice_id }`; your clones use `{ voice_id: "custom", audio_voice_clone_asset }`)
- `POST /api/v1/voices/add` — make a shared-library voice usable; body is the `add` object from a `/voices?search=` hit, returns its `use`
- `GET  /api/v1/assets/collections` — list your folders (with item counts)
- `POST /api/v1/assets/collections` — create a folder `{ name, parentId?, color? }`
- `GET  /api/v1/assets/collections/{id}` — one folder
- `PATCH /api/v1/assets/collections/{id}` — rename / recolour / re-parent
- `DELETE /api/v1/assets/collections/{id}` — delete (assets are kept)
- `GET  /api/v1/assets/collections/{id}/items` — assets in a folder (signed URLs); `?page=&limit=`
- `POST /api/v1/assets/collections/{id}/items` — file assets `{ assetIds }`
- `DELETE /api/v1/assets/collections/{id}/items` — unfile assets `{ assetIds }` or `?ids=`
- `GET  /api/v1/params?modelId=pixio/{model}`
- `POST /api/v1/generations/estimate` — credit cost preview before generating
- `GET  /api/v1/generations` — list your generations (all statuses); `?status=&type=&page=&limit=`. `creditsCost` is the quoted list price; `billedAt` is set only when credits were actually debited (failed runs are never billed)
- `GET  /api/v1/generations/{id}`
- `DELETE /api/v1/generations/{id}` — delete a generation you own
- `GET  /api/v1/prompts/optimize` — optimizer configuration: `messageTypes` (model-family system prompts), `modes`, `limits`
- `POST /api/v1/prompts/optimize` — the full optimizer: `{ prompt, messageType?, mode?, attachments?, googleSearch?, urlContext? }`; legacy `{ prompt, type?, context? }` still works unchanged
- `GET  /api/v1/models` — each model carries `credits` (list price) plus `freeForPlans`, `freeForCurrentPlan`, `makerCap`, and `freeExcept` so you can tell what your plan actually pays
- `GET  /api/v1/models/{id}` — model detail + inputs
- `GET  /api/v1/pricing` — the live price list priced for you: `listCredits` vs `yourCredits` per model, plus `plans`, `creditPacks`, and `usdPerCredit`
- `GET  /api/v1/credits`
- `GET  /api/v1/credits/ledger` — credit transaction history
- `GET  /api/v1/me` — account, plan, credit balances, concurrency limit, and `makerCaps` (daily free-use pools with `remainingToday`)
- `GET  /api/v1/subscription` — plan, quota, API concurrency limit
- `GET  /api/v1/workflows`
- `POST /api/v1/workflows/{id}/runs`
- `GET  /api/v1/workflows/{id}/runs`
- `GET  /api/v1/workflows/{id}/runs/{runId}`
- `GET  /api/v1/montage` — what Montage (the Director API) is, for agents: what it makes, quickstart, limits, prices (public)
- `GET  /api/v1/director/catalog` — Director endpoints, fields, looks, styles and credit prices
- `GET  /api/v1/director/voiceover/voices` — voices for a packaging `voiceover_text` (free)
- `POST /api/v1/director/videos/{text|image|reference}` — one 5–15 s shot
- `POST /api/v1/director/videos/music` — lip-synced music video from a song (file, URL or `song_job`)
- `POST /api/v1/director/videos/film` — film from clip prompts or an `idea`
- `POST /api/v1/director/videos/{music|film}/{id}/redo` — re-shoot one section or clip as a new job
- `POST /api/v1/director/videos/film/{id}/final` — render a finished draft film at full quality (same clips, pictures, seeds)
- `POST /api/v1/director/videos/music/{id}/final` — render a finished draft music video at full quality (same song, sections, pictures)
- `GET|POST /api/v1/director/series`, `GET|POST|DELETE /api/v1/director/series/{id}` — your TV series (free)
- `POST /api/v1/director/series/{id}/cast`, `DELETE …/cast/{name}`, `GET …/cast/{name}/{picture|voice}`, `GET …/picture?n=` — a series' cast and pictures
- `POST /api/v1/director/series/{id}/episodes` — make an episode; `GET` lists them with their recaps
- `GET  /api/v1/director/jobs/{id}/pictures/{n}` — one reference picture a film or music video used
- `POST /api/v1/director/videos/{upscale|finish|facefix}` — post-process a finished job or a clip
- `POST /api/v1/director/videos/package` — end card, logo, music, voiceover, frame shapes and cutdowns (`deliverables`)
- `GET  /api/v1/director/brands` · `POST /api/v1/director/brands` — list / save brands (free)
- `GET|POST|DELETE /api/v1/director/brands/{id}` · `GET /api/v1/director/brands/{id}/logo` — read / change / delete a brand, its logo
- `POST /api/v1/director/images/{text|edit|reference}`
- `POST /api/v1/director/music/generate` — a song from a description and lyrics
- `POST /api/v1/director/music/plan` · `POST /api/v1/director/prompts/write` — writer calls (result in `result`)
- `POST /api/v1/director/prompts/check` — check prompts against the house rules (free, synchronous)
- `GET  /api/v1/director/jobs` — your Director jobs; `?limit=&before=&endpoint=`
- `GET  /api/v1/director/queue` — your waiting/rendering Director jobs with their place in line
- `GET  /api/v1/director/jobs/{id}` · `DELETE /api/v1/director/jobs/{id}` — get / cancel
- `GET  /api/v1/director/jobs/{id}/parts/{n}` — stream one clip or section (Range supported)
- `GET  /api/v1/director/jobs/{id}/{video|image|audio}` — 302 to the finished file
