Skip to main content
These endpoints drive the same video maker as Dashboard → Create Video: pick a template, give it your website or a description (and, if you like, the script), and LumisReach writes, renders and composites a social-ready MP4. When it is ready you can download it or post it to TikTok, Instagram, Facebook, X, LinkedIn and YouTube. To keep videos coming on a cadence, see Video schedules.
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.
Want a text post, or a text post with one picture, written to perform on X, LinkedIn or Instagram? Use Optimized posts: the post producer researches your business and competitors and writes it with the tuned writer. A slideshow made here is written plainly from your sources.

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).
Retries are free, and so are quotes, reads and posting. The charge comes out of your plan’s included video credits first, then your prepaid balance. If the workspace cannot pay for a video, the release is refused with 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:
With your own 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. A slideshow is the exception: its slides are planned from your words first, then approved as script_review says, 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 (within max_price_cents).
  • No script, script_review: "manual": the video stops in script_review. Read the script (or scenes, slides, interview) with GET /v1/videos/{id} and its price in price_cents, then approve it with POST /v1/videos/{id}/approve, sending {} or your edits.
Either way the response is 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:
Only what the edit makes stale is made again, and only that is charged: the response’s 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).
A finished video is mixed again in the background; its 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.