# Cinematic Shot Breakdown: Cuts, Camera & AI Video Prompts (`ferrolark/cinematic-shot-breakdown`) Actor

Cinematic shot breakdown for a clip up to 120 s: every cut, shot timing, estimated camera movement, lighting, palette and rhythm, plus Sora, Veo, Kling and Runway prompts per shot. Optional BYOK vision. $0.01 per 10 seconds of video.

- **URL**: https://apify.com/ferrolark/cinematic-shot-breakdown.md
- **Developed by:** [Ferrolark](https://apify.com/ferrolark) (community)
- **Categories:** AI, Videos, Developer tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 77.8% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$10.00 / 1,000 10 seconds of video analyseds

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Cinematic Shot Breakdown: Cut Detection, Camera Moves & AI Video Prompts

Upload a clip of up to 2 minutes and get a shot-by-shot breakdown: every cut with timecodes, shot length and rhythm, estimated camera movement, lighting, colour palette and shot size, plus ready-to-edit prompts for **Sora, Veo, Kling and Runway** for each shot.

- **Cuts:** PySceneDetect (adaptive + content detectors combined) on a letterbox-cropped proxy, with flash-frame merging.
- **Edit rhythm:** average and median shot length (ASL), cuts per minute, pace label, and "held shot / flash cut" per shot.
- **Camera movement:** optical flow estimates pan, tilt, push in / pull out, handheld shake and speed, with a confidence value.
- **Look:** palette with colour names and shares, key (high/low/mid), contrast, colour temperature, saturation, vignetting.
- **Shot size:** close-up / medium / wide from detected faces (heuristic).
- **Prompts:** four model-specific prompts per shot. Without a vision model the subject and setting stay as `[subject]` / `[setting]` placeholders for you to fill.
- **Optional BYOK vision:** add your own OpenAI, Gemini, OpenRouter or Anthropic key and a vision model describes subject, setting, angle, lens and mood, which fill the prompts.

Typical uses: studying the edit of an ad or trailer you are allowed to analyse, briefing a re-shoot, building a shot list for AI video generation, and comparing pacing between your own cuts.

### Real example

The Sintel trailer (Blender Foundation, CC-BY 3.0), 52 s at 854×480:

```json
{
  "videoUrl": "https://example.com/your-own-clip.mp4",
  "rightsConfirmed": true
}
```

- Run time: 14 s on Apify at 2,048 MB. Platform usage: $0.0022.
- Your cost: 6 started 10-second blocks × $0.01 = **$0.06**.
- Result: 18 shots, ASL 2.9 s, median 1.27 s, 19.5 cuts per minute ("brisk"), palette dominated by black, dark brown and tan.

| Shot | Start | Seconds | Camera | Lighting |
|---|---|---|---|---|
| 1 | 00:00.000 | 13.5 | slow push in / zoom in | mid-key, medium contrast, desaturated, vignetted |
| 2 | 00:13.500 | 0.4 | static / locked off | flat, low contrast, deep shadows (flash cut) |

Shot 1's Veo prompt: *"A cinematic medium close-up of \[subject] \[action] in \[setting]. The camera uses a slow push in / zoom in. Balanced / mid-key, medium contrast, neutral colour temperature, desaturated, vignetted, light pooled on the centre. Colour grade built on black, charcoal, dark brown, grey. Duration about 14 seconds. No on-screen text."*

### Price and limits

- **$0.01 per started 10 seconds of analysed video ($0.06 per minute).** A 30 s ad costs $0.03, a 2-minute trailer $0.12.
- Charged only after a successful analysis. Clips that cannot be downloaded or decoded, are too long, or come from a refused source are not charged.
- Limits: 120 s per clip (or turn on `trimToLimit` to analyse the first 120 s), 250 MB per file.
- Vision-model costs (BYOK) go to your own provider account. With small models (for example gpt-5-nano or gemini-2.5-flash-lite) and 2 frames per shot this is typically well under a cent per clip.

### Your rights and what we refuse

You must own the clip or be allowed to analyse it (`rightsConfirmed: true`). The Actor **does not download from platforms whose terms forbid it**: links to YouTube, TikTok, Instagram, Facebook, X, Vimeo, Twitch, Netflix, Prime Video and similar sites are refused. Use a direct file link (your storage, S3, Drive direct link) or base64.

Nothing from the clip is redistributed: keyframes are analysed in memory; `saveKeyframes` keeps them only in your private run storage.

### Input

| Field | Default | What it does |
|---|---|---|
| `videoUrl` / `videoBase64` | none | A direct link to an MP4/MOV/WebM/MKV file, or base64 for n8n and Make binaries. |
| `rightsConfirmed` | `false` | Required for your own clips (not for the public Sintel sample). |
| `maxSeconds` / `trimToLimit` | 120 / `false` | Longer clips fail (not charged) unless trimming is on. |
| `cutSensitivity` | 3.0 | Lower finds more cuts, higher fewer. |
| `minShotSeconds` | 0.4 | Merges cuts closer than this. |
| `visionProvider` | `none` | `openai`, `gemini`, `openrouter` or `anthropic` (BYOK). |
| `visionApiKey` / `visionModel` | none | Your key (secret, never logged) and an optional model id. |
| `maxShotsForVision` | 60 | Caps your provider cost on very fast edits. |
| `saveKeyframes` | `false` | Keep analysed frames in your private run storage. |

### Call it from code or an AI agent

```bash
curl -X POST "https://api.apify.com/v2/acts/ferrolark~cinematic-shot-breakdown/run-sync-get-dataset-items?maxTotalChargeUsd=0.2" \
  -H "Authorization: Bearer $APIFY_TOKEN" -H "Content-Type: application/json" \
  -d '{"videoUrl": "https://example.com/your-own-clip.mp4", "rightsConfirmed": true}'
```

The run summary (ASL, cuts per minute, palette, shot types) is in the `OUTPUT` record of the run's key-value store.

**AI agents (MCP):** add the Apify MCP server (`https://mcp.apify.com`) and allow `ferrolark/cinematic-shot-breakdown`.

### FAQ

**How accurate is the camera movement?**

It is an optical-flow estimate on a small proxy. Pans, tilts and push-ins are usually right; complex moves (orbit, crane plus pan) come out as the dominant component. Each shot has a confidence value.

**Why are subject and setting placeholders?**

Without a vision model the Actor only measures what it can compute. Add your own vision key to fill them in, or edit the prompts yourself.

**Can I analyse a YouTube video?**

No. Download platforms' terms forbid it, so those links are refused. Use a file you own.

### More Ferrolark tools

- [Brand Name Availability Checker](https://apify.com/ferrolark/brand-name-checker): domains, GitHub, npm, PyPI and more in one report.
- [Domain Intelligence Report](https://apify.com/ferrolark/domain-intelligence-report): WHOIS, DNS, email security, SSL and hosting for any domain.
- [Launch Asset Pack](https://apify.com/ferrolark/launch-asset-pack): favicons, PWA icons, OG image and head tags from one logo.
- [Live Deploy QA](https://apify.com/ferrolark/live-deploy-qa): meta tags, canonical, robots, OG image and favicon of your deployed routes, with diffs between deploys.
- [Sitemap Delta](https://apify.com/ferrolark/sitemap-delta): new, removed and broken URLs in any sitemap since the last run.
- [RSS Delta](https://apify.com/ferrolark/rss-delta): only new RSS, Atom and JSON Feed items, de-duplicated.
- [PDF Merge API](https://apify.com/ferrolark/pdf-merge-api): merge PDFs from URLs or base64 with page ranges and a SHA-256 manifest.
- [PDF Split API](https://apify.com/ferrolark/pdf-split-api): split a PDF by page ranges or every N pages, or extract pages, with a ZIP and manifest.
- [Image Convert](https://apify.com/ferrolark/image-convert): PNG, JPG, WebP, AVIF and HEIC conversion (SVG input too) from URLs or base64.
- [Image Compress & Resize](https://apify.com/ferrolark/image-compress-resize): resize images and compress them to a target size in KB, WebP or AVIF.
- [PDF to Image](https://apify.com/ferrolark/pdf-to-image): PDF pages to PNG, JPG or WebP at the DPI you choose.
- [Image to PDF](https://apify.com/ferrolark/image-to-pdf): JPG, PNG, HEIC and WebP images to one PDF, JPEGs embedded without recompression.
- [PDF Compress](https://apify.com/ferrolark/pdf-compress): smaller PDFs, lossless or with image downsampling; charged only when smaller.
- [HTML to PDF & URL to PDF](https://apify.com/ferrolark/html-to-pdf): web pages or raw HTML to PDF with headless Chrome.
- [Markdown to PDF](https://apify.com/ferrolark/markdown-to-pdf): Markdown with tables, code and footnotes to a clean PDF.
- [DOCX to PDF](https://apify.com/ferrolark/docx-to-pdf): Word, Excel, PowerPoint and ODT to PDF with LibreOffice.
- [Data Convert](https://apify.com/ferrolark/data-convert): CSV, JSON, NDJSON and Excel XLSX in any direction.
- [Criteria Checker](https://apify.com/ferrolark/criteria-checker): pass/review/fail QA gate for AI output, emails and posts (BYOK TypeSafe).
- [Support Ticket Triage](https://apify.com/ferrolark/ticket-triage): route tickets to teams with P1-P4 priority and escalation flags (BYOK TypeSafe).
- [Amazon Listing Checker](https://apify.com/ferrolark/amazon-listing-rules): title rules, restricted claims and search-term audit before upload.

***

*Built by Ferrolark.*

# Actor input Schema

## `videoUrl` (type: `string`):

A direct link to a video file you own or may analyse (MP4, MOV, WebM, MKV...), up to 120 s and 250 MB. Links to YouTube, TikTok, Instagram, Vimeo and other platforms that forbid downloads are refused. The prefilled link is the Sintel trailer (Blender Foundation, CC BY 3.0). If empty, its first 10 s are analysed as a free demo.

## `videoBase64` (type: `string`):

For n8n/Make binaries: the clip as base64 or a data: URL. Keep the whole input under about 9 MB; use a URL for bigger clips.

## `fileName` (type: `string`):

Optional, for example spot.mp4.

## `rightsConfirmed` (type: `boolean`):

Required for your own clips (not needed for the public Sintel sample). The clip is only analysed; nothing from it is published or redistributed.

## `maxSeconds` (type: `integer`):

Clips longer than this fail (not charged) unless 'trimToLimit' is on.

## `trimToLimit` (type: `boolean`):

For longer clips: analyse the start and ignore the rest.

## `cutSensitivity` (type: `string`):

PySceneDetect adaptive threshold. Lower (2.0) finds more cuts, higher (4.5) fewer. 3.0 suits most edits.

## `minShotSeconds` (type: `string`):

Cuts closer than this are merged (flash frames).

## `visionProvider` (type: `string`):

Optional: describe subject, setting, shot size, angle, lens and mood with your own API key. You pay the provider directly (typically well under $0.01 per minute of video). Without a key the run still succeeds with the measured breakdown.

## `visionApiKey` (type: `string`):

Used only for this run's requests to the provider you picked; never logged or stored.

## `visionModel` (type: `string`):

Optional, any vision model id of the provider.

## `maxShotsForVision` (type: `integer`):

Caps your provider cost on very fast edits.

## `saveKeyframes` (type: `boolean`):

Keeps the 1-2 analysed frames per shot in this run's key-value store (private to your account, no public links).

## Actor input object example

```json
{
  "videoUrl": "https://api.apify.com/v2/key-value-stores/ZHc6C27RfpYYgLG7z/records/sintel-trailer-480p.mp4?signature=JYCwugVSqXRTspEmku9Z",
  "rightsConfirmed": false,
  "maxSeconds": 120,
  "trimToLimit": false,
  "cutSensitivity": "3.0",
  "minShotSeconds": "0.4",
  "visionProvider": "none",
  "maxShotsForVision": 60,
  "saveKeyframes": false
}
```

# Actor output Schema

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

No description

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

No description

# 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 = {
    "videoUrl": "https://api.apify.com/v2/key-value-stores/ZHc6C27RfpYYgLG7z/records/sintel-trailer-480p.mp4?signature=JYCwugVSqXRTspEmku9Z"
};

// Run the Actor and wait for it to finish
const run = await client.actor("ferrolark/cinematic-shot-breakdown").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 = { "videoUrl": "https://api.apify.com/v2/key-value-stores/ZHc6C27RfpYYgLG7z/records/sintel-trailer-480p.mp4?signature=JYCwugVSqXRTspEmku9Z" }

# Run the Actor and wait for it to finish
run = client.actor("ferrolark/cinematic-shot-breakdown").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "videoUrl": "https://api.apify.com/v2/key-value-stores/ZHc6C27RfpYYgLG7z/records/sintel-trailer-480p.mp4?signature=JYCwugVSqXRTspEmku9Z"
}' |
apify call ferrolark/cinematic-shot-breakdown --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ferrolark/cinematic-shot-breakdown"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/UoEqmx1QLY4BaXmlF/builds/abHNFcUGcVRqPtaON/openapi.json
