Skip to main content
POST
Create a video

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string

A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.

Body

application/json
template
enum<string>
default:talking_avatar
required

Which recipe makes the video: ai_videographer (the AI edits like a human editor: animation, real footage, photos, cutouts and a presenter on camera, with a narrator), talking_avatar (a presenter over your site), remotion (motion graphics with a narrator), site_demo (an automated demo: an agent clicks through your website, screen-recorded, with a narrator), freeform_ai (one generated clip per scene), meme_hook (a viral clip into your presenter), interview (2 to 4 avatars in a split screen), phone_mockup (your video, site or photos on a phone in a hand), slideshow (captioned still slides) or real_footage (a real stock clip with a caption).

Available options:
ai_videographer,
talking_avatar,
remotion,
site_demo,
freeform_ai,
meme_hook,
interview,
phone_mockup,
slideshow,
real_footage
format
enum<string>
default:vertical
required

vertical (9:16) or horizontal (16:9)

Available options:
vertical,
horizontal
target_duration_seconds
enum<number>
default:30
required

Roughly how long a written script runs. Ignored when you send script. Each template supports its own subset.

Available options:
10,
15,
20,
30,
45,
60,
120,
180,
300
avatar_layout
enum<string>
default:center
required

Where the presenter sits. audio_only is for an automated demo only.

Available options:
center,
bubble_bottom_left,
bubble_bottom_right,
audio_only
background_mode
enum<string>
default:static
required

