> ## Documentation Index
> Fetch the complete documentation index at: https://support.myapps.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing and limits

> How Director jobs are held, charged and refunded, every price, and the limits that return errors

Director bills in Pixio credits (**1 credit = \$0.01**), from the same balance as the app. Prices are the same as in the app. The live price list is always at `GET /api/v1/director/catalog` under `prices`; this page explains how those numbers combine.

> [!TIP]
>
> Get the exact quote for any request for free first: add `?check=true` (or `?dry_run=true`) to the start URL. Nothing is held or rendered. Video is expensive — a 60-second music video from an idea is about **1,055 credits (\$10.55)** — so quote before long jobs.

## Hold, then settle

**1. Held at the start**

The full quote is reserved when the job starts. If your balance is short you get `402 insufficient_credits` with `requiredCredits`, and **nothing starts**.

**2. Settled once at the end**

When the job finishes, the hold is settled exactly once: captured for what was delivered, and the rest given back. You are never charged more than was held.

| Outcome | What you pay |
| - | - |
| `done` | The quote. Two exceptions: a face fix pays only for sections it visibly changed, and a storyboarded film pays for the stills actually drawn instead of the allowance held |
| Music video or film stops early (`failed` or `cancelled`) | Finished sections or clips, plus the writing if at least one was finished. Never more than the hold |
| A storyboarded film that is never approved | The writing and the stills drawn |
| Anything else that fails or is cancelled | Nothing |
| The studio refuses the request at the start | Nothing; every hold is given back |
| The finished file can't be saved to your assets (after retries) | Nothing; the job is marked `failed` |
| `music/plan`, `prompts/write` | The quote when done; nothing if they fail |

### Extra holds

Some requests hold more than one amount, so a short balance stops all of it up front:

* **Film `variants`** — every version is held at the start, each at the single-version price. Each extra version is its own job (`versionJobIds`) and settles on its own.
* **A single shot with `brand_id` or `package`** — the packaging is held with the shot. When the clip is done it becomes its own `videos/package` job (`packageJobId`). If the clip stops, or the packaging never starts, its hold is given back and `packageSkipped` says why.
* **`face_fix: "auto"`** — after the video is done, sections whose faces drifted get a face fix as a separate job (`faceFixJobId`), held at that moment and billed like any face fix. If your balance is short then, the face fix is skipped, not charged.
* **Storyboard redraws** and a **made series theme** are held when you ask, charged when the studio takes the work, and given back if it refuses.

Every settled job appears in your credits history and in `GET /api/v1/credits/ledger`.

## Prices

All amounts in credits.

### Single shots (`videos/text`, `videos/image`, `videos/reference`)

| Item | Price |
| - | - |
| Fast (`quality: "fast"`, default) | 4.73 per second |
| Quality (`quality: "quality"`) | 7.57 per second |

**Formula:** `ceil(max(8, duration) × rate × stepsFactor × vsaFactor)` — shots are billed as at least 8 seconds. `stepsFactor` is `steps / 8` above 8 steps; `vsaFactor` is 1.8 with `vsa: false`.

| Example | Credits |
| - | - |
| 5 s fast | 38 |
| 10 s quality | 76 |
| 15 s fast | 71 |
| 15 s quality | 114 |
| 10 s fast, `vsa: false` | 86 |
| 10 s fast, `steps: 16` | 95 |

### Music videos (`videos/music`)

| Item | Price |
| - | - |
| One 15 s section | 201 |
| One 15 s section, `speed: "draft"` | 180 |
| Writer, with an `idea` | 151 |
| Designed set pictures (`make_references`, with an idea) | 4 × 25 |

**Formula:** `sections × ceil(sectionPrice × stepsFactor) + writer + sets + upscale + finish + visual QA + packaging`. Sections are the song length divided into 15 s, rounded up (a remainder under 1/48 s joins the last section). `stepsFactor` uses a default of 8 steps, or 12 with `lipsync: "sung_words"`.

| Example | Credits |
| - | - |
| 60 s song from an idea | 1,055 |
| 60 s song from an idea, draft | 971 |
| Final of that 60 s draft (`…/final`) | 804 |
| 3 min song from an idea | 2,663 |

### Films (`videos/film`)

| Item | Price |
| - | - |
| One 15 s clip | 115 |
| One 15 s clip, `speed: "draft"` | 73 |
| Writer round, with an `idea` | 151 |
| Ad review (commercial, explainer or documentary) | 76 |

**Formula:** `clips × clipPrice + writer + upscale + finish + visual QA + packaging + storyboard`. Clips are `duration / 15`. Writer rounds are 1 for films up to 8 clips (2 minutes), otherwise `1 + ceil(clips / 4)`. Explainers and documentaries always include packaging; documentaries also include a score (36 per started 5 minutes).

| Example | Credits |
| - | - |
| 60 s from an idea | 611 |
| 60 s from an idea, draft | 443 |
| Final of that 60 s draft (`…/final`) | 460 |
| 60 s commercial from an idea | 687 |
| 3 min from an idea | 1,984 |
| 30 s from your own clips | 230 |

### Retakes and finals

| Item | Price |
| - | - |
| Music video section redo | One section at the source video's speed (201, or 180 for a draft) |
| Film clip redo | One clip at the source film's speed (115, or 73 for a draft) |
| Music video final | Every section at 201, plus upscale and the draft's packaging and visual QA. Never the writing or the sets |
| Film final | Every clip at 115, plus upscale and the draft's packaging and visual QA. Never the writing |

### TV series episodes (`series/{id}/episodes`)

An AI-written film of the episode's length, plus **76** for the recap, plus packaging for the title card and theme (plus the series' laugh track or a `package.score` when set). A 60 s episode is **775**.

