Storyboard Video Generator (Ken Burns)

Turns a set of images, or a written story, into an MP4 with slow ken-burns zoom and pan on each frame, plus optional background audio. Built for faceless videos, slideshows, reels, and rough animatics where you want motion without editing each clip by hand. If you already have artwork, give it the URLs. If you only have a story, it writes the scenes and generates the images first.

How it works

Each image gets a per-clip ffmpeg pass that zooms and pans it over secondsPerImage, the clips are concatenated in order, and the audio track (if any) is mixed in. In story mode the text is split into scenes with an OpenAI model, then each scene is rendered to an image before animation.

Input

Nothing is strictly required, but you need to supply either imageUrls or story. If both are empty the run finishes with one labelled sample row and charges nothing for video seconds.

Field	Required	Notes
imageUrls	one of these	Public image URLs to animate, in order. Skips generation entirely.
story	one of these	Prose to split into scenes and generate images from. Needs openaiApiKey.
numScenes	no	Images to generate in story mode. Default 5, max 15.
style	no	Shared visual style for generated images. Story mode only.
characters	no	Recurring-character description so generated scenes stay consistent.
imageQuality	no	gpt-image-1 quality for generated scenes: low, medium (default), or high. Trades cost for sharpness — see Pricing. Story mode only.
secondsPerImage	no	How long each image is held, with motion. Default 4.
fps	no	Output frame rate. Default 30.
aspectRatio	no	9:16 (default), 16:9, or 1:1.
audioUrl	no	Public URL to a voiceover or music track laid over the whole video.
openaiApiKey	story mode	Your OpenAI key. Only used to write scenes and generate images.

Output

The MP4 is saved to the run's key-value store and a single record is pushed to the dataset describing it. Key fields: videoUrl and videoKey (where to fetch the file), durationSeconds, images (count animated), aspectRatio, fps, hasAudio, and videoBytes.

When something is wrong with the input

The run does not crash. It writes one row with ok: false, an errorCode and a details list saying exactly what was rejected, then exits successfully — so you can read the reason in the dataset instead of digging through a failed run's log. No video second is charged on those rows.

errorCode	What happened
NO_USABLE_IMAGES	Every URL in imageUrls 404'd, timed out, or returned an HTML page instead of image bytes.
UPSTREAM_AUTH	OpenAI rejected the key (401/403).
UPSTREAM_RATE_LIMITED	OpenAI rate- or quota-limited the key (429).
UPSTREAM_ERROR	The OpenAI-compatible endpoint failed some other way.
RENDER_FAILED	ffmpeg could not turn these files into a video.
NO_TIME_LEFT	The run's timeout arrived first. Lower numScenes or secondsPerImage, or raise the timeout.

Partial problems do not stop the run: a single dead URL or a single scene that fails to generate is skipped, listed under skipped, and the rest still render. A bad audioUrl keeps the silent video rather than throwing it away.

Example

{
  "story": "A lighthouse keeper finds a message in a bottle and rows out to sea to follow it.",
  "numScenes": 6,
  "style": "moody watercolor, muted palette",
  "secondsPerImage": 4,
  "aspectRatio": "9:16",
  "audioUrl": "https://example.com/ambient.mp3",
  "openaiApiKey": "sk-..."
}

Pricing

$0.015 per output second, plus $0.00005 each time a run starts. Flat rate; you are charged only for seconds actually rendered, with no volume tiers, no plan gates and no subscription. A 5-scene, 4-seconds-per-scene run is 20 seconds of video — $0.30 plus the start fee.

Story mode uses your own OpenAI key, so image generation is billed by OpenAI separately.

The OpenAI image cost depends on imageQuality (gpt-image-1, per image): low ≈ $0.011, medium ≈ $0.04, high ≈ $0.167. So the default 5-scene story run costs roughly $0.06 on low, $0.20 on medium, or $0.84 on high in OpenAI charges. Pick low for drafts and high only when you need the sharpest frames.

Notes

The duration you pay for is the final video length, so secondsPerImage times the number of images (audio does not extend it). Image URLs must be publicly reachable, since the actor downloads them directly; a residential or datacenter proxy on the URLs won't help if the host blocks the request.

The "Video second" event is charged in one place in the code, after the MP4 has been written to the key-value store and its row is already in the dataset. A run that produces no file charges no seconds.

FAQ

Do I need an OpenAI key? Only for story mode. If you pass imageUrls, no key is used and no OpenAI call is made.

What happens if I run it with no input at all? You get one row marked _sample: true explaining what to fill in. No video seconds are charged.

What if one of my image URLs is dead? That image is skipped and listed in the skipped field of the result row. The remaining images still render. If every URL is dead you get a NO_USABLE_IMAGES row and pay nothing for video seconds.

Can I use my own scene images instead of generated ones? Yes — that is what imageUrls is for. Order matters; the video follows the array order.

What sizes does it output? 1080x1920 for 9:16, 1920x1080 for 16:9, 1080x1080 for 1:1, H.264 MP4.

How long can the video be? Hard caps are 60 images and 900 seconds of output per run; past that, secondsPerImage is trimmed to fit and the run says so in the log. In practice the run timeout binds first — ken-burns motion is rendered frame by frame, so the default 1-hour timeout fits several minutes of 30 fps video rather than the full 900 seconds. When the clock runs out the run does not time out: it stops rendering, joins the clips it finished, lists the rest under skipped, and charges only for the seconds in the file you actually get.

What this does not do

No transitions beyond hard cuts between clips, no text or captions burned in, no per-scene motion control (the zoom direction alternates automatically), and no voice generation — bring your own audio track via audioUrl.