/api/v1/cast:
1. Choose an avatar
List your saved avatars withPOST /cast/library/search. roster is all, custom (your team’s) or melius (Melius avatars):
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.
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/voiceslists voices.otherAvatars— up to two more avatars in the same video, or up to seven with a large cast. A section’sspeakerIdnames 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 aswarmordeadpan.engine,resolution,aspectRatio(default9:16) andsubtitles—GET /cast/optionslists what each model supports and the subtitle presets.scriptTemplate—{ "id", "revision", "source": "database" }fromPOST /cast/templates/search, to start from a template’s script and settings.creationSettings—{ "videoStyle": { "id", "version": 1 }, "speech" }, wherespeechison-screenornarration. See Video styles. It also takesvisualsandvisualsBrief; see Added visuals.useFreeGeneration—truespends one of your team’s free generations instead of credits,falsebills credits. Sendfalseto add visuals: a video that leaves it out, or sendstrue, has none.
"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 theattemptId 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.
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
PollGET /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.
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’sactionas@[name]{prop:<assetId>}. - Write each
actionabout 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.
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.
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.
"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—autolets Cast choose visuals from the script, andoffadds none. Left out, it’sautoforexplainerandcorporate-training, and for a script that asks for visuals;offotherwise.- 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
actionthat quotes text for the screen, such asOn screen: "50% off", shows those words. - In a video of several people, an
actionsuch asLower third: "Maya, dermatologist"names that person on screen.
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.
nextCursor as cursor while hasMore is true.