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

# Recipes

> End-to-end Director API walkthroughs with curl: music videos, films from draft to final, commercials, documentaries, episodes and retakes

Complete, copy-pasteable flows. Each one starts a job, polls it, and collects the result. Field-by-field detail for every endpoint is in the generated API reference; prices are explained in [Billing and limits](https://support.myapps.ai/director-api/billing-and-limits.md).

## Before you start

```bash theme={null}
export PIXIO_API_KEY="..."            # an integration key, see /integrations/api-keys
export API="https://beta.pixio.myapps.ai/api/v1"
```

A small poll helper used below. It waits until the job is `done`, `failed` or `cancelled`:

```bash theme={null}
poll() {
  while true; do
    JOB=$(curl -s "$API/director/jobs/$1" -H "Authorization: Bearer $PIXIO_API_KEY")
    STATUS=$(echo "$JOB" | jq -r .status)
    echo "$(echo "$JOB" | jq -r .stage)"
    case "$STATUS" in done|failed|cancelled) echo "$JOB"; return;; esac
    sleep 20
  done
}
```

> [!NOTE]
>
> **How to send values.** Endpoints that take files use `multipart/form-data` (`-F`). In a form, `true`/`false` and numbers are read as such, and lists or objects go in as JSON text, e.g. `-F 'product_pictures=[1]'`. Endpoints without files also accept a JSON body. Any file field also takes a URL (`-F song_url=https://…`) or a path from your Pixio assets.

## Music video from a song

**1. Make a song (or bring your own)**

```bash theme={null}
SONG=$(curl -s -X POST "$API/director/music/generate" \
  -H "Authorization: Bearer $PIXIO_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"warm indie pop, female vocal","lyrics":"[verse]\nCity lights are humming low\n[chorus]\nTake me home","duration":60}' \
  | jq -r .id)
poll $SONG
```

36 credits. If it comes back shorter than asked, the job has `durationShort`; add sections to the lyrics for a longer song.

**2. Quote it (free)**

```bash theme={null}
curl -s -X POST "$API/director/videos/music?check=true" \
  -H "Authorization: Bearer $PIXIO_API_KEY" \
  -F song_job=$SONG \
  -F idea="a singer walking home through neon rain" \
  -F aspect=16:9 \
  -F images=@artist.jpg | jq .credits
```

**3. Shoot it**

Same request without `?check=true`:

```bash theme={null}
MV=$(curl -s -X POST "$API/director/videos/music" \
  -H "Authorization: Bearer $PIXIO_API_KEY" \
  -F song_job=$SONG \
  -F idea="a singer walking home through neon rain" \
  -F aspect=16:9 \
  -F images=@artist.jpg | jq -r .id)
poll $MV
```

Each finished section shows up in `parts[]` while the rest renders. A 60 s song from an idea is about 1,055 credits.

> [!TIP]
>
> Want a cheaper look first? Add `-F speed=draft` (180 per section instead of 201), then render the same video at full quality with `POST /director/videos/music/{id}/final` (see the film flow below — it works the same way).

## Retake one section

Didn't like section 3? Re-shoot only that section as a new job; the original stays as it was.

```bash theme={null}
REDO=$(curl -s -X POST "$API/director/videos/music/$MV/redo" \
  -H "Authorization: Bearer $PIXIO_API_KEY" -H "Content-Type: application/json" \
  -d '{"section":3,"prompt":"close-up, she turns to camera as the rain stops"}' | jq -r .id)
poll $REDO
```

One section at the source video's price. For films the path is `/director/videos/film/{id}/redo` and the field is `clip`. `qaIssues` on the original names the part worth redoing.

## Film: draft, then final

**1. Draft**

```bash theme={null}
FILM=$(curl -s -X POST "$API/director/videos/film" \
  -H "Authorization: Bearer $PIXIO_API_KEY" \
  -F duration=60 \
  -F idea="a lighthouse keeper finds a message in a bottle from her younger self" \
  -F speed=draft \
  -F voice_lock=true \
  -F images=@keeper.jpg \
  -F 'references=["Mara, the lighthouse keeper, late 60s"]' | jq -r .id)
poll $FILM
```

443 credits for 60 s from an idea as a draft.

**2. Final**

Renders the same written clips, pictures and seeds at full quality as a new job. Packaging and finishing carry over. The writing is not charged again.

```bash theme={null}
FINAL=$(curl -s -X POST "$API/director/videos/film/$FILM/final" \
  -H "Authorization: Bearer $PIXIO_API_KEY" -H "Content-Type: application/json" \
  -d '{}' | jq -r .id)
poll $FINAL
```

460 credits for 60 s (4 clips × 115).

## Commercial with a brand and packaging

**1. Save the brand once (free)**

```bash theme={null}
BRAND=$(curl -s -X POST "$API/director/brands" \
  -H "Authorization: Bearer $PIXIO_API_KEY" \
  -F name="Northwind Coffee" \
  -F tagline="Wake up somewhere better" \
  -F cta="Order at northwind.example" \
  -F description="Small-batch coffee roasted in Oregon" \
  -F audience="Busy professionals who care about taste" \
  -F logo=@logo.png | jq -r .id)
```

**2. Quote the commercial (free)**

```bash theme={null}
curl -s -X POST "$API/director/videos/film?check=true" \
  -H "Authorization: Bearer $PIXIO_API_KEY" \
  -F duration=30 \
  -F film_type=commercial \
  -F ad_style=product_hero \
  -F idea="the first sip on a grey Monday morning turns the city warm" \
  -F brand_id=$BRAND \
  -F images=@bag.jpg \
  -F 'product_pictures=[1]' \
  -F 'package={"formats":["9:16","1:1"],"cutdowns":[15],"captions":"auto"}' \
  -F variants=2 | jq .credits
```

With `variants=2` you'll see `perVersion` and `versions`. Every version is held up front and billed like the first.

**3. Make it**

Send the same request without `?check=true`. Poll the job; the other versions are in `versionJobIds` (poll each). When done, the main cut is `output`, and the 9:16, 1:1 and 15 s versions are in `deliverables`.

> [!TIP]
>
> Already have a finished video? Brand it directly with `POST /director/videos/package` and `job_id` (or an uploaded `video`). Try colour filters first with the free `GET /director/jobs/{id}/filter_preview?filter=all`.

## Documentary with a storyboard

**1. Start with storyboard on**

```bash theme={null}
DOC=$(curl -s -X POST "$API/director/videos/film" \
  -H "Authorization: Bearer $PIXIO_API_KEY" \
  -F duration=90 \
  -F film_type=documentary \
  -F doc_style=investigative \
  -F interviews=few \
  -F idea="how a small fishing town rebuilt its harbour after the storm of 1987" \
  -F storyboard=true | jq -r .id)
```

**2. Wait for the storyboard**

Poll until `storyboard.waiting` is `true` (the status stays `running`):

```bash theme={null}
curl -s "$API/director/jobs/$DOC" -H "Authorization: Bearer $PIXIO_API_KEY" | jq .storyboard
curl -s "$API/director/jobs/$DOC/storyboard" -H "Authorization: Bearer $PIXIO_API_KEY"
curl -s "$API/director/jobs/$DOC/storyboard/sheet.jpg" -H "Authorization: Bearer $PIXIO_API_KEY" -o sheet.jpg
```

**3. Fix a shot**

```bash theme={null}
curl -s -X POST "$API/director/jobs/$DOC/storyboard/redo" \
  -H "Authorization: Bearer $PIXIO_API_KEY" -H "Content-Type: application/json" \
  -d '{"clip":2,"shot":1,"note":"wide aerial of the harbour at dawn, no people"}'
```

25 credits, plus 16 with a note.

**4. Approve and render**

```bash theme={null}
curl -s -X POST "$API/director/jobs/$DOC/storyboard/approve" \
  -H "Authorization: Bearer $PIXIO_API_KEY"
poll $DOC
```

More in [Storyboards](https://support.myapps.ai/director-api/storyboards.md).

## A TV series episode

```bash theme={null}
SERIES=$(curl -s -X POST "$API/director/series" \
  -H "Authorization: Bearer $PIXIO_API_KEY" \
  -F name="Harbour Lights" \
  -F premise="A warm small-town drama about a family-run lighthouse inn" \
  -F aspect=16:9 \
  -F pictures=@mara.jpg -F pictures=@inn.jpg \
  -F 'references=["Mara, the innkeeper, late 60s","The inn, a white lighthouse on a cliff"]' | jq -r .id)

EP=$(curl -s -X POST "$API/director/series/$SERIES/episodes" \
  -H "Authorization: Bearer $PIXIO_API_KEY" \
  -F idea="Mara finds a guest who claims to have stayed at the inn fifty years ago" \
  -F duration=60 | jq -r .id)
poll $EP
```

A 60 s episode is 775 credits. More in [TV series](https://support.myapps.ai/director-api/series.md).

## Upscale, finish or fix faces afterwards

All three take the `job_id` of a finished job and start a new one:

```bash theme={null}
curl -s -X POST "$API/director/videos/upscale" \
  -H "Authorization: Bearer $PIXIO_API_KEY" -H "Content-Type: application/json" \
  -d "{\"job_id\":\"$FINAL\"}"

curl -s -X POST "$API/director/videos/finish" \
  -H "Authorization: Bearer $PIXIO_API_KEY" -H "Content-Type: application/json" \
  -d "{\"job_id\":\"$FINAL\",\"grade\":\"warm\"}"

curl -s -X POST "$API/director/videos/facefix" \
  -H "Authorization: Bearer $PIXIO_API_KEY" -H "Content-Type: application/json" \
  -d "{\"job_id\":\"$MV\",\"sections\":[2,4]}"
```

A face fix holds 59 per section and charges only for sections it visibly changed (`faceFixReport`). It redraws one face per shot, so two-person shots change little.

## Related

* [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)
* [Director API overview](https://support.myapps.ai/integrations/director-api.md)


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