> ## 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.

# Storyboards

> See every shot of a film as a still before it renders, redraw the ones you don't like, then approve

A storyboard lets you check a film shot by shot before paying for the render. Send `storyboard: true` with an `idea` on `POST /director/videos/film`: the writer plans the film, one still is drawn per shot, and the job waits for you.

Use it for anything long or expensive — explainers, documentaries, commercials — where a wrong shot is cheaper to catch as a still than as a 15-second clip.

> [!NOTE]
>
> Storyboards need an `idea` (the writer plans the shots to draw) and work on one version at a time: `variants` must be 1. Otherwise the request returns `400 invalid_request`.

## The flow

**1. Start the film with storyboard on**

```bash theme={null}
JOB=$(curl -s -X POST https://beta.pixio.myapps.ai/api/v1/director/videos/film \
  -H "Authorization: Bearer $PIXIO_API_KEY" \
  -F duration=60 \
  -F film_type=explainer \
  -F idea="why the sky is blue, for curious ten-year-olds" \
  -F storyboard=true | jq -r .id)
```

**2. Wait until it's ready for you**

Poll the job. When the stills are drawn, `storyboard.waiting` becomes `true`. The status **stays `running`** — that's deliberate, so existing clients don't break.

```json theme={null}
"status": "running",
"storyboard": {
  "waiting": true,
  "stills": 9,
  "url": "https://beta.pixio.myapps.ai/api/v1/director/jobs/…/storyboard",
  "sheetUrl": "https://beta.pixio.myapps.ai/api/v1/director/jobs/…/storyboard/sheet.jpg"
}
```

> [!WARNING]
>
> Branch on `storyboard.waiting`, not on `stage`. While waiting, `stage` isn't meant for this decision.

**3. Review it**

| Read | Endpoint |
| - | - |
| Every shot's text, with a link to each still | `GET /director/jobs/{id}/storyboard` |
| All stills on one contact sheet (JPEG) | `GET /director/jobs/{id}/storyboard/sheet.jpg` |
| One still (PNG), 1-based | `GET /director/jobs/{id}/storyboard/{clip}/{shot}` |

All free. The storyboard answer is `{ object: "director.storyboard", jobId, waiting, stills, sheetUrl, storyboard }`.

**4. Redraw what's wrong**

`POST /director/jobs/{id}/storyboard/redo` with a JSON body:

| Field | Notes |
| - | - |
| `clip` | Required, 1–28 |
| `shot` | Required, 1–12 |
| `note` | Optional, up to 500 characters. The writer rewrites that shot first, and the film follows the new shot |

```bash theme={null}
curl -s -X POST https://beta.pixio.myapps.ai/api/v1/director/jobs/$JOB/storyboard/redo \
  -H "Authorization: Bearer $PIXIO_API_KEY" -H "Content-Type: application/json" \
  -d '{"clip":1,"shot":2,"note":"show a prism splitting white light, close-up"}'
```

Answers with the updated storyboard once the new still is ready. Without a `note`, the same shot is simply drawn again.

**5. Approve**

```bash theme={null}
curl -s -X POST https://beta.pixio.myapps.ai/api/v1/director/jobs/$JOB/storyboard/approve \
  -H "Authorization: Bearer $PIXIO_API_KEY"
```

Answers with the job. Keep polling it as usual until `done`.

## What it costs

| Item | Credits |
| - | - |
| Each still | 25 |
| Held at the start | 4 stills per clip (100 per 15 s clip) |
| A redraw | 25 |
| A redraw with a `note` | 25 + 16 |

You pay for the stills actually drawn, not the allowance held: the job settles at its quote with the allowance replaced by the real count. Redraws are charged one at a time — held when you ask, charged when the studio takes it, given back if it refuses. A redraw with too few credits returns `402`.

> [!WARNING]
>
> A storyboard you never approve still pays for its writing and its stills. Cancel it with `DELETE /director/jobs/{id}` if you've decided not to make it.

## Errors

| Status | When |
| - | - |
| `404 not_found` | The job has no storyboard (it wasn't started with `storyboard: true`), or isn't yours |
| `400 invalid_request` | A redraw without a valid `clip` and `shot`, or a note over 500 characters |
| `402 insufficient_credits` | Not enough credits for the redraw |

## Related

* [Recipes](https://support.myapps.ai/director-api/recipes.md) — a documentary with a storyboard, end to end
* [Jobs and statuses](https://support.myapps.ai/director-api/jobs-and-statuses.md)
* [Billing and limits](https://support.myapps.ai/director-api/billing-and-limits.md)


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