Send us your content and instructions. Get a film, a course, or an LMS package back.
A contract for a client application that supplies its own media — HeyGen avatar clips, Higgsfield videos, images — and wants it stitched, captioned, branded, and packaged. The engine is a compositor: you provide the assets, it assembles them.
✦ What Studio can do (and how to ask)
Find it here, say it in plain words, then send the request. The live engine is version 3.69.0
(GET /health reports it). Items marked new in 3.69.0 arrived in this
release; items without a badge existed before. Every request needs Authorization: Bearer mk_live_…; a POST returns a
jobId to follow at GET /jobs/{jobId}.
GET /v1 (the live index, needs your key) · /health (version and what is on, no key).
Leave a choice out and Studio picks (look, music, voice, set, frame); the finished job records what it picked.1. Make a film
POST /v1/direct
{
"brief": "A 30-second trailer for 'The Salt Road', a novel about a family of salt traders. For Instagram readers. Warm, unhurried. End on the title and 'Out now'.",
"title": "The Salt Road",
"preset": "9:16",
"target": {
"seconds": 30
},
"generateVisuals": true
}POST /v1/render
{
"timeline": {
"preset": "16:9",
"theme": "lux",
"scenes": [
{
"duration": 6,
"visual": {
"type": "video",
"src": "https://your-cdn/intro.mp4"
},
"transition": "fade",
"overlays": [
{
"type": "title",
"text": "Welcome"
}
]
},
{
"duration": 5,
"visual": {
"type": "image",
"src": "https://your-cdn/slide.png",
"kenBurns": "in"
}
}
]
}
}POST /v1/assets
(raw file bytes as the body, with its Content-Type header; not JSON)POST /v1/merge
{
"template": {
"preset": "square",
"scenes": [
{
"duration": 4,
"visual": {
"type": "color"
},
"overlays": [
{
"type": "title",
"text": "Welcome, {{first}}"
}
]
}
]
},
"rows": [
{
"first": "Priya"
},
{
"first": "Kenji"
}
],
"key": "first"
}POST /v1/campaigns
{
"name": "Thank you",
"set": "office",
"cast": [
{
"id": "maya",
"preset": "maya"
}
],
"lines": [
{
"who": "maya",
"text": "Hi {first_name}, thank you from everyone at {company|our team}."
}
],
"clients": "first_name,company\nPriya,Acme",
"cta": {
"label": "Book a call",
"url": "https://example.com/book"
},
"format": "vertical"
}POST /v1/reel
{
"song": "<url, data-url or stored source>",
"visuals": [
{
"src": "https://.../photo1.jpg"
},
{
"prompt": "sunrise over a quiet harbour"
}
],
"shape": "vertical",
"mood": "dreamy",
"lyrics": "auto",
"karaoke": true,
"captionLook": "bold"
}POST /v1/render
{
"timeline": {
"preset": "16:9",
"scenes": [
{
"duration": 4,
"visual": {
"type": "image",
"src": "https://.../street.png",
"flow": "right"
}
},
{
"duration": 4,
"visual": {
"type": "image",
"src": "https://.../street2.png",
"flow": "right"
}
}
]
}
}POST /v1/render
{
"timeline": {
"preset": "9:16",
"brand": {
"color": "#5A0F14",
"accent": "#E2B04A",
"endCard": {
"text": "Follow for more"
}
},
"scenes": [
{
"duration": 5,
"visual": {
"type": "blocks",
"items": [
{
"kind": "text",
"small": "If you're looking to",
"big": "Grow your audience"
},
{
"kind": "count",
"small": "Over the last",
"to": 14,
"suffix": "years"
}
]
},
"subtitle": "If you're looking to grow your audience... over the last fourteen years..."
}
]
}
}POST /v1/render
{
"timeline": {
"preset": "16:9",
"scenes": [
{
"duration": 7,
"visual": {
"type": "image",
"src": "https://.../step-2.png",
"kenBurns": "hold"
},
"overlays": [
{
"type": "eyebrow",
"text": "Step 2"
}
],
"highlights": [
{
"x": 0.73,
"y": 0.86,
"w": 0.065,
"h": 0.056,
"start": 0.5,
"label": "Continue"
}
]
}
]
}
}POST /v1/enrich
{
"video": "<stored source>",
"source": "ai",
"count": 6
}POST /v1/storyboard
{
"text": "Our school opens a new library on Monday..."
}POST /v1/mix
{
"format": "landscape",
"blocks": [
{
"type": "clip",
"src": "<stored source>",
"stops": [
{
"at": 4,
"side": "right",
"cast": [
{
"id": "grace",
"preset": "grace"
}
],
"lines": [
{
"who": "grace",
"text": "This is the button to press.",
"mood": "happy"
}
],
"circles": [
{
"find": "the blue button",
"cue": "button"
}
]
}
]
}
]
}POST /v1/videogen
{
"parts": [
"A woman in a kitchen says: Hello, welcome."
],
"aspectRatio": "16:9"
}POST /v1/moments
{
"video": "<stored source>",
"count": 8,
"minSeconds": 20,
"maxSeconds": 60
}DELETE /jobs/{jobId}PUT /v1/rules
{
"rules": "Never show faces. No music."
}2. Captions and look
POST /v1/caption
{
"video": "<stored source or URL>",
"captionLook": "bold",
"spokenLang": "en"
}POST /v1/render
{
"timeline": {
"preset": "9:16",
"subtitleStyle": {
"look": "band",
"wordsPerBeat": "auto",
"keyWord": "auto",
"accent": "#D9A441",
"caseMode": "upper"
},
"subtitles": [
{
"start": 0,
"end": 3,
"text": "We grew 40% in one year",
"words": [
{
"word": "We",
"start": 0,
"end": 0.2
}
]
}
],
"scenes": [
{
"duration": 6,
"visual": {
"type": "video",
"src": "https://.../me.mp4"
}
}
]
}
}POST /v1/render
{
"timeline": {
"scenes": [
{
"duration": 4,
"visual": {
"type": "color"
},
"overlays": [
{
"type": "popcaption",
"text": "you can WIN this game",
"start": 0.5,
"end": 3.5
}
]
}
]
}
}POST /v1/render
{
"timeline": {
"language": "en",
"subtitles": [
{
"start": 0.3,
"end": 3.8,
"text": "We love the land we live in",
"ta": "நாங்கள் வாழும் நிலத்தை நேசிக்கிறோம்"
}
],
"scenes": [
{
"duration": 5,
"visual": {
"type": "color"
}
}
]
}
}POST /v1/direct
{
"brief": "A bright 20-second explainer on how rainbows form",
"theme": "sunlit",
"artStyle": "ink",
"preset": "9:16"
}POST /v1/render
{
"timeline": {
"scenes": [
{
"duration": 5,
"visual": {
"type": "image",
"src": "https://.../a.jpg",
"kenBurns": "drift-left"
},
"effects": [
"golden",
{
"name": "grain",
"intensity": 0.4
}
],
"atmosphere": [
{
"effect": "snow",
"density": 0.6
}
]
},
{
"duration": 4,
"visual": {
"type": "color"
},
"transition": {
"type": "whip",
"duration": 0.6
}
}
]
}
}POST /v1/render
{
"timeline": {
"scenes": [
{
"duration": 5,
"visual": {
"type": "video",
"src": "https://.../clip.mp4"
},
"heading": "The referral engine",
"overlays": [
{
"type": "lowerthird",
"text": "Jane Doe",
"secondary": "Founder, ACME",
"start": 0.5,
"end": 5
},
{
"type": "lockup",
"eyebrow": "Lesson",
"title": "Safety basics",
"kinetic": true,
"animate": "spring"
}
]
}
]
}
}POST /v1/render
{
"timeline": {
"frame": {
"balance": "auto",
"fill": [
"blockcaption",
"counter"
],
"sound": "soft"
},
"scenes": [
{
"duration": 6,
"visual": {
"type": "video",
"src": "https://.../me.mp4"
}
}
]
}
}POST /v1/render
{
"timeline": {
"frame": {
"layout": "designed"
},
"brand": {
"color": "#5A0F14",
"accent": "#E2B04A"
},
"scenes": [
{
"duration": 7,
"visual": {
"type": "video",
"src": "https://.../me.mp4"
}
},
{
"duration": 5,
"visual": {
"type": "image",
"src": "https://.../proof.png"
},
"frame": {
"focus": {
"x": 0.05,
"y": 0.3,
"w": 0.9,
"h": 0.3
}
}
}
]
}
}3. Marks and effects (hand-drawn marks, confetti, bubbles)
POST /v1/render
{
"timeline": {
"scenes": [
{
"duration": 5.5,
"visual": {
"type": "image",
"src": "https://.../amazon.png"
},
"marks": [
{
"kind": "circle",
"x": 0.08,
"y": 0.2,
"w": 0.19,
"h": 0.46,
"at": 0.6
},
{
"kind": "box",
"x": 0.33,
"y": 0.53,
"w": 0.57,
"h": 0.06,
"at": 2,
"label": "#2 BEST SELLER"
}
]
}
]
}
}POST /v1/render
{
"timeline": {
"scenes": [
{
"duration": 6,
"visual": {
"type": "video",
"src": "https://.../me.mp4"
},
"bursts": [
{
"kind": "confetti",
"at": 0.6
}
]
}
]
}
}POST /v1/render
{
"timeline": {
"scenes": [
{
"duration": 6,
"visual": {
"type": "video",
"src": "https://.../me.mp4"
},
"overlays": [
{
"type": "sticker",
"text": "WE DID IT!",
"icon": "party",
"start": 0.9,
"end": 4.6
},
{
"type": "pill",
"text": "#1 TOP NEW RELEASE",
"icon": "trophy",
"start": 2.4,
"end": 5.6
},
{
"type": "bubble",
"speaker": "Boss",
"text": "Do this.",
"side": "auto",
"start": 1,
"end": 5
},
{
"type": "quotecard",
"kicker": "MY CHAPTER",
"text": "The Boss Said. The Team Heard.",
"start": 1.2,
"end": 4.8
}
]
}
]
}
}POST /v1/render
{
"timeline": {
"director": "auto",
"tone": "warm",
"scenes": [
{
"duration": 6,
"visual": {
"type": "video",
"src": "https://.../me.mp4"
}
}
]
}
}4. Sound and music
POST /v1/direct
{
"brief": "A calm 90-second film about our garden project",
"music": {
"mood": "calm",
"shape": "bookends"
}
}POST /v1/render
{
"timeline": {
"sfx": "auto",
"scenes": [
{
"duration": 5,
"visual": {
"type": "color"
},
"overlays": [
{
"type": "popcaption",
"text": "Grow your AUDIENCE",
"start": 0.5,
"sfx": "ping"
}
],
"sfx": [
{
"name": "draw",
"at": 2
}
]
}
]
}
}POST /v1/isolate
{
"media": "<stored source or URL>"
}5. Voices and languages
POST /v1/voice
{
"text": "Welcome to the course.",
"language": "en",
"keep": true
}GET /v1/history?kind=voicePOST /v1/caption
{
"video": "<stored source>",
"captionLang": "hi",
"spokenLang": "en"
}POST /v1/cover
{
"from": "<finished film id>",
"headline": "आपकी कहानी, आपकी आवाज़"
}POST /v1/people
{
"name": "Priya",
"photo": "<stored source>",
"consent": true,
"self": true
}6. Characters, drawing and 3D
POST /v1/cast
{
"set": "library",
"format": "vertical",
"cast": [
{
"id": "grace",
"preset": "grace"
},
{
"id": "kenji",
"preset": "kenji"
}
],
"lines": [
{
"who": "kenji",
"text": "What's the book about?",
"mood": "curious",
"action": "raise"
},
{
"who": "grace",
"text": "A family of salt traders, and one long road home.",
"mood": "happy",
"action": "open"
}
]
}POST /v1/cast
{
"topic": "Preparing for a job interview",
"avatar": "av_...",
"seconds": 60
}POST /v1/cast
{
"style": "stick",
"set": "park",
"cast": [
{
"id": "ana",
"pronoun": "she",
"age": 34
},
{
"id": "ben",
"pronoun": "he",
"look": "ben-7"
}
],
"lines": [
{
"who": "ana",
"text": "A thousand people came out today.",
"mood": "excited"
}
],
"crowd": {
"count": 1000,
"seed": "plaza-a",
"doing": "clap",
"layout": "plaza"
}
}POST /v1/library
{
"request": "a tired night-shift nurse",
"kind": "character"
}POST /v1/draw/create
{
"kind": "character",
"brief": "a grumpy teapot with a bowler hat",
"rounds": 2,
"save": {
"name": "teapot"
}
}POST /v1/render
{
"timeline": {
"scenes": [
{
"duration": 5,
"visual": {
"type": "3d",
"scene": {
"background": {
"gradient": [
"0x100E08",
"0x000000"
]
},
"camera": {
"orbit": {
"radius": 5,
"height": 1.3,
"revolutions": 0.08
},
"fov": 38
},
"ground": {
"y": -1.3,
"reflectivity": 0.5,
"shadow": true
},
"objects": [
{
"mesh": "text3d",
"text": "ACME",
"extrude": 0.4,
"bevel": 0.03,
"material": {
"color": "0xE3C878",
"metallic": 0.9,
"roughness": 0.2
}
}
]
}
}
}
]
}
}7. Courses and learning systems (LMS, LTI)
POST /v1/direct-course
{
"brief": "A short course on kitchen fire safety for new cooks",
"look": "clinic",
"target": {
"seconds": 600
},
"certificate": {
"passingScore": 0.8
}
}POST /v1/interactive
{
"title": "Your first bakery shift",
"start": "intro",
"preset": "16:9",
"nodes": {
"intro": {
"timeline": {
"scenes": [
{
"duration": 6,
"visual": {
"type": "color"
},
"overlays": [
{
"type": "lockup",
"title": "Your first bakery shift"
}
]
}
]
},
"next": "q1"
},
"q1": {
"timeline": {
"scenes": [
{
"duration": 4,
"visual": {
"type": "color"
}
}
]
},
"question": {
"type": "dragdrop",
"prompt": "Drag each item to where it belongs.",
"buckets": [
"Oven",
"Fridge"
],
"items": [
{
"text": "Milk",
"bucket": "Fridge"
},
{
"text": "Dough",
"bucket": "Oven"
}
],
"pass": "done",
"fail": "intro"
}
},
"done": {
"timeline": {
"scenes": [
{
"duration": 4,
"visual": {
"type": "color"
},
"overlays": [
{
"type": "lockup",
"title": "Well done"
}
]
}
]
}
}
}
}PATCH /v1/interactive/{interactiveId}
{
"look": "book",
"brandColor": "#0E7C7B",
"celebrate": true
}POST /v1/direct-course
{
"brief": "A short course on kitchen fire safety for new cooks",
"title": "Kitchen fire safety",
"outcome": "Handle a kitchen fire safely",
"author": "Jane Doe, Nurse Educator"
}POST /v1/interactive/{interactiveId}/trailer
{
"seconds": 30
}PATCH /v1/interactive/{interactiveId}
{
"sounds": true
}GET /v1/interactive/{interactiveId}/resultsGET /v1/interactive/{interactiveId}/export/scorm2004POST /v1/lti/registration-links8. Covers and thumbnails
POST /v1/cover
{
"from": "<finished film id>",
"headline": "Number 2 on Amazon",
"accent": "in 30 days",
"byline": "Jane Doe, Author",
"badge": "New",
"size": "9:16"
}9. Social and export
POST /v1/social/schedule
{
"items": [
{
"film": {
"job": "<jobId>"
},
"platforms": [
"instagram",
"linkedin"
],
"at": "2026-12-04T09:00:00Z",
"text": "Our new film.",
"title": "New film"
}
]
}POST /v1/direct
{
"brief": "A 20-second welcome film",
"webhook": {
"url": "https://your-server.example/studio-hook"
}
}10. Account and API
GET /v1/usageGET /healthfind (needs the
picture-reading service); a real learning-system test of LTI 1.3; the licensed music pack ships empty.✦ What's new
The engine self-describes at runtime — GET /health reports the live version
and which capabilities are on. These are the notable recent additions:
GET /health reports the version. Every ready course gets a cover for the course and one per lesson (cover: false opts out; read them under covers on GET /v1/interactive/{id}). POST /v1/interactive/{id}/trailer renders a 20-40 second vertical trailer from the lessons. sounds: true adds a ping on a right answer, a tick on a wrong one and confetti on a passed lesson. A scene can carry hand-written blocks with scene.frame.phrases. Captions burned in Hindi, Marathi, Bengali and the other Indic scripts now join letters and place vowel signs correctly, and covers typeset those scripts too. director: "auto" chooses marks and effects from what is said. See What Studio can do.POST /v1/library { "request": "a tired night-shift nurse", "kind": "character" } — and it comes from the shared creative library, or is made on the spot as a small recipe (age, build, skin, hair, clothes, gender — no voice of its own) with a preview portrait. Put it in any cast as { "id": "nurse", "library": "lib_…" }; its voice defaults to a gender-matched voice from the voice library (set voice on the entry to choose another; list at GET /v1/voices); other fields on the entry change it for your film ("top": { "color": "#E53935" }). Only generic characters are kept for everyone (a nurse, a farmer, a firefighter); a real person, a brand, a film character or your customer's own is made for that film alone, as an original person, and never kept. No photo and no voice sample is involved — a real person's avatar is /v1/people, which is separate. Full details in llms-full.txt.POST /v1/direct now writes the film a music bed and mixes it under the narration, ducking on every spoken line. It is generated by the engine — there is nothing to license, nobody to attribute and no vendor that can go down. Choose one with "score": "warm" | "calm" | "bright" | "serious" | "tender", decline it with "score": false, or send your own music — yours always wins. List them at GET /v1/score; the finished job reports film.score.targetSeconds on /v1/direct was ignored, the default length took its place, and the finished film reported a target you never set. Every submit now answers with ignored: [{ field, didYouMean }] and a plain-language warning, and the same report rides the job as a field-not-understood advisory. Nothing is refused — a field we haven't heard of never breaks your request, it just stops being invisible./v1/direct takes target: { seconds }, targetSeconds, or seconds — all the same thing. A length that isn't a number is refused at the door with the field named, rather than quietly becoming 60. Note that narrated scenes run as long as their voice takes, so a target is aimed at, not guaranteed; the job says so."imageProvider": "openai" | "google" on /v1/direct and /v1/direct-course. A pinned service is the only one tried — if it refuses you're told, never handed the other one's pictures in a different house style. Worth knowing: only Imagen (google) draws to a 16:9 frame; gpt-image-1's largest landscape is 1536×1024, so a 1080p film enlarges it slightly and eases the Ken Burns move to keep that from showing."heading": "The referral engine" on any scene (or { text, position } to pin it), or send "headings": true to /v1/direct / /v1/direct-course and the Director labels each scene itself. Left to place itself, the engine measures where the picture is quiet — edge energy per zone, because a face or a subject is where the detail is — and files the label top, left, or right accordingly, never over the busy part and never in the caption band. Films that don't ask render byte-identically."previous": "<interactiveId>" on POST /v1/direct-course when producing a new version of a course you already made. Parts whose teaching the edited brief leaves untouched keep their finished films — no new pictures, no new narration, no render, nothing metered — and each kept part says so on its own timeline (part-reused). Anything the edit touches is made fresh, and when in doubt the engine rebuilds: a stale film can never wear an edited script. Reuse needs the same course-wide settings (theme, voice, size, language, length, tone, rules, providers) — change any of those and every part rebuilds, with a note saying why. Courses produced before this feature carry no reuse record; their first re-produce is full price and starts the chain.PUT /v1/rules stores your standing rules ("no music", "never show faces") server-side, per key. They are merged into every generation — reels, Director films, courses, storyboard images, redraws and re-runs — so a rule stated once can never be forgotten by a later variation. Read back with GET /v1/rules.lyricsText to POST /v1/reel or POST /v1/caption and the captions carry your exact text, aligned word-by-word to the audio's clock. Transcription only provides timings; a misheard name or a skipped line can no longer reach the film. The job notes report how much of the text anchored to the audio.invented-words-over-silence-were-dropped advisory on the job carries every such stretch with its clock (dropped: [{ start, end, text }]), so "no captions appeared" reads as "nothing was heard between 0:03 and 0:08". A recording that was room tone end to end fails with those stretches named. Applies to POST /v1/caption and POST /v1/enrich alike.POST /v1/isolate takes any audio or video (media: URL, data-URL or stored asset) and returns the voice alone — music, instruments and noise stripped. A video comes back as the same video (picture stream-copied) with only the voice on its soundtrack. Poll /jobs/{id}; the outputs land in result.vocalsUrl / result.videoUrl.POST /v1/caption, /v1/enrich, /v1/reel and /v1/isolate now accept a stored-asset reference ({"__asset": "…", "mime": "…"} from POST /v1/assets) as the video/song — so a 500MB film streams up once instead of failing the 32MB JSON cap. Transcription is fed a small mono extract, never the whole file.GET /health → "storage": "r2"), the box's disk is a CACHE, not a home: uploads, recordings, generated stills, finished films, interactive course media, certificates, learner results, templates, locked rules and the usage ledger all persist to object storage. A swept file restores transparently on next access, and a brand-new box pulls its state home from the bucket at boot.POST /v1/handoff (mint), GET /v1/handoff/{token} (poll), POST /v1/handoff/{token}/asset (public phone upload)./studio/record records the webcam up to 4K with native noise-cancellation, a WebGL chroma-key greenscreen, native background blur, and AI background blur / replacement (MediaPipe body-segmentation, vendored and served by the engine — no external request) — then auto-saves the clip as one of your sources. Reachable from the Studio's 🎥 Record button.POST /v1/assets streams a browser-recorded clip (4K, camera permitting) — or any large media — straight into the content-addressed store and hands back a {__asset} marker you can drop in any timeline, plus a Range-served preview URL. The backbone of the in-Studio camera recorder: record in the browser, and the clip becomes another of your video sources. See section 02."graded": true on an interactive and the answer key never reaches the browser — the player submits each response to POST /play/{id}/grade, the engine decides correctness, and the score is server-authoritative (a forged client score can't earn a certificate). Default courses stay client-graded for fast, offline learning checks. See section 04.dragdrop, match, ordering (arrange in order), fillblanks (cloze), markwords (tap the right words), and hotspot (click a region of an image) — alongside choice/multi/text. All work by mouse, touch, or keyboard, score automatically (server-graded when the course is graded), and report through SCORM/xAPI/cmi5. See section 04.GET /v1/jobs, /v1/batches, and /v1/usage return your own work; another product's ids, files, and spend are invisible (a request for one answers 404).breathe, veil, curtain, bloom — now render several times faster at identical quality. Use them on any scene junction.atmosphere — snow, embers, fog, light — layered over your picture. List them at GET /v1/atmosphere.GET /health → captionLangs).presenter: true with your avatar/voice ids.01 Authentication
Every call except /health and the public learner player carries your token:
Authorization: Bearer YOUR_API_KEYYour app is issued its own named key, so usage is attributed to you and can be revoked
independently — never share the master key, and never ship the key to a browser. Every job records which
key submitted it, and GET /v1/usage returns your per-key metering.
Your key is a tenant boundary: it sees, downloads, and cancels only the jobs and batches
it submitted. Another product's ids, files, and spend are invisible to you, and a request for one answers
404. (The operator's console key and admins see everything, for support.)
02 Providing content
Anywhere a visual takes a src, you may pass:
| Form | Use | Notes |
|---|---|---|
https://… | Recommended for HeyGen / Higgsfield clips & images | Streamed to disk, size-capped; host must be publicly reachable |
data:<mime>;base64,… | Small inline assets only | Never inline hundreds-of-MB video — use a URL |
Accepted visual kinds: video, image, color (a themed card).
Private, loopback, and cloud-metadata hosts are refused by the SSRF guard — public URLs are fine.
The request body itself is capped at 32 MB, the other reason to pass big media by URL.
03 Stitch content into a video
Each scene carries a duration, a visual, and optional transition,
overlays, effects, and atmosphere. Your provided clip or image is
the scene's visual.
{
"timeline": {
"preset": "16:9",
"theme": "lux",
"scenes": [
{
"duration": 6,
"visual": { "type": "video", "src": "https://your-cdn/heygen-intro.mp4" },
"transition": "fade",
"overlays": [{ "type": "title", "text": "Welcome" }]
},
{
"duration": 5,
"visual": { "type": "image", "src": "https://your-cdn/slide-1.png", "motion": "in" },
"overlays": [
{ "type": "eyebrow", "text": "MODULE 1" },
{ "type": "title", "text": "Fire safety basics" }
]
}
]
}
}| Field | Values |
|---|---|
preset | 16:9/landscape/course, 9:16/portrait/vertical, 1:1/square. Omit → 16:9. |
visual.type | video (your clip), image (still, optional Ken-Burns motion: in / out / drift-left / drift-right / punch), color |
overlays[].type | eyebrow, title, subtitle, lowerthird, keyline, caption, popcaption, lockup |
transition | fade, cut, breathe, veil, curtain, bloom, pixelize, whip … (live: GET /v1/effects) |
captions | { "subtitles": [{ "start", "end", "text" }] } for burn-in captions, or omit. Burned into the picture and shipped beside it as .srt + .vtt |
language | a BCP-47 tag (fr, pt-BR) — reaches the .vtt header and the mp4's own track tags |
bookend | the film fades up from black and out to it, and a music bed comes up rather than starting at full level. false keeps the audio ramps and drops the picture fades — for clips played back to back |
Poll the job
{ "status": "processing", "progress": "scene 3/12 built",
"phase": "building", "percent": 25, "step": { "done": 3, "total": 12 } }progress is a sentence to show a person — don’t run a regex over it. Beside it,
phase is the stable key (GET /v1 lists them in order), percent is how far
through that phase, and it is absent rather than stale when there is no honest number.
{ "status": "done", "duration": 11.0, "seconds": 11, "label": "Fire safety",
"url": "https://studio.futurizenow.co/files/{id}.mp4",
"captionsUrl": "…/files/{id}.srt", "subtitlesUrl": "…/files/{id}.vtt", "posterUrl": "…/files/{id}.jpg",
"chaptersUrl": "…/files/{id}.chapters.vtt",
"createdAtIso": "2026-08-06T17:41:58.887Z", "restartUrl": "…/jobs/{id}/restart",
"film": { "width": 1920, "height": 1080, "fps": 30, "bytes": 8431276, "scenes": 4,
"videoCodec": "h264", "audio": "stereo 48 kHz", "captionCues": 23,
"chapters": [ { "index": 1, "start": 0, "end": 3.3, "title": "Fire safety basics" } ] } }status runs queued → processing → done | failed. Every URL in every answer is
whole — nothing here needs joining to a base. The film comes back described: its size, its codecs, how
many scenes, and its own table of contents (written into the mp4 as well). Fetch the outputs at
GET /files/{id}.mp4 (Range/seek supported, plus .srt, .vtt and
.jpg); they carry an ETag, so a re-check costs a 304.
GET /jobs/{jobId}/events is an SSE
stream of named events — progress, then a final done/failed —
each frame a whole job view. Reconnect with Last-Event-ID and the numbering carries on where it
left off; you are handed the current state, never a replay of stale ones.
Or add "webhook": { "url": "https://your-app/hook" } to the POST and we call you on completion,
with the same links, whole.04 Stitch content into a course
Each node is an ordinary timeline (same schema as above) that renders to its own clip.
A node ends in a question whose choices route to other nodes, a next that
auto-advances, or nothing (the end). Loops are legal — a wrong answer can route to a remediation node
that returns to the question.
{
"title": "Fire Safety Module",
"start": "intro",
"theme": "lux",
"nodes": {
"intro": {
"timeline": { "scenes": [
{ "duration": 6, "visual": { "type": "video", "src": "https://your-cdn/heygen-lesson.mp4" },
"overlays": [{ "type": "title", "text": "Lesson 1" }] }
]},
"question": {
"prompt": "A pan catches fire. What do you do?",
"choices": [
{ "label": "Cover it with a lid", "next": "correct", "correct": true },
{ "label": "Throw water on it", "next": "recap" }
]
}
},
"recap": { "timeline": { "scenes": [ { "duration": 5, "visual": { "type": "color", "src": "#301414" }, "overlays": [ { "type": "title", "text": "Not quite" } ] } ] }, "next": "intro" },
"correct": { "timeline": { "scenes": [ { "duration": 4, "visual": { "type": "color", "src": "#12301c" }, "overlays": [ { "type": "title", "text": "Well done" } ] } ] } }
}
}Poll GET /v1/interactive/{interactiveId} until every node has rendered. The
learner-facing player is public at GET /play/{interactiveId} — the
unguessable id is the capability token; hand that URL to learners or embed it. Results and analytics
come from GET /v1/interactive/{interactiveId}/results. Optional per node: a
certificate minted on pass, a resultsWebhook, and templateName +
row to mail-merge inside a branch.
05 LMS export
06 Discovery
| Endpoint | Returns |
|---|---|
GET /health | capabilities & version (no auth) |
GET /v1/themes | visual themes |
GET /v1/presets | format presets (16:9 / 9:16 / 1:1) |
GET /v1/effects | cinematic looks & transitions |
GET /v1/atmosphere | weather / light layers |
GET /v1/score | music beds the engine writes |
GET /v1/voices | speech services & their voices |
GET /v1/usage | your per-key metering |
GET /v1/library | the shared creative library: backgrounds, pictures, sets, props & characters |
07 Notes & limits
- Async by design. Renders take seconds to minutes — never block on the POST. Poll
/jobs/{id}, subscribe to/jobs/{id}/events, or use a webhook. - Caps. A single render takes up to 500 scenes; an interactive graph up to 40 nodes. Ask if you need these raised.
- Cancellation.
DELETE /jobs/{id}cancels a job (and stops any in-flight spend);DELETE /v1/interactive/{id}cancels a course. - Provide, don't generate. When you supply the assets, no provider keys are involved. The engine can also generate — AI Director, stills, narration, HeyGen presenter — but that's a separate, key-gated path.
08 Quickstart
# submit
JOB=$(curl -s -X POST https://studio.futurizenow.co/v1/render \
-H "Authorization: Bearer $KEY" -H "content-type: application/json" \
-d '{"timeline":{"preset":"16:9","scenes":[
{"duration":6,"visual":{"type":"video","src":"https://your-cdn/clip.mp4"},"overlays":[{"type":"title","text":"Welcome"}]},
{"duration":5,"visual":{"type":"image","src":"https://your-cdn/slide.png","motion":"in"}}
]}}' | jq -r .jobId)
# poll
curl -s https://studio.futurizenow.co/jobs/$JOB -H "Authorization: Bearer $KEY" | jq .status
# fetch when done
curl -s https://studio.futurizenow.co/files/$JOB.mp4 -H "Authorization: Bearer $KEY" -o film.mp4