# Storyboard Video Generator — Ken Burns Slideshow (`dami_studio/storyboard-video-generator`) Actor

Turn a set of images (or a story) into a polished video with smooth ken-burns zoom/pan motion and optional audio. Give image URLs or a story to auto-generate scenes. For faceless videos, slideshows, reels, ads, and animatics.

- **URL**: https://apify.com/dami\_studio/storyboard-video-generator.md
- **Developed by:** [Dami's Studio](https://apify.com/dami_studio) (community)
- **Categories:** Videos, For creators, AI
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## 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 fails.

| 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`, and `hasAudio`.

### Example

```json
{
  "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, pay per result, no subscription. 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.

# Actor input Schema

## `imageUrls` (type: `array`):

Public image URLs to animate, in order. (Leave empty to auto-generate from a story.)

## `story` (type: `string`):

If no image URLs are given, this story is split into scenes and images are generated (needs OpenAI key).

## `numScenes` (type: `integer`):

How many images to generate when using a story.

## `style` (type: `string`):

Shared visual style for generated images.

## `characters` (type: `string`):

Recurring-character description for consistency.

## `imageQuality` (type: `string`):

gpt-image-1 rendering quality for generated scenes. Higher = sharper but pricier on the OpenAI key: low ≈ $0.011/image, medium ≈ $0.04/image, high ≈ $0.167/image. Default 'medium' (≈ $0.20 for 5 scenes vs ≈ $0.84 on high).

## `secondsPerImage` (type: `integer`):

How long each image is shown (with motion).

## `fps` (type: `integer`):

Output frames per second.

## `aspectRatio` (type: `string`):

9:16 vertical, 16:9 wide, or 1:1 square.

## `audioUrl` (type: `string`):

Public URL to a voiceover or music track to lay over the video.

## `openaiApiKey` (type: `string`):

Your OpenAI key — only needed to auto-generate images from a story. Kept private.

## `baseUrl` (type: `string`):

OpenAI-compatible base URL. Default https://api.openai.com/v1.

## Actor input object example

```json
{
  "numScenes": 5,
  "style": "cinematic, highly detailed, dramatic lighting",
  "imageQuality": "medium",
  "secondsPerImage": 4,
  "fps": 30,
  "aspectRatio": "9:16"
}
```

# Actor output Schema

## `results` (type: `string`):

Result rows / metadata are stored in the default dataset (one row per item).

## `files` (type: `string`):

Generated media/files (video, audio, images, captions) are stored in the default key-value store.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("dami_studio/storyboard-video-generator").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("dami_studio/storyboard-video-generator").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call dami_studio/storyboard-video-generator --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=dami_studio/storyboard-video-generator",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Storyboard Video Generator — Ken Burns Slideshow",
        "description": "Turn a set of images (or a story) into a polished video with smooth ken-burns zoom/pan motion and optional audio. Give image URLs or a story to auto-generate scenes. For faceless videos, slideshows, reels, ads, and animatics.",
        "version": "0.1",
        "x-build-id": "LQTo0GqATu5Nb7x5Y"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/dami_studio~storyboard-video-generator/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-dami_studio-storyboard-video-generator",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/dami_studio~storyboard-video-generator/runs": {
            "post": {
                "operationId": "runs-sync-dami_studio-storyboard-video-generator",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/dami_studio~storyboard-video-generator/run-sync": {
            "post": {
                "operationId": "run-sync-dami_studio-storyboard-video-generator",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "imageUrls": {
                        "title": "Image URLs",
                        "type": "array",
                        "description": "Public image URLs to animate, in order. (Leave empty to auto-generate from a story.)",
                        "items": {
                            "type": "string"
                        }
                    },
                    "story": {
                        "title": "Story (auto-generate images)",
                        "type": "string",
                        "description": "If no image URLs are given, this story is split into scenes and images are generated (needs OpenAI key)."
                    },
                    "numScenes": {
                        "title": "Number of scenes",
                        "minimum": 1,
                        "maximum": 15,
                        "type": "integer",
                        "description": "How many images to generate when using a story.",
                        "default": 5
                    },
                    "style": {
                        "title": "Art style (story mode)",
                        "type": "string",
                        "description": "Shared visual style for generated images.",
                        "default": "cinematic, highly detailed, dramatic lighting"
                    },
                    "characters": {
                        "title": "Character notes (story mode)",
                        "type": "string",
                        "description": "Recurring-character description for consistency."
                    },
                    "imageQuality": {
                        "title": "Image quality (story mode)",
                        "enum": [
                            "low",
                            "medium",
                            "high"
                        ],
                        "type": "string",
                        "description": "gpt-image-1 rendering quality for generated scenes. Higher = sharper but pricier on the OpenAI key: low ≈ $0.011/image, medium ≈ $0.04/image, high ≈ $0.167/image. Default 'medium' (≈ $0.20 for 5 scenes vs ≈ $0.84 on high).",
                        "default": "medium"
                    },
                    "secondsPerImage": {
                        "title": "Seconds per image",
                        "minimum": 1,
                        "maximum": 15,
                        "type": "integer",
                        "description": "How long each image is shown (with motion).",
                        "default": 4
                    },
                    "fps": {
                        "title": "Frame rate",
                        "type": "integer",
                        "description": "Output frames per second.",
                        "default": 30
                    },
                    "aspectRatio": {
                        "title": "Aspect ratio",
                        "enum": [
                            "9:16",
                            "16:9",
                            "1:1"
                        ],
                        "type": "string",
                        "description": "9:16 vertical, 16:9 wide, or 1:1 square.",
                        "default": "9:16"
                    },
                    "audioUrl": {
                        "title": "Audio URL (optional)",
                        "type": "string",
                        "description": "Public URL to a voiceover or music track to lay over the video."
                    },
                    "openaiApiKey": {
                        "title": "OpenAI API key (story mode)",
                        "type": "string",
                        "description": "Your OpenAI key — only needed to auto-generate images from a story. Kept private."
                    },
                    "baseUrl": {
                        "title": "API base URL (advanced)",
                        "type": "string",
                        "description": "OpenAI-compatible base URL. Default https://api.openai.com/v1."
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```