AI Storyboard & Scene Image Generator

Turn a story or script into a run of AI scene images, one per scene, that share a consistent art style and character look. Hand it a block of text and it works out the scenes for you, or pass your own scene list if you would rather control the breakdown. Built for faceless videos, comics, ad concepts and pitch decks, where you need a sequence of related shots instead of one picture.

Bring your own API key. The renders are billed to your provider account; Apify bills you per image this Actor hands back.

How it works

Give it a story and a chat model splits it into N short visual scene descriptions, holding the same characters and setting across them. Each scene is then rendered with an image model, with your style and characters notes prepended to every prompt so the look stays consistent shot to shot. Pass scenes yourself and the splitting step is skipped entirely — no chat model needed.

Input

Field	Required	Notes
story	no	A story or script. Gets split into scenes automatically. Leave empty if you supply scenes.
scenes	no	Your own array of scene descriptions, one image each. Overrides automatic splitting.
numScenes	no	How many scenes to split a story into. Default 6, capped at 20. Ignored when you pass scenes.
style	no	Shared art style applied to every image. Defaults to a cinematic look.
characters	no	Recurring character notes for continuity, e.g. "an old bearded keeper in a yellow raincoat".
aspectRatio	no	9:16 (1024x1536), 16:9 (1536x1024) or 1:1 (1024x1024). Default 9:16.
quality	no	low, medium or high. Default high. Affects your provider bill, not the Apify charge.
openaiApiKey	yes	Your API key, used for both splitting and rendering. Can also come from the OPENAI_API_KEY environment variable.
baseUrl	no	Any OpenAI-compatible base URL. Defaults to https://api.openai.com/v1.
sceneModel	no	Chat model for splitting. Default gpt-4o-mini.
imageModel	no	Image model for the renders. Default gpt-image-1.

Only give openaiApiKey a key that works at the baseUrl you set — they are used together.

Output

The dataset gets one record per image that was actually generated and stored:

Field	Example
index	1
scene	"A weathered lighthouse keeper crouches on a rocky shore at dawn, lifting a softly glowing bottle from the surf."
prompt	the full prompt that was sent, including your style and character notes
imageKey	scene-01-1786411663909.png
imageUrl	direct link to the PNG in the run's key-value store
aspectRatio / size	9:16 / 1024x1536
contentType / bytes	image/png / 2135564

A real two-scene run at 9:16, low quality, through an OpenAI-compatible proxy took about 27 seconds per render and produced two PNGs of 2.1 MB and 2.0 MB.

Scenes that fail do not appear in the dataset. They are written to the run's key-value store under DIAGNOSTICS, along with a storyboard-diagnostics dataset, with the exact error and a suggested fix. That is deliberate: the dataset is the meter, so a scene that produced no picture must not appear in it.

Pricing

$0.05 per image, plus $0.00005 each time a run starts. Flat rate — no volume tiers, no plan gates — and you are charged only for images actually produced. A six-scene storyboard that renders all six costs $0.30 plus the start fee.

You bring your own key, so the splitting call and the renders are billed to your provider account on top of that. Higher quality raises your provider bill, not the Apify charge.

What this does not do

• It does not lock a character with a reference image. Continuity is prompt-based, so characters stay close but are not pixel-identical across every shot. Tighter characters notes and a specific style help a lot.
• It does not assemble a video. Use a video generator downstream if you need motion.
• It does not supply an API key. This is a bring-your-own-key Actor.
• It caps a run at 20 images, so a feature-length script needs several runs.
• It does not edit or upscale existing images.

FAQ

Do I need an OpenAI account? You need a key for an OpenAI-compatible image API. OpenAI itself works, and so does any proxy that speaks the same /v1/chat/completions and /v1/images/generations routes — set baseUrl and, if the provider names its models differently, sceneModel and imageModel.

What happens if I run it with no key, or forget to type a story? The run finishes successfully, generates nothing, and charges you nothing beyond the run-start fee. It writes one labelled sample row explaining exactly what was missing. It does not crash.

Am I charged when an image fails to render? No. Only an image that was generated and stored becomes a dataset row, and only dataset rows are billed. If every scene fails you pay the run-start fee and nothing else.

Why did my run return fewer images than scenes? Some scenes fail on the provider side — rate limits, quota, or a content-policy refusal on that particular prompt. Check the DIAGNOSTICS record in the run's key-value store; each failed scene is listed with its error.

My key works for chat but every image fails. Why? gpt-image-1 sits behind organisation verification on OpenAI. A key that can call gpt-4o-mini may still be refused for image generation until the organisation is verified. The error text in DIAGNOSTICS will say so.

Can I skip the automatic scene splitting? Yes. Pass scenes as an array and no chat model is called at all — useful if you already have a shot list, or if your provider only carries image models.

How long does a run take? Renders are sequential, roughly 15 to 60 seconds each depending on model and quality, so a six-scene storyboard is usually a couple of minutes. The run timeout is one hour.