Videos need a plan that includes Content (the Growth Marketing Manager). Without it every endpoint here
returns
403 plan_not_included.Pricing
Each video is priced at what the providers that make it charge us (presenter renders, generated shots and pictures, narration, rendering) plus a small markup, and is charged once, at the moment it is released to render:- with your own
script, when you create it; - otherwise, when its written script is approved (automatically or by you).
400 and nothing is bought.
Quote first. POST /v1/videos/quote takes the same body as POST /v1/videos and returns the price,
without making anything:
script the quote is exact. Without one, the words (or shots, or slides) are not written
yet, so the quote is an estimate from target_duration_seconds (estimated: true) and the charge at
approval is for what was actually written. Every video also shows price_cents (what it costs now, or
was charged) and billed_cents (what it was charged, once released).
Cap it. Pass max_price_cents when you create a video. With your own script, a video above the cap
is rejected with 400 before anything is created. With a script approved automatically, one that comes
out above the cap is not approved: it waits in script_review with the reason in error, for you to
shorten and approve (or delete). When you approve by hand, pass max_price_cents to
POST /v1/videos/{id}/approve instead.
Templates
template picks the recipe, and preset a style within it (omit it for the template’s default).
Templates marked No write their own script scene by scene (or slide by slide), so sending
script
with them is a 400. The self-recorded style (where you film yourself) needs an upload in the
dashboard and is not available here.
Everything else the dashboard’s Configure step sets is in the body: format (vertical or
horizontal), target_duration_seconds, the presenter (avatar_provider, replica_id, avatar_id,
voice_id, voice_model, avatar_layout), the background (background_mode, background_image),
cutaways (b_roll, b_roll_sources, b_roll_opening, b_roll_motion_style), captions (subtitle_style), the video model for freeform_ai, slide settings for slideshow, the clip for
real_footage and meme_hook, the device for phone_mockup, and a site_demo’s demo_focus and demo_login (it needs a source_url). Settings a template does
not use are ignored. Presenters and voices can’t be listed through the API yet: leave out
replica_id and avatar_id for the default presenter.
Real footage. stock_footage must be a clip filmed in the video’s format: the vertical and
horizontal libraries are different clips. on_screen_caption is one caption, or up to three shown
one after another (separate them with a blank line). This template has no spoken captions; subtitle_position
(top, the default, middle or bottom) and subtitle_size place and size its written captions instead.
Captions. subtitle_style burns in captions of what is said:
classic (outlined white, a line or two), boxed (white on a dark box), bold_words (a few big
yellow words at a time), dynamic (each word appears as it is said, and the line clears after a
pause or about six words), dynamic_highlight (like dynamic, with a black border on the text and
only the newest word in yellow), emphasis (like dynamic, with a black border on the text and the
important words in yellow), highlight (a few words at a time with the word being said in yellow,
then the next few) or one_word (only the word being said, replaced by the next as it starts). The
default is none. They sit
along the bottom of the frame at the style’s own size unless subtitle_position (top, middle
or bottom) or subtitle_size (small, medium or large) says otherwise. subtitle_emojis
floats an emoji beside them at the few moments that deserve one (a question, a shocking fact, the
call to action), chosen from what is said.
Device Greenscreen. phone_mockup plays one of your sources (phone_screen: video, website
or photos) on the screen of a real, filmed device. device_clip picks the device, and must be a clip
filmed in the video’s format; leave it out and one is picked whose screen suits the shape of your
content. A clip whose slug ends in -backdrop was filmed against a green backdrop: device_background
names the built-in photo that stands behind it.
Name and brief. title names the video; leave it out and the title is written from the script.
brief says what you want this video to be, in a sentence or two (the subject, the audience, the
feel), and the script is written to it. Both are optional, and the brief comes back on the video.
Sources. Give at least one of source_url (your website) or source_text (a description). Images
and videos must already be in LumisReach (source_image_urls, source_video_urls); there is no upload
endpoint in the API yet, so upload them in the dashboard or describe the business in source_text.
Script up front, or review
TRACK_ID is a track_id from GET /v1/videos/music.
- Your own
script: spoken word for word. The video skips review, is charged, and starts rendering right away. - No
script,script_review: "auto"(the default): a script is written from your sources and approved as soon as it is written, which charges it (withinmax_price_cents). - No
script,script_review: "manual": the video stops inscript_review. Read the script (orscenes,slides,interview) withGET /v1/videos/{id}and its price inprice_cents, then approve it withPOST /v1/videos/{id}/approve, sending{}or your edits.
201 with the video. Poll GET /v1/videos/{id}:
A video takes a few minutes; long ones and AI-generated scenes can take longer.
Downloading
video_url and thumbnail_url are signed links to the finished files. They need no API key and don’t
expire, so you can download the MP4 or hand the link to another service; treat them like a share link.
Posting
List the accounts connected in Dashboard → Connections, then post:caption defaults to the video’s caption and hashtags. Omit scheduled_for to post now. A slideshow
can go out as its slides with "media_type": "carousel" (TikTok and Instagram). Each account gets its
own post; follow them with GET /v1/videos/{id}/posts, and cancel one that is still scheduled with
DELETE /v1/posts/{id}. Posting is free.