Skip to main content
POST
Quote 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: 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:
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
​
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
​
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). The video skips script review and is charged when it is created.

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, or a built-in speaker as openai:<name> (e.g. openai:ash, the default)

Required string length: 1 - 100
​
voice_model
string

The ElevenLabs speech model an ElevenLabs narrator is spoken with: eleven_v4 (the default), eleven_v3, eleven_multilingual_v2 or eleven_flash_v2_5. Ignored for a built-in speaker.

​
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). 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) 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 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) or uploaded (shots cut from source_video_urls). Default ["stock"].

Required array length: 1 - 9 elements
Available options:
any,
stock,
motion_graphics,
ai,
greenscreen,
image,
automated_demo,
talking_avatar,
uploaded
​
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_end_scene
boolean

talking_avatar, 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,
motion-graphics-7,
motion-graphics-8
​
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. 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,
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. Default ai.

Available options:
uploaded,
website,
ai
​
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 only: what plays on the device's screen. Omit to pick video, then website, then photos.

Available options:
video,
website,
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-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

Response

Success

​
data
object
required