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

# Cast

> Make presenter videos from a saved avatar and a script with Melius Cast over the REST API.

Cast makes a video of an avatar speaking your script. You choose a saved avatar, write the script as sections, and Cast films it with a voice, a background and up to six props. The API runs the same Cast as the Cast studio in Melius, and finished videos appear in Cast's **History**.

Every Cast endpoint lives under `/api/v1/cast`:

```
GET  /cast/options                       → models and settings you can use
POST /cast/library/search                → saved avatars and backgrounds
POST /cast/templates/search              → script templates
POST /cast/videos/prepare                → validate and estimate, without generating
POST /cast/videos                        → start the video (or recover it)
GET  /cast/videos/:generationId  (poll)  → submitting → running → captioning → ready
POST /cast/videos/:generationId/download → signed download URL
POST /cast/generations/search            → your or your team's past videos
```

## 1. Choose an avatar

List your saved avatars with `POST /cast/library/search`. `roster` is `all`, `custom` (your team's) or `melius` (Melius avatars):

```bash theme={null}
curl -X POST https://api.melius.com/api/v1/cast/library/search \
  -H "Authorization: Bearer mel_..." \
  -H "Content-Type: application/json" \
  -d '{ "kind": "avatar", "roster": "all" }'
```

```json theme={null}
{
    "data": [
        {
            "kind": "avatar",
            "avatar": { "kind": "custom", "id": "<avatarId>" },
            "name": "Loopy",
            "imageUrl": "https://...",
            "previewUrl": "https://..."
        }
    ],
    "pageSize": 50,
    "count": null,
    "hasMore": false,
    "nextCursor": null
}
```

Send the item's `avatar` object in your request. You can also send `{ "name": "Loopy" }`; a name that matches several avatars needs the exact `kind` and `id`. List saved backgrounds the same way with `"kind": "background"` and send the returned `backgroundId`.

## 2. Prepare the video

`POST /cast/videos/prepare` checks your request, fills in defaults and estimates the credits. It doesn't generate anything or charge credits.

```bash theme={null}
curl -X POST https://api.melius.com/api/v1/cast/videos/prepare \
  -H "Authorization: Bearer mel_..." \
  -H "Content-Type: application/json" \
  -d '{
    "avatar": { "kind": "custom", "id": "<avatarId>" },
    "sections": [
      { "text": "Mornings used to be chaos. Then I found this serum." },
      { "text": "Two drops, and I am out the door.", "action": "Holds up the bottle to the camera" }
    ],
    "props": [{ "assetId": "<productImageId>", "name": "serum" }],
    "aspectRatio": "9:16"
  }'
```

The script is 1–30 `sections`. Each has the spoken `text` (up to 5,000 characters) and an optional `action` describing what the avatar does on screen (up to 2,000 characters), which is not read aloud. Optional fields:

* `voice` — leave it out to use the avatar's saved voice. Send `{ "kind": "stock", "voiceId": "..." }` or `{ "kind": "custom", "customVoiceId": "..." }` for another voice, or `{ "kind": "auto" }` to generate one. `GET /audio/voices` lists voices.
* `otherAvatars` — up to two more avatars in the same video, or up to seven with a [large cast](#large-cast). A section's `speakerId` names who says it.
* `backgroundId` — a saved background. Cast chooses a scene from the script otherwise.
* `props` — up to six images, each `{ "assetId", "name"? }`. Upload images with the endpoints under **Uploads**. Avatars, backgrounds and props share the model's reference-image limit.
* `tone` — how the avatar delivers the script, such as `warm` or `deadpan`.
* `engine`, `resolution`, `aspectRatio` (default `9:16`) and `subtitles` — `GET /cast/options` lists what each model supports and the subtitle presets.
* `scriptTemplate` — `{ "id", "revision", "source": "database" }` from `POST /cast/templates/search`, to start from a template's script and settings.
* `creationSettings` — `{ "videoStyle": { "id", "version": 1 }, "speech" }`, where `speech` is `on-screen` or `narration`. See [Video styles](#video-styles). It also takes `visuals` and `visualsBrief`; see [Added visuals](#added-visuals).
* `useFreeGeneration` — `true` spends one of your team's free generations instead of credits, `false` bills credits. Send `false` to add visuals: a video that leaves it out, or sends `true`, has none.

A section with `"kind": "action"` and empty `text` is a silent beat: the camera films its `action` with nothing said.

The response has a `status`:

| `status` | Meaning |
| - | - |
| `ready` | Ready to start. `estimatedCredits` is the estimate. |
| `invalid` | The request can't be made as sent. `validationError` says why. |
| `estimate_unavailable` | The request is valid but the estimate isn't available right now. Try again. |

A ready response also has an `attemptId`, the resolved `input`, a `review` of the avatar, voice, background, props and settings, and the script's length in `scriptSeconds`. Save the whole response. The estimate is not a credit reservation or a price guarantee. A **Before & after** video is charged no more than the estimate its preparation returned.

## 3. Start the video

Send the `attemptId` and `input` from preparation, unchanged, to `POST /cast/videos`. Starting a video needs an editor role on the team and charges its credits to the team.

```bash theme={null}
curl -X POST https://api.melius.com/api/v1/cast/videos \
  -H "Authorization: Bearer mel_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <saved UUID>" \
  -d '{
    "attemptId": "<attemptId>",
    "preparationToken": "<preparationToken>",
    "expectedEstimatedCredits": 120,
    "input": { ...input from prepare... }
  }'
```

Include `preparationToken` when preparation returned one. `expectedEstimatedCredits` is optional: send the `estimatedCredits` you showed, and if the estimate has changed or expired, the request is refused with the code `CAST_PREPARATION_REQUIRED` and starts nothing. Prepare again to get a new estimate.

The response has the `generationId` and its `status`. If you lose the response, resend the identical request: the same `attemptId` returns the same video instead of starting another. Changing the input under an accepted `attemptId` is a conflict. Prepare again for a deliberately new video. See [Retry a submission safely](https://docs.melius.com/api/overview.md#retry-a-submission-safely).

## 4. Get the result

Poll `GET /cast/videos/<generationId>` until `status` is `ready` or `failed`. `submitting`, `running` and `captioning` mean it is still working; `captioning` means Cast is adding the subtitles you asked for.

```bash theme={null}
curl https://api.melius.com/api/v1/cast/videos/<generationId> \
  -H "Authorization: Bearer mel_..."
```

A `ready` video has `url`, `assetId` (the video in your team's **Assets**) and `outputVersionId`. If subtitles fail after retries, the video is ready without them, with a `warning`, and the subtitle credits are refunded. A `failed` video has a `message`.

For a fresh signed download link, call `POST /cast/videos/<generationId>/download`. It returns `url` and `filename`.

## Video styles

`creationSettings.videoStyle.id` sets how Cast films the script. `GET /cast/options` lists in `videoStyles` the styles your team can use.

| `id` | What it films |
| - | - |
| `auto` | The style the script reads as |
| `self-filmed` | A phone propped up at home, talking to camera |
| `produced` | A camera on a tripod, shaped light, graded, like an ad |
| `drama` | A scored scene between two people, one face per shot |
| `vlog` | Handheld, moving through places over a day |
| `podcast` | Seated at a mic with headphones, studio sound |
| `unboxing` | At a table, opening the package on camera |
| `tutorial` | How to do something, step by step |
| `announcement` | Upbeat news, on a tripod with shaped light |
| `explainer` | One idea explained, on a tripod with shaped light |
| `founder-story` | A personal story told from where they work |
| `before-after` | The problem, the change and the result |
| `corporate-training` | An office tripod, flat light, scripted delivery |
| `storytime` | In bed at night by one lamp, venting |
| `comment-reply` | A self-filmed reply to the comment the script quotes |
| `streamer-reaction` | A webcam over the monitor, headset on |
| `animated-3d` | Rendered like a 3D animated feature |
| `street-interview` | Stopped outside, a handheld mic held to them |
| `product-film` | Product style: the product on a cinematic set, narrated off camera |
| `product-asmr` | Product style: macro shots and the product's own sounds, whispered |
| `product-3d` | Product style: the product in 3D, narrated off camera |
| `product-stop-motion` | Product style: the product moved frame by frame, narrated off camera |
| `asmr` | The avatar whispers each line close to the lens |
| `claymation` | The avatar and the set in clay |
| `animated-2d` | The avatar as a 2D cartoon character |

### Product styles

> [!NOTE]
>
> **Beta** — this feature is rolling out gradually. Reach out to support if
> you'd like access.

`product-film`, `product-asmr`, `product-3d` and `product-stop-motion` film your product, from its photo, with nobody on camera:

* Send the product photo in `props`. Several products can share a section: name each one in that section's `action` as `@[name]{prop:<assetId>}`.
* Write each `action` about the product and its place. A direction that names a person, or uses a pronoun for one, is refused; hands are the most it can show.
* The avatar narrates every line off camera in their own voice. Leave out `otherAvatars`.

For `asmr`, send a product photo in `props` for the avatar to handle on camera.

### Motion speeds

> [!NOTE]
>
> **Beta** — this feature is rolling out gradually. Reach out to support if
> you'd like access.

A silent beat's `action` can ask for slow motion, a speed ramp or a time-lapse ("in slow motion", "time-lapse"). A section with spoken `text` always plays at real speed, and a time-lapse that shows a prop is refused.

### Large cast

> [!NOTE]
>
> **Beta** — this feature is rolling out gradually. Reach out to support if
> you'd like access.

`otherAvatars` takes up to seven avatars, eight people in all. One clip films at most three of them, so a line that brings in someone new starts the next clip.

## Added visuals

> [!NOTE]
>
> **Beta** — this feature is rolling out gradually. Reach out to support if
> you'd like access.

Cast can add images, diagrams and motion graphics over the finished video. Added visuals need `"useFreeGeneration": false`, and cost nothing beyond the video. The `review` shows `visuals` as `Auto`, `Off` or `Unavailable`; when it's `Unavailable`, `visualsUnavailableReason` names the field to change.

* `creationSettings.visuals` — `auto` lets Cast choose visuals from the script, and `off` adds none. Left out, it's `auto` for `explainer` and `corporate-training`, and for a script that asks for visuals; `off` otherwise.
* A section's `onScreen` — what to show while that line is spoken, in your words. It's never filmed.
* `creationSettings.visualsBrief` — the look of every visual: colors, type, motion and mood.
* An `action` that quotes text for the screen, such as `On screen: "50% off"`, shows those words.
* In a video of several people, an `action` such as `Lower third: "Maya, dermatologist"` names that person on screen.

A request with `onScreen` or `visualsBrief` that sets `visuals` to `off`, or that can't have visuals, is refused with the reason in `validationError`.

## Browse past videos

`POST /cast/generations/search` lists Cast videos with the settings each used. Filter with `filters.scope` (`mine` or `team`) or `filters.generationId`. Add `"includeReplacements": true` to include your Ditto videos.

```bash theme={null}
curl -X POST https://api.melius.com/api/v1/cast/generations/search \
  -H "Authorization: Bearer mel_..." \
  -H "Content-Type: application/json" \
  -d '{ "filters": { "scope": "team" }, "pageSize": 24 }'
```

List endpoints are paged: pass `nextCursor` as `cursor` while `hasMore` is true.


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