AI footage
Generate B-roll that shows what your narration says: a technician tightening a bolt, a nurse washing her hands, a forklift backing into a bay. It is the same pipeline as the AI tab in Studio.
It works in three steps, cheapest first:
- Plan the shot (free). A description becomes short, editable fields, plus a warning when AI video is the wrong tool for it.
- Generate stills. Settle the look on a still frame, which is fast and cheap.
- Animate one still into a 4, 6 or 8 second clip.
Stills and clips cost credits, charged only when they succeed. A still the model refuses, or a
clip that fails, costs nothing. Current prices are in Credit costs
(ai_footage_still, ai_footage_clip).
Generating needs a paid plan and a role that can create. Free plans and trials get 402. The workspace owner can turn AI footage
off in Settings, and requests then fail with 403. The endpoints use the Studio scopes:
studio:read to list and fetch, and studio:write to generate.
Plan a shot
POST /v1/ai-media/shot
curl -X POST https://api.vidocu.ai/v1/ai-media/shot \
-H "Authorization: Bearer vdo_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"description": "a nurse washing her hands before seeing a patient", "preset": "documentary"}'
{
"shot": {
"subject": "a nurse in blue scrubs",
"action": "washes her hands thoroughly with soap",
"setting": "at a hospital handwashing station",
"framing": "close-up of hands",
"camera": "slow push-in",
"lighting": "bright, clean daylight"
},
"risks": [
{ "kind": "exactSteps", "note": "AI video may not show each handwashing step correctly." }
],
"suggestion": "For the exact steps, use an animated slide or a real demonstration."
}
Send description, narration (the line the shot plays under), or both, plus preset and styleNote if you use them. risks lists what AI
video does badly, so you can stop before spending credits:
kind | When |
|---|---|
text | The shot only works if words, numbers or labels are readable |
logo | It needs a specific brand or product |
softwareUi | It is about a specific app or website screen |
realPerson | It needs a specific real person |
exactSteps | It needs an exact count or sequence to be correct |
Refine a shot
Send the shot you have as current and a short change ("darker", "closer", "a woman instead"),
and the planner returns the same shot with only that changed. Then generate new stills, passing the
still you liked as referenceUrl so the people and setting stay the same.
{ "current": { "subject": "a nurse in blue scrubs", "action": "washes her hands", "setting": "at a hospital sink" }, "change": "closer, warmer light" }
Styles
preset sets the look, and keeping one preset per course keeps clips consistent:
preset | Look |
|---|---|
documentary | Real people at work, natural light, calm handheld camera (default) |
studio | Objects and hands on a seamless background |
onSite | Workshops, plants and field work, with safety gear |
cinematic | Dramatic light and wide framing |
isometric3d | Clean 3D scenes for processes and systems |
flat2d | Flat 2D illustration |
cartoon3d | Friendly animated-film characters. Good for kids and teens |
storybook | Warm hand-drawn picture-book art |
claymation | Handmade stop-motion clay figures |
whiteboard | Black-marker drawings on white, explainer style |
classroom | Real schools, lecture halls and libraries, with teachers and adult students |
brand | Documentary look in your Brand Kit colors |
styleNote adds your own style words on top of any preset, up to 400 characters: "navy
coveralls with orange trim, bright modern plant". Send the same note with every shot and still in
a course. It never overrides the rule that shots contain no text or logos.
For courses aimed at kids and teens, the illustrated presets (cartoon3d, storybook,
claymation, flat2d) usually suit the audience best.
Generate stills
POST /v1/ai-media/stills
curl -X POST https://api.vidocu.ai/v1/ai-media/stills \
-H "Authorization: Bearer vdo_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"shot": {"subject": "a nurse in blue scrubs", "action": "washes her hands", "setting": "at a hospital sink"}, "count": 2}'
| Field | |
|---|---|
shot | Required. Needs at least a subject, action or setting |
preset | Default documentary |
styleNote | Your own style words on top of the preset |
aspectRatio | 16:9 (default) or 9:16 |
count | 1-4, default 1. Each still is charged |
referenceUrl | An image in this workspace whose people and setting the stills should keep |
studioProjectId | The Studio project this is for. It appears in that project's AI tab |
The response is 201 with media: one item per still. Check each item's status. One still can
be refused while the others succeed.
Animate a still
POST /v1/ai-media/clips
curl -X POST https://api.vidocu.ai/v1/ai-media/clips \
-H "Authorization: Bearer vdo_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"stillId": "3f1c...", "durationSec": 6, "resolution": "720p"}'
Pass stillId (a completed still), or imageUrl for any image file in this workspace. The clip is
4, 6 (default) or 8 seconds, at 720p (default) or 1080p. shot overrides the still's own
shot field by field.
The file carries generated ambient sound (no music or speech) and can run slightly past
durationSec. Studio places AI clips muted and cut to durationSec; do the same when you place
one with the timeline API (volume: 0, sourceEndTime = durationSec). At 720p the frame
follows the still, for example 1344×768 for a 16:9 still.
The response is 202 with status: "generating". A clip usually takes under a minute, at most a
few. Poll
GET /v1/ai-media/:id until status is completed (its url is then set) or failed (error
says why). A clip that does not finish within 20 minutes is failed and not charged.
Animated scenes
POST /v1/ai-media/scenes
Not everything is clearer filmed. Steps, a key number, a checklist or a do/don't comparison read better drawn, with exact text. An animated scene is a short motion-graphics clip in your Brand Kit colors and font, written from a description or the narration it plays under.
curl -X POST https://api.vidocu.ai/v1/ai-media/scenes \
-H "Authorization: Bearer vdo_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"description": "The 4 steps to lock out a machine: switch off, isolate the energy source, attach your lock and tag, test that it will not start."}'
The response is 201 with kind: "scene" and a scene document:
{
"layout": "processFlow",
"title": "Lock out a machine before maintenance",
"items": [
{ "label": "Switch off" },
{ "label": "Isolate the energy source" },
{ "label": "Attach your lock and tag", "detail": "Use your personal lock" },
{ "label": "Test it won't start" }
],
"theme": { "background": "#F7F2EC", "text": "#1F2A2E", "accent": "#007A7A", "muted": "#7A8589", "fontFamily": "Satoshi, sans-serif" }
}
layout | Shows |
|---|---|
processFlow | 2-6 ordered steps |
checklist | 2-6 items to confirm |
stat | One key number (stat.value, prefix, suffix, label) |
comparison | Two columns (comparison.left, .right); tone is doDont, beforeAfter or neutral |
keyPoints | 1-4 phrases that build to a takeaway |
timeline | 2-6 events with a when |
The scene only uses facts in your description or narration; it does not invent numbers, names or
steps. durationSec is how long it should stay on screen to be read (4-15 seconds).
Timing to the voiceover. When you send narration, each item gets an anchor: the first words
of the narration where that item is spoken. In Studio, a scene placed over a voiceover then reveals
each step as it is said (revealAt, seconds from the scene start). Without word timings it reveals
at an even pace. anchor and revealAt are never shown.
Logo. theme.logoUrl is your Brand Kit logo (the article logo, else the watermark image). It
shows in a corner unless the scene has showLogo: false.
Translate a scene
POST /v1/ai-media/scenes/translate with {"scene": {...}, "language": "es"} returns the scene
with its on-screen text in that language. Layout, numbers, colors and timing are kept. Charged on
success (ai_scene_translate).
To use it, add a clip of type: "scene" with the document in its scene field to a Studio
timeline (PUT /v1/studio/projects/:id/timeline). Every word, color and the
font stay editable in Studio. Scenes are charged on success; see
Credit costs (ai_animated_scene).
Which to use
POST /v1/ai-media/shot returns route along with the shot:
route | Means | Use |
|---|---|---|
footage | Real-world people, places, equipment | Stills, then a clip |
animation | Steps, numbers, lists, comparisons, concepts | An animated scene |
screen | A specific software screen | A screen recording or screenshot |
List and fetch
GET /v1/ai-media · GET /v1/ai-media/:id
The list is newest first, up to limit (default 60, max 200), optionally only one
studioProjectId's. Every item:
{
"id": "9b2e...",
"kind": "video",
"status": "completed",
"studioProjectId": null,
"shot": { "subject": "a nurse in blue scrubs", "action": "washes her hands" },
"preset": "documentary",
"prompt": "...",
"aspectRatio": "16:9",
"durationSec": 6,
"resolution": "720p",
"sourceStillId": "3f1c...",
"model": "heygen-video-1",
"url": "https://storage.vidocu.ai/workspaces/.../clip.mp4",
"aiGenerated": true,
"digitalSourceType": "http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia",
"createdAt": "2026-10-08T09:21:40.000Z",
"completedAt": "2026-10-08T09:22:31.000Z"
}
To put a clip in a video, add its url to a Studio project's media and place it with
PUT /v1/studio/projects/:id/timeline.
AI marking
Every item carries aiGenerated: true and the IPTC digitalSourceType. A Studio export that uses
AI footage says so in the MP4's metadata (comment and description, with the IPTC term for
media that mixes AI-generated elements into an edit). See Governance.
MCP
plan_ai_shot, generate_ai_stills, animate_ai_still, create_ai_scene, translate_ai_scene,
list_ai_media, get_ai_media.