### Post-processing

| Endpoint | Formula | Example |
| - | - | - |
| `videos/upscale` | 71 per started 15 s | 30 s → 142 |
| `videos/finish` | `ceil(seconds × 1.46)`, at least 16 | 30 s → 44 |
| `videos/facefix` | 59 per section held; charged only for sections visibly changed | 4 sections → up to 236 |
| `videos/package` | `ceil((seconds + sum of cutdowns) × (1 + extra formats) × 1.46)`, at least 16 | 60 s → 88; 30 s + two extra shapes + a 15 s cutdown → 198 |

Packaging extras: a made `score` adds **36 per started 5 minutes**; a `laugh_track` adds **16**. Filters, looks, captions, fine print, a packshot and a typed voiceover cost nothing extra. A cutdown that isn't at least 1 s shorter than the video is skipped and not charged.

### Extras on films and music videos

| Option | Price |
| - | - |
| `upscale: true` | 71 per section or clip |
| `finish` | Like `videos/finish` for the whole length |
| `visual_qa: "local"` | 4 per section or clip |
| `visual_qa: "full"` | 16 per section or clip |
| `storyboard: true` | 25 per still; up to 4 a clip are held, the real count is charged |
| Storyboard redraw | 25, plus 16 with a `note` |

### Images

| Endpoint | Formula | Default price |
| - | - | - |
| `images/text` | `ceil(max(16, (96 + 2 × megapixels) × 0.15095) × 1.45475)` | 24 |
| `images/edit` | `ceil(max(17, (100 + 2 × megapixels) × 0.15095) × 1.45475)` | 25 |
| `images/reference` | `ceil(max(17, (96 + 2 × megapixels + 4 × pictures) × 0.15095) × 1.45475)` | 26 with 3 pictures |

`megapixels` defaults to 4 and is priced between 0.5 and 16. `image_model: "high"` multiplies by 1.55 (text at default size → 38). Steps above 6 multiply by `steps / 6` (12 steps → 48).

### Songs and writing

| Endpoint | Price |
| - | - |
| `music/generate` | 36, × `steps / 30` above 30 steps (60 steps → 72) |
| `music/plan` | 151 with an `idea`; 16 for the song analysis alone |
| `prompts/write`, film mode | 151 per writer round (60 s → 151, 3 min → 604) |
| `prompts/write`, other modes | 151 |
| Commercial on `prompts/write` (film or reference mode) | +76 |

### Free

Prompt checks, `?check` and `?dry_run` quotes, brands, saving a series, looks, filter previews, the catalog, voice lists, job reads and stills.

A series theme made for you (`theme_auto` or `theme_brief`) costs **36** when the series is saved.

## Limits

### Running jobs

**At most 8 Director jobs queued or running at once per account.** The ninth start returns `429 concurrency_limit` with a `Retry-After: 30` header — the request is rejected, not queued. This limit is separate from the `/generate` concurrency limit.

### Saved things

| Item | Limit | Over it |
| - | - | - |
| Brands per account | 50 | `409 conflict` |
| Series per account | 50 | `409 conflict` |

### Text

Text over its limit returns `400 invalid_request` **before anything is held**, naming the field:

```json theme={null}
{
  "error": "`idea` is 4,040 characters; the most is 4,000.",
  "code": "invalid_request",
  "field": "idea",
  "maxLength": 4000,
  "length": 4040
}
```

| Field | Limit |
| - | - |
| `prompt` on shots, images and redos | 8,000 |
| `idea` on music videos, films and `music/plan` | 4,000 |
| `style` on music videos, films, `music/plan` and `prompts/write` | 500 |
| `story` on `prompts/write` | 4,000 |
| `idea` on series episodes | 4,000 |
| `previously` on series episodes | 3,000 |
| `prompt` on `music/generate` | 4,000 |
| `lyrics` on `music/generate` | 6,000 |
| Packaging `tagline` | 120 |
| Packaging `cta` | 60 |
| Packaging `legal` | 300 |
| Packaging `title_card` | 160 |
| Packaging `voiceover_text` | 1,500 |
| Series cast `name` / `what` / `voice_what` | 60 / 400 / 200 |
| Storyboard redraw `note` | 500 |

Packaging limits apply inside a `package` object too, reported as e.g. `package.tagline`.

> [!WARNING]
>
> **Text is counted as sent: every line break counts as two characters.** Text reaches the studio with line breaks as CRLF, so a 4,000-character idea with 40 line breaks counts as 4,040 and is refused. This applies to JSON and multipart bodies alike. Trim or join lines if you're near a limit.

### Files per request

| Endpoint | Files |
| - | - |
| `videos/reference` | `images` up to 9, `videos` up to 3, `audios` up to 3 |
| `videos/music`, `videos/film` | `images` up to 9; films also `ref_audios` up to 3 |
| Redo | `images` up to 9 |
| `images/reference` | `images` 1–8 |
| `videos/upscale` | An uploaded `video` up to 15 s |
| Everything else | One of each named file |

Sending more than the maximum returns `400 invalid_request`. Every file field accepts a multipart upload, a URL (`<field>_url` or `<field>_urls`), or a path from your own Pixio assets.

### Lengths

| Item | Range |
| - | - |
| Single shot | 5–15 s |
| Film or episode | 30–420 s, a multiple of 15 |
| Music video | The song's length, in 15 s sections |
| Section or clip number (`parts`) | 1–28 |

## Related

* [Jobs and statuses](https://support.myapps.ai/director-api/jobs-and-statuses.md)
* [Credits](https://support.myapps.ai/credits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.