Create Scenes Video
Videos
Scenes
Create multi-scene videos combining avatars, video clips, and AI-generated transitions
POST
Create Scenes Video
Try it out! Use the API playground on the right to test the Scenes endpoint directly.
Overview
Scenes allows you to create complex, multi-scene videos by combining different content types in a storyboard format. Each scene can be one of four types:- Avatar: A talking avatar scene with script and voice
- Video: A video or image clip with optional voiceover
- Picture in Picture: An avatar overlaid on a video/image background
- Start/End Frame: AI-generated video transition between two images
- Long-form content with multiple segments
- Tutorials with avatar explanations and demo clips
- Marketing videos with varied visual styles
- Storytelling with scene transitions
- Educational content mixing talking heads and visuals
Scenes automatically handles transitions between different scene types and maintains consistent captions throughout the video.
Endpoint
Required Fields
Array of scene objects (1-50 scenes). Each scene defines a segment of your video.
Optional Fields
Video name (max 100 characters). If not provided, a name will be auto-generated from the scene scripts.
Background music ID from
/v1/music/list.Caption settings for the video
Video aspect ratio:
ratio_9_16: Vertical (TikTok, Reels, Shorts) - Recommendedratio_16_9: Horizontal (YouTube)ratio_1_1: Square (Instagram)
Language code for the video (2 characters). Example:
en, esHTTPS URL to receive completion notification (max 500 characters). Highly recommended for production use.
Custom metadata object (max 5KB). Store any additional data you need to associate with this video.
Scene Types
Avatar Scene
A talking avatar presents content with synchronized lip movements.script, avatarId, voiceId
Video Scene
A video or image clip plays, optionally with voiceover.mediaId
Picture in Picture Scene
An avatar appears overlaid on a video/image background.script, avatarId, voiceId, mediaId
Start/End Frame Scene
AI generates a video transition between two images.startFrameMediaId, endFrameMediaId, framePrompt
Request Examples
Basic Multi-Scene Video
Tutorial with Picture in Picture
AI Transition Video
Response
Webhook Notification
When your video is ready, we’ll POST to your webhook URL:Webhook Payload
Your webhook endpoint must return a
200 status code. We’ll retry up to 3 times if the request fails.Scene Type Requirements
| Scene Type | Required Fields | Optional Fields |
|---|---|---|
avatar | script, avatarId, voiceId | |
video | mediaId | script, voiceId, |
picture_in_picture | script, avatarId, voiceId, mediaId | |
start_end_frame | startFrameMediaId, endFrameMediaId, framePrompt | frameModel, frameDuration |
AI Models for Start/End Frame
| Model | Description | Best For |
|---|---|---|
kling_2_5 | Kling 2.5 model | Fast generation, general transitions |
veo_3_1 | Google Veo 3.1 | High quality, complex camera movements |
Caption Presets
Available caption presets for thecaption.preset field:
| Preset | Description |
|---|---|
default | Default caption style with bold text and shadow effects |
beast | Bold uppercase style with Komika font |
umi | Yellow glowing text style |
tiktok | Viral & trendy style, perfect for social media |
wrap1 | Wrapped style with red background highlight |
wrap2 | Wrapped style with blue background highlight (uppercase) |
ariel | Bold uppercase style with purple highlight |
hooked | Brand style with purple background |
classic | Clean, simple captions with black background |
active | Green background with bold text |
bubble | White background bubble style |
glass | Glassmorphic transparency effect |
comic | Comic Sans font with colorful style |
glow | Pink and orange glow effects |
pastel | Soft pastel pink background |
neon | Green neon glow effect |
retroTV | Retro TV style with cyan glow |
red | Red glow effect with white text |
marker | Yellow marker/highlighter style |
modern | Contemporary white background style |
blue | Blue background style |
vivid | Vibrant pink background with uppercase text |
Best Practices
Plan Your Storyboard
Outline your scenes before creating. Each scene should serve a clear purpose in the narrative.
Consistent Avatar
Use the same avatar across scenes for continuity, unless intentionally switching perspectives.
Vary Scene Types
Mix avatar, video, and PiP scenes to keep viewers engaged and add visual variety.
Smooth Transitions
Write scripts that flow naturally between scenes. End one scene leading into the next.
Optimize Duration
Keep individual scenes focused. Split long content into multiple shorter scenes.
Use Start/End Frames
Leverage AI transitions for impressive visual effects between static images.
Error Handling
| Error | Description | Solution |
|---|---|---|
At least one scene is required | Empty scenes array | Add at least one scene to the array |
Cannot have more than 50 scenes | Too many scenes | Reduce the number of scenes to 50 or fewer |
Script is required for avatar scenes | Missing script in avatar scene | Add the script field |
Avatar ID is required for avatar scenes | Missing avatarId | Add a valid avatarId from /v1/avatar/list |
Voice ID is required for avatar scenes | Missing voiceId | Add a valid voiceId from /v1/voice/list |
Media ID is required for video scenes | Missing mediaId in video scene | Add a valid mediaId |
Not enough credits | Insufficient credits | Top up your account credits |
Credits
Scenes videos use a credit model based on:- Base credits: Fixed cost per video
- Avatar scene credits: Charged based on script duration (similar to UGC Video)
- Video scenes: Included in base credits (no additional charge)
- Start/End Frame: Additional credits for AI generation
Next Steps
List Avatars
Browse available avatars for your scenes
List Voices
Find the perfect voice for your avatars
List Music
Add background music to your video
Webhooks Guide
Learn how to handle webhook notifications
Authorizations
Body
application/json
Array of scene objects (1-50 scenes)
Required array length:
1 - 50 elementsVideo name (max 100 characters)
Maximum string length:
100Background music ID from /v1/music/list
Maximum string length:
30Video aspect ratio
Available options:
ratio_9_16, ratio_16_9, ratio_1_1 Add AI-generated stickers to enhance video engagement
Language code (2 characters)
Required string length:
2HTTPS URL to receive completion notification
Maximum string length:
500Custom metadata object (max 5KB)