Skip to main content
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:

1. Choose an avatar

List your saved avatars with POST /cast/library/search. roster is all, custom (your team’s) or melius (Melius avatars):
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.
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. 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. It also takes visuals and visualsBrief; see 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: 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.
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.

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

Product styles

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

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

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

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.
List endpoints are paged: pass nextCursor as cursor while hasMore is true.
Last modified on November 18, 2026