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

# TV series

> Save a show once — premise, look, cast, theme and title card — then make episodes that remember what came before

Use a **series** when you'll make more than one episode with the same people and places. You save the show once; every episode is then written from it, with a recap of the earlier episodes, and opens with the show's title card and theme.

Saving and changing a series is free. Each episode is a normal Director job, priced like an AI-written film plus its recap and packaging.

## How it fits together

| Piece | What it is |
| - | - |
| **Series** | The show: `name`, `premise` (its world and tone, for the writer), `style` (one look for every episode), `aspect` (`16:9`, `9:16` or `1:1`), a `theme` and a `title_card` |
| **Cast** | People, places and things (`kind`: `person`, `place`, `thing`), each with a description, a picture and, for people, a voice |
| **Episode** | One film job made from the series. When it finishes, its recap is saved and the show learns new faces and voices from it |

## Save a series

`POST /api/v1/director/series` — multipart or JSON. Answers `201` with the series.

```bash theme={null}
curl -s -X POST https://beta.pixio.myapps.ai/api/v1/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 style="soft coastal light, muted blues" \
  -F aspect=16:9 \
  -F theme=@theme.mp3 \
  -F theme_s=8 \
  -F 'cast=[{"name":"Mara","what":"The innkeeper, late 60s, silver braid","kind":"person"}]'
```

* **Title card** is on by default and reads "NAME / Episode N: Title".
* **Theme** plays under the opening for `theme_s` seconds (default 10). Instead of uploading one, send `theme_auto=true` or a `theme_brief` to have it made once — **36 credits**, charged when the series is saved.
* **`laugh_track`** (`light` or `full`) puts studio-audience laughs in every episode (16 credits an episode).
* **Name** is required, up to 200 characters. At most **50 series** per account (`409 conflict`).

## Add the cast

Two ways:

> [tab] One member at a time
>
> `POST /director/series/{id}/cast` adds a member, or changes one matched by `name`. Answers with the whole series.
>
> ```bash theme={null}
> curl -s -X POST https://beta.pixio.myapps.ai/api/v1/director/series/$SERIES/cast \
>   -H "Authorization: Bearer $PIXIO_API_KEY" \
>   -F name=Mara \
>   -F what="The innkeeper, late 60s, silver braid, wool cardigan" \
>   -F kind=person \
>   -F picture=@mara.jpg \
>   -F voice=@mara-voice.wav \
>   -F voice_what="low, warm, unhurried"
> ```
>
> `voice` is 5–15 s of them speaking.

> [tab] All at once
>
> On the series itself: `pictures` (1–9) with `references` saying what each shows — the cast name is the text before the first comma — and `voice_samples` (0–3) with `voices` saying whose each is.
>
> ```bash theme={null}
> -F pictures=@mara.jpg -F pictures=@inn.jpg \
> -F 'references=["Mara, the innkeeper","The inn, a white lighthouse on a cliff"]'
> ```
>
> On a change, new `pictures` or `voice_samples` **replace all the old ones**.

Without pictures or voices, the first episode's become the show's own.

**Limits:** cast `name` 60, `what` 400, `voice_what` 200 characters. Over a limit returns `400 invalid_request` naming the field (e.g. `cast.what`).

Remove a member, or only their picture or voice, with `DELETE /director/series/{id}/cast/{name}` (`?part=picture` or `?part=voice`). Read a member's files at `GET …/cast/{name}/picture` or `…/voice`, and the series' pictures at `GET /director/series/{id}/picture?n=1`.

## Make an episode

`POST /api/v1/director/series/{id}/episodes` answers `202` with a Director job. Poll it like any job.

| Field | Notes |
| - | - |
| `idea` | **Required.** What happens, 10–4,000 characters. Name the cast members in it — their pictures and voices go first |
| `duration` | 30–420 seconds, a multiple of 15 (default 60) |
| `speed` | `draft` for a cheaper first cut |
| `number` | The episode number |
| `previously` | Your own recap of the story so far, up to 3,000 characters |
| `voice_lock` | `auto` (default: on only when someone in it has no voice yet), `true` or `false` |
| `face_fix` | `auto` to fix faces that drifted, billed per fixed section |
| `visual_qa` | `local` or `full` |
| `package` | Extra packaging on top of the title card and theme |

```bash theme={null}
curl -s -X POST "https://beta.pixio.myapps.ai/api/v1/director/series/$SERIES/episodes?dry_run=true" \
  -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
```

`?dry_run=true` is free and returns the quote. Drop it to make the episode.

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

## After it renders

`GET /director/series/{id}/episodes` lists every episode with its title, idea, recap, open threads, lasting changes, what the show learned, status and `jobId` — the episode's Director job, so you can download, retake or finish it.

Redo and final work on an episode exactly like on a film: `POST /director/videos/film/{jobId}/redo` and `…/final`.

## Changing and deleting

* `POST /director/series/{id}` changes a series — send only what changes. `remove_theme=true` drops the theme.
* `DELETE /director/series/{id}` deletes it. Episodes already made stay as your jobs.

## Related

* [Recipes](https://support.myapps.ai/director-api/recipes.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.