Making videos through the API comes with the API & MCP plan, the Growth Marketing Manager hire, and the
Revenue Engine and Custom plans. On any other plan,
POST /v1/videos and POST /v1/videos/{id}/approve
return 403 plan_not_included.Pricing
What a video costs depends on the plan:
A charged video is priced at what the providers that make it charge us (presenter renders, generated
shots and pictures, narration, rendering) plus 20%, 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. On Revenue Engine and Custom, quotes still show what a video
would cost, and billed_cents is 0. Every charge shows up as ai_video in GET /v1/billing/events,
labelled “via API”.
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, so sending
script with them is a
400. A slideshow’s script is the post’s own text, posted as you send it (up to 4,000 characters):
its slides are planned from it, so it is still reviewed as script_review says. 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.
AI Videographer. The dashboard’s default for a new video, and the best one for most businesses.
It writes the story first, then cuts it into scenes and places media in each. These set what the
dashboard’s Configure step sets for it:
They are refused on any other template.
Posts. A
slideshow is a post. post_format is text (its words alone; X, LinkedIn and
Facebook), image (one captioned picture) or carousel (slide_count slides, the default), and
post_orientation is the pictures’ shape (square, vertical or horizontal). This writes the post
plainly from your sources. To have it researched and written to perform on one network, use
Optimized posts.
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. Aslideshowis the exception: its slides are planned from your words first, then approved asscript_reviewsays, like a written one. - 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.
Editing a finished video
POST /v1/videos/{id}/edit changes a ready (or failed) video and makes it again, like Apply
changes in the dashboard. Change, remove or regenerate scenes by the ids GET /v1/videos/{id}
returns, send a new script, a new narrator (voice_id), or restyle the captions:
price_cents.
A captions-only edit is redrawn in seconds and is free. Above max_price_cents the edit is refused with
400 and nothing changes. The video goes back to rendering; poll it until it is ready again.
Scene templates edit their scenes, narrator and captions; talking_avatar and phone_mockup their
script; real_footage its on-screen caption. Posts, imported videos and interviews cannot be edited
this way.
To change only the caption and hashtags its posts start from (for a post, its text), use
PATCH /v1/videos/{id} with caption, hashtags or both. It is free and makes nothing again.
Music
GET /v1/videos/music lists tracks from one library; put one on a video with
music: { library, track_id } when you create it, or later with PUT /v1/videos/{id}/music
(DELETE takes it off). GET /v1/videos/music/catalog says what each library offers to browse and
whether it is set up.
A premium Epidemic track needs
accept_price_cents set to its price_cents: sending it agrees to the
charge. Commercial music needs your workspace’s confirmation that it holds the rights to it, which only
a person can give, in the dashboard (Music & caption → Commercial Music); until then it is a 403.
A commercial listing is kept for a day; one that has to be looked up live is charged at what it costs
(about $0.07 for a search, $0.12 for a category).
music.status goes mixing, then applied.
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. GET /v1/posts lists every post still
scheduled across the workspace; move one with PATCH /v1/posts/{id} ({ "scheduled_for": ... }) or call
it off with DELETE /v1/posts/{id}. Each connection says whether it can post (can_publish) and whether
the platform dropped its sign-in (needs_reconnect); reconnect those in the dashboard. Posting is free.