What the presenter stands in front of: static (a still of the site), scrolling (scrolls the site or several images), footage (your uploaded video), automated_demo (an agent clicks through your product), original (the presenter's own set) or image (a photo).

Available options:
static,
scrolling,
footage,
automated_demo,
original,
image
script_review
enum<string>
default:auto
required

Without your own script, one is written first. auto approves it (and charges the video) as soon as it is written; manual stops in script_review until you call POST /v1/videos/{id}/approve. Ignored when you send script: your script needs no review.

Available options:
auto,
manual
preset
string

A style of that template, e.g. imessage for remotion. Omit for the template's default.

title
string

Your name for the video. Kept as its title; omit it and the title is written from the script.

Required string length: 1 - 100
brief
string

What you want this video to be, in a sentence or two: the subject, the audience and the feel. The script is written to it. Ignored when you send script.

Required string length: 1 - 1000
language
enum<string>

The language the video is made in, as a code (en, es, fr, de, pt-BR, ja, ...): the script, the voiceover, on-screen text, subtitles, the title, the caption and the hashtags are all written and spoken in it, whatever language the sources are in. Default en. Your own script is spoken as you wrote it. INTERVIEW is made in en only: any other language is refused.

Available options:
en,
en-GB,
en-AU,
es,
es-ES,
fr,
fr-CA,
de,
it,
pt-BR,
pt,
nl,
pl,
sv,
da,
no,
fi,
cs,
el,
hu,
ro,
ru,
uk,
tr,
ar,
he,
hi,
zh,
zh-Hant,
zh-TW,
zh-Hans-TW,
yue,
yue-Hans,
ja,
ko,
id,
ms,
fil,
vi,
th
source_url
string<uri>

The website the video is about

source_text
string

A description of the business, product or offer, in your words

Required string length: 1 - 5000
source_image_urls
string<uri>[]

Images already uploaded to LumisReach, in the order the video shows them

Maximum array length: 10
source_video_urls
string<uri>[]

Videos already uploaded to LumisReach, in order

Maximum array length: 5
source_image_kinds
(enum<string> | null)[]

What each of source_image_urls is, in the same order: screen (a screenshot), photo, logo (your logo: shown by the end logo scene and nowhere else in the video) or other (a flyer, a chart, an illustration). null, or leaving the list out, has us read the image and decide.

Maximum array length: 10
Available options:
screen,
photo,
logo,
other
source_video_kinds
(enum<string> | null)[]

What each of source_video_urls is, in the same order: talking (someone talking to the camera), broll (footage to cut away to) or screen (a screen recording). null, or leaving the list out, has us read the video and decide.

Maximum array length: 5
Available options:
talking,
broll,
screen
script
string

Your own script, spoken word for word. Only for templates that read a script (talking_avatar, meme_hook, phone_mockup, real_footage), and for a slideshow, whose post text it is (up to 4000 characters). The video skips script review and is charged when it is created; a slideshow's slides are still planned from it, so it is reviewed as script_review says.

Required string length: 1 - 60000
avatar_provider
enum<string>

Who renders the presenter. Left out with a replica_id or avatar_id, that presenter is a Tavus one. Left out with neither, it is tavus for an interview (cast from its stock faces) and heygen otherwise. HeyGen without replica_id or avatar_id uses one of its pre-made presenters, chosen to fit the source text where one does; Tavus without them uses the account's default presenter.

Available options:
heygen,
tavus,
elevenlabs
avatar_id
string<uuid>

One of your saved avatars (required for ElevenLabs)

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
replica_id
string

A pre-made presenter: a Tavus face or a HeyGen look

Required string length: 1 - 100
heygen_engine
enum<string>

HeyGen only. Omit for the most advanced engine the look supports.

Available options:
avatar_iii,
avatar_iv,
avatar_v
voice_id
string

An ElevenLabs avatar's voice, or the narrator of a narrated template: an ElevenLabs voice id, a Cartesia voice as cartesia:<voice id>, a Fish Audio voice as fish:<voice id>, or a built-in speaker as openai:<name> (e.g. openai:ash). A narrator left unset is the ElevenLabs default, spoken with eleven_v4

Required string length: 1 - 100
voice_model
string

The ElevenLabs speech model an ElevenLabs narrator is spoken with: eleven_v4, the only one. The retired eleven_v3, eleven_multilingual_v2 and eleven_flash_v2_5 are still accepted and spoken with eleven_v4. Ignored for any other narrator.

interview_cast
(object | null)[]

interview only: who is in each window, in order. A null window is cast for you.

Maximum array length: 4
background_image

image background: a built-in photo's slug, or upload:<index> for one of your images

Available options:
modern-office,
classical-hall,
library,
city-skyline,
city-street,
mountains,
park,
beach,
cafe,
loft
b_roll
boolean

talking_avatar: cut away to B-roll while the presenter talks (never while they talk about what is behind them). freeform_ai: cut away to B-roll over the generated scenes while the narration carries on. remotion: cut to B-roll scenes between the drawn ones; each comes on once the scene before it has finished, with the narration over it.

b_roll_sources
enum<string>[]

With b_roll: what it is made of; several is a mix, chosen per cutaway or scene. For talking_avatar: stock (filmed stock footage), motion_graphics (one animated scene of the point being made), ai (a 5 second clip generated for the topic, charged per clip), youtube (a few seconds cut from a real YouTube video of a named event, person, product or moment the script refers to, charged per clip; third-party footage, credited in the caption, which a platform may mute or take down), online_image (the real photo of the very person, product, event or place the script names, found on Google Images and held full frame for a few seconds, charged per photo; third-party photos, credited in the caption) or greenscreen (one of your own screenshots or screen recordings from source_image_urls and source_video_urls, shown on a filmed phone or laptop, whichever fits its shape) or image (one of your own source_image_urls held full frame for a few seconds; see b_roll_images). Or any, alone: the planner picks per cutaway from all of those the video can use, and decides whether the video ends on an end card. For freeform_ai: the same, but ai, since its scenes are generated clips already. For remotion: automated_demo (a recording of your product being clicked through; needs source_url, takes demo_focus and demo_login), stock, ai, talking_avatar (a presenter says that scene on camera in their original background; HeyGen or Tavus, chosen with avatar_provider and replica_id or avatar_id, charged per second) uploaded (shots cut from source_video_urls), image (one of your own source_image_urls held full frame for the line about what it shows, blended in and out), youtube or online_image (as for talking_avatar, held for the length of the scene). Default ["stock"].

Required array length: 1 - 11 elements
Available options:
any,
stock,
motion_graphics,
ai,
youtube,
online_image,
greenscreen,
image,
uploaded,
automated_demo,
talking_avatar
b_roll_images
integer[]

With the image B-roll source: which of source_image_urls the cutaways may show, by index from 0. Each is shown at most once, on the words about what it shows. Omitted, the planner chooses among your photos.

Maximum array length: 8
Required range: 0 <= x <= 9007199254740991
b_roll_opening
boolean

With b_roll: let the video open on a cutaway instead of on the presenter. Default false.

b_roll_layouts
enum<string>[]

With b_roll, on talking_avatar, video_edit or freeform_ai: where in the frame a cutaway may play; several is a mix, each cutaway in the one that suits its footage. full_screen covers the whole video; top_third (vertical videos only) plays across the top third, blurred into the presenter below, for wide footage; side_third (horizontal videos only) plays down the third on the side away from the presenter, for upright footage; picture_in_picture is a floating box kept clear of the presenter, faces and on-screen text, moving as the presenter does (where nowhere is clear it takes your next layout, or with none, the spot that covers least); top_half (vertical videos only) plays across the top half, the presenter moved down below it with their head and shoulders in view; right_half (horizontal videos only) plays down the right half. Or any, alone: each cutaway in whichever of those suits it (never top_half or right_half). Layouts the video's format does not offer are dropped. Default ["any"].

Required array length: 1 - 7 elements
Available options:
any,
full_screen,
top_third,
side_third,
picture_in_picture,
top_half,
right_half
b_roll_end_scene
boolean

talking_avatar or freeform_ai, with or without b_roll: join an end card (a motion-graphics scene, for example a like and follow card, or where to book) to the end of the video, played after it has finished. It is always drawn, never footage. Drawn in b_roll_motion_style. Default false.

b_roll_end_scene_text
string

With b_roll_end_scene: the line the end card shows. Omitted, it is written for the video.

Maximum string length: 70
b_roll_end_scene_sound
enum<string>

With b_roll_end_scene: the sound effect the scene comes on with. Omitted is none.

Available options:
sparkle,
pop,
whoosh,
ding,
chime,
success,
notification,
impact,
riser
b_roll_end_scene_voice_id
string

With b_roll_end_scene: the voice that says the end card's line out loud as it plays, an ElevenLabs voice id or a built-in speaker such as openai:ash. Omitted is no voiceover.

Required string length: 1 - 200
b_roll_motion_style
enum<string>

With motion_graphics B-roll: the remotion style the cutaways are drawn in. Default motion-graphics-1.

Available options:
motion-graphics-1,
launch-video,
motion-graphics-2,
motion-graphics-3,
motion-graphics-4,
motion-graphics-5,
motion-graphics-6,
diorama,
clinic,
boutique,
notebook,
newsroom,
keynote,
motion-graphics-7,
motion-graphics-8,
prism,
momentum
videographer_sources
enum<string>[]

ai_videographer only: what its scenes may be made of (the dashboard's "What it may use"); several is a mix, chosen scene by scene. any (alone) is everything below. motion_graphics is synthesized graphics: shapes, 3D, arrows, diagrams, charts and maps drawn in code (leave it out for a video composed of media alone). stock (filmed stock footage), ai (a clip generated for the scene), talking_avatar (a presenter says the line on camera), uploaded (shots from source_video_urls and your website's videos), image (your photos), youtube (a few seconds of a real YouTube video of what the script names, credited) and online_image (the real photo of what the script names, found on Google Images, credited). Default ["any"].

Required array length: 1 - 9 elements
Available options:
any,
motion_graphics,
stock,
ai,
talking_avatar,
uploaded,
image,
youtube,
online_image
videographer_model
enum<string>

ai_videographer only: the Claude model that writes and animates the video (the dashboard's "Claude model"): anthropic/claude-fable-5.2 (most capable, slowest), anthropic/claude-opus-5.5 (deeper reasoning, faster), anthropic/claude-sonnet-5.5 (fast and capable). Default anthropic/claude-opus-5.5.

Available options:
anthropic/claude-fable-5.2,
anthropic/claude-opus-5.5,
anthropic/claude-sonnet-5.5
videographer_actions
integer

ai_videographer only: how much happens on screen, 0 to 100 (the dashboard's "Actions" slider). 100 is full of action, a new shot every few seconds; around 20 to 40 is calm (longer scenes, the presenter on screen longer, media full screen or in half the frame, simple cuts); 0 is long still scenes with straight cuts. Default 100.

Required range: 0 <= x <= 100
presenter_narrates
boolean

ai_videographer only: its HeyGen presenter always says their own lines on camera; true has them narrate the scenes they are off camera in too (one voice throughout), false leaves those to voice_id. Default true.

narration
integer

ai_videographer, remotion, freeform_ai and site_demo: how much of the video a narrator speaks over, 0 to 100. 100 is narrated throughout; 50 is a voice over about half of it, the silent scenes carried by the picture, on-screen words and music; 0 is no narration at all. Default 100.

Required range: 0 <= x <= 100
post_format
enum<string>

slideshow only: what the post is. text is its words alone (X, LinkedIn and Facebook), image its words with one captioned picture, carousel its words with slide_count captioned slides to swipe through. Default carousel. To have the post researched and written to perform on one network, use POST /v1/optimized-posts instead.

Available options:
text,
image,
carousel
post_orientation
enum<string>

slideshow with pictures only: their shape. square (1:1, shown whole on every feed), vertical (9:16, fills TikTok photo mode) or horizontal (16:9, fills an X, LinkedIn or Facebook feed). Default square.

Available options:
square,
vertical,
horizontal
subtitle_style
enum<string>

Captions of what is said, burned in along the bottom of the frame. dynamic adds each word as it is said and clears after a pause or about six words; dynamic_highlight does the same with a black border on the text and only the newest word in colour; emphasis does the same with a black border on the text and the important words in colour; enlarge shows four or five words at a time the same way, with one important word of each set bold and larger; one_word shows only the word being said; highlight shows a few words at a time with the one being said in colour; comic is comic-book lettering, a few big yellow capitals at a time with a heavy outline. Default none. Ignored by real_footage, which has written captions instead; on slideshow it styles the slide captions (classic, boxed or bold_words).

Available options:
none,
classic,
boxed,
bold_words,
dynamic,
dynamic_highlight,
emphasis,
enlarge,
one_word,
comic,
highlight
subtitle_position
enum<string> | null

Where the captions sit. On real_footage null is the top, on slideshow null keeps each slide's own place, and for spoken captions null is along the bottom.

Available options:
top,
middle,
bottom
subtitle_emojis
boolean

Floats an emoji beside the spoken captions at the few moments that deserve one (a question, a shocking fact, the call to action), chosen from what is said. Needs a subtitle_style other than none. Default false.

subtitle_size
enum<string>

How big the captions are drawn, relative to the style's own size. Default medium.

Available options:
small,
medium,
large
video_model
string

freeform_ai only: <model>@<tier>, e.g. seedance-2.5@720p. Omit for the default.

slide_count
integer

slideshow only

Required range: 3 <= x <= 10
slide_source
enum<string>

slideshow only: where the pictures come from: uploaded (your images), website (screenshots), ai (drawn) or google (real photos found on Google Images). Default ai.

Available options:
uploaded,
website,
ai,
google
image_model
string

slideshow with AI pictures: the image model. Omit for the default.

stock_footage
enum<string>

real_footage only: the clip, by slug. It must be one filmed in the video's format.

Available options:
young-woman-braids-portrait,
stylish-senior-woman-hat,
man-coffee-fedora,
woman-curly-hair-turns,
taxi-driver-by-cab,
bald-man-smiling,
asian-woman-laughing,
nurse-in-corridor,
woman-hijab-smiling,
man-dimple-smile,
grandmother-on-sofa,
man-coat-field,
older-man-plants,
young-man-glasses-curls,
construction-worker-hard-hat,
shop-owner-packing-box,
barista-iced-coffee,
man-making-pancakes,
senior-woman-reading,
man-driving-car,
florist-arranging-bouquet,
woman-cooking-spices,
woman-laptop-phone-breakfast,
woman-morning-coffee,
older-man-tea,
grandma-baking-with-granddaughter,
man-typing-laptop,
barista-pouring-milk,
builder-hammering-wall,
woman-treadmill-gym,
older-man-white-beard,
man-glasses-sunset,
woman-hugging-herself,
woman-walks-up-courtyard,
woman-laughing-brick-wall,
woman-laughing-forest,
man-grinning-forest,
bald-man-glare,
man-chin-thinking,
man-gasps-disbelief,
woman-glasses-ties-hair,
barista-pour-over,
market-vendor-tray,
builder-shovelling-sand,
painter-rolling-wall,
support-agent-headset,
man-phone-call-laptop,
older-man-laptop-park,
woman-tablet-cafe,
woman-phone-smiling,
office-worker-late,
pharmacist-typing,
woman-blow-drying-hair,
cook-lifts-pot-lid,
woman-sipping-mug
on_screen_caption
string

real_footage only: the caption over the clip, or up to 3 captions shown one after another, separated by a blank line (each at most 150 characters). Omit to have one written.

Maximum string length: 454
footage_narrated
boolean

real_footage only: whether a narrator reads the script. Default true.

meme_clip_id
string<uuid>

meme_hook: a clip from your library...

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
stock_meme_clip
enum<string>

...or a built-in clip, by slug

Available options:
dramatic-chipmunk,
sneezing-panda,
keyboard-cat,
vibing-cat,
screaming-goat,
coffin-dance,
epic-sax-guy,
rick-roll,
office-rage,
surprised-kitty
phone_screen
enum<string>

phone_mockup: what plays on the device's screen. website scrolls the site and automated_demo clicks through it, either planned with the script from the site's map. Omit to pick video, then website, then photos. With greenscreen B-roll on another template: website makes a cutaway of the site scroll instead of the automated demo it is by default.

Available options:
video,
website,
automated_demo,
photos
device_clip
enum<string>

phone_mockup only: the device clip (a phone, tablet, laptop or monitor with a green screen), by slug. It must be one filmed in the video's format. Omit to have one picked that suits what is on screen.

Available options:
hand-phone,
phone-shop-floor,
phone-scrolling,
phone-in-car,
phone-sideways-sofa,
phone-cafe,
tablet-wood-desk,
tablet-marble-desk,
tablet-coffee-break,
tablet-flat-lay,
laptop-typing,
laptop-alarm-clock,
laptop-sideboard,
monitor-home-office,
phone-hand-city,
phone-hand-grey,
phone-two-hands,
phone-blue-wall,
laptop-living-room,
phone-hand-city-wide,
phone-hand-grey-wide,
phone-sideways-two-hands,
phone-sideways-close,
laptop-window-desk,
laptop-couch-typing,
laptop-navy-room,
laptop-woman-desk,
laptop-white-desk,
laptop-close-up,
phone-sideways-backdrop,
phone-backdrop
device_background
enum<string>

phone_mockup with a device_clip filmed against a green backdrop (a -backdrop slug): the built-in photo behind the device. Omit for the default.

Available options:
modern-office,
classical-hall,
library,
city-skyline,
city-street,
mountains,
park,
beach,
cafe,
loft
demo_focus
string

Site demos: the features to show, in your words

Maximum string length: 1000
demo_login
object

Site demos: sign in first to show the product behind the login

max_price_cents
integer

A spending cap. With your own script the price is known now, and a video above the cap is rejected with 400 before anything is created. Otherwise the written script is priced when it is approved automatically; above the cap it is not approved and waits in script_review with the reason in error. With script_review: manual, pass the cap to the approve call instead.

Required range: 0 <= x <= 9007199254740991
caption
string

The post caption. Omit to use the one written with the script.

Maximum string length: 4000
hashtags
string[]

Hashtags for the post, with or without #

Maximum array length: 30
Maximum string length: 101
music
object

Background music mixed under the finished video: any track GET /v1/videos/music lists, from the built-in library, Epidemic Sound, your AI-generated tracks or commercial music. A track that cannot be used is a 400 before the video is made. A talking_avatar video sent without it gets a random royalty-free track. There is no level to set: the music plays at full volume wherever nobody speaks and comes down to about 30% under speech. Change it later with PUT /v1/videos/{id}/music.

Response

Success

data
object
required