# Video AI Analyzer — Hook, Shot List, Script & Summary (`tidydata/video-ai-analyzer`) Actor

Turn your video files into a structured AI breakdown: hook score, sections, shot-by-shot keyframes, on-screen text, CTA, pacing (cuts per minute), summary, chapters or the answer to your question, plus the transcript. MP4, Drive, Dropbox, OneDrive. Works with n8n, Make and AI agents.

- **URL**: https://apify.com/tidydata/video-ai-analyzer.md
- **Developed by:** [tidydata](https://apify.com/tidydata) (community)
- **Categories:** AI, Videos, Social media
- **Features:** Limited permissions
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 videos

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## 🎬 Video AI Analyzer — Hook Score, Shot List, Script, Pacing & Summary from Video Files

![One video file turned into a hook score, a shot list with keyframes and on-screen text, and measured pacing: 26 cuts, 13 cuts per minute, 7 labelled sections (real output)](https://raw.githubusercontent.com/tidydata-dev/tidydata-dev/main/assets/apify/video-ai-analyzer.png)

Turn **your own video files** into a structured, AI-written breakdown you can sort, filter and reuse: the **opening hook with a 1-10 score**, the **structure in labelled sections** (Hook → Problem → Demo → Proof → CTA), a **shot-by-shot list with keyframe images and on-screen text**, the **call to action**, brands and products shown, **measured pacing (cuts per minute, average shot length)**, a summary or chapters, the **answer to any question** you ask, and the **timestamped transcript**.

Works with **direct links (.mp4, .mov, .webm, .mkv…), Google Drive files and folders, Dropbox, OneDrive / SharePoint, Amazon S3 or Cloud Storage links, archive.org and .m3u8 streams**. From **$0.025 per video**. Failed videos are free.

### What can I use it for?

- **Ad creative reviews** — score the first 3 seconds of every ad variant before you spend money on it, and get concrete ideas to improve each one.
- **UGC and influencer deliveries** — check that each creator's video shows the product, says the key message and has a call to action, in bulk.
- **Content libraries and courses** — summaries, key points and chapters with start times for lessons, webinars and talks.
- **Storyboards and briefs** — a shot list with keyframe images and on-screen text, ready for Notion, Google Sheets or your editor.
- **Automations and AI agents** — one call from n8n, Make, Zapier or an MCP client (Claude, ChatGPT, Cursor) returns clean JSON for each video.

### How it works

1. The video is downloaded (up to 1 GB) and **every cut is measured** with FFmpeg's scene detection — the pacing numbers are measured, not guessed.
2. **Keyframes** are taken from the shots (one per shot, 6-16 for videos up to 5 minutes, 12-20 for longer ones; the first one is always inside the hook).
3. The speech is transcribed with **Whisper large-v3-turbo** (99 languages).
4. **Claude Haiku 5.5** (Anthropic) reads the keyframes, the transcript and the cut list and writes the breakdown, with a strict JSON schema so every row has the same fields.

### Input

| Field | What it does |
|---|---|
| `videoUrls` | One link per line: files you own or may analyze (see the list above). |
| `analysis` | `creative` (hook, structure, shot list, CTA, ideas — default), `summary` (key points, chapters, topics) or `custom` (answer your question). |
| `question` | Optional: anything you want answered in `answer` — e.g. *"List every product shown with the time it appears"* or *"Write 3 alternative hooks"*. Required in `custom` mode. |
| `outputLanguage` | English (default), Same as video, Spanish, Portuguese, French, German, Italian and 12 more. Quotes stay in their original language (`translateQuotes` adds a translation). |
| `datasetId` | Or: a dataset from another run with links to video files (field detected automatically, or set `datasetUrlField`). |
| `maxFrames` | Keyframes per video (0 = automatic, up to 24). Same price. |
| `maxVideoMinutes` | Analyze (and pay for) up to this many minutes per video. Default 30. |
| `includeTranscript`, `saveFrames` | Transcript and keyframe images on or off. |

```json
{
  "videoUrls": ["https://example.com/ads/summer-ad-v2.mp4", "https://drive.google.com/file/d/FILE_ID/view"],
  "analysis": "creative",
  "question": "Write 3 alternative opening hooks for this video.",
  "outputLanguage": "English"
}
```

### Output (real example)

From a 2-minute NASA explainer video (public domain), `creative` mode:

```json
{
  "fileName": "NHQ_2020_0127_AskNASA┃ How Will Astronauts Dig on the Moon~small.mp4",
  "status": "ok",
  "durationSeconds": 304.33,
  "analyzedSeconds": 120,
  "orientation": "horizontal",
  "summary": "A NASA Ask NASA episode in which geologist Jacob Bleacher (named on lower-third) answers 'What is unique about the surface of the Moon?' … demonstrates crater formation with a foil tray of powder and a golf ball …",
  "hook": {
    "description": "Man in a graphic tee faces camera against a plain backdrop and introduces himself and his job, followed by the Ask NASA logo animation.",
    "spokenLine": "Hi, I'm Jacob Bleacher. I'm a geologist. That means I study rocks and dirt on the Earth and planets.",
    "onScreenText": null,
    "score": 4,
    "why": "Clear and friendly but not a strong hook … no tension or visual payoff appears in the first 3 seconds."
  },
  "structure": [
    {"start": 0, "end": 9.9, "label": "Intro", "description": "Presenter introduces himself and the Ask NASA series."},
    {"start": 10.5, "end": 16.7, "label": "Branding", "description": "Ask NASA logo animation."},
    {"start": 18.2, "end": 32.6, "label": "Question 1 setup", "description": "Question card shown; presenter explains the Moon has no atmosphere so surface processes are preserved."}
  ],
  "format": "presentation / webinar",
  "tone": "friendly, educational, playful",
  "targetAudience": "general public and space enthusiasts curious about Moon science",
  "improvementIdeas": [
    "Open with the crater demo or the question 'Why are there circles on the Moon?' to hook faster.",
    "Put the on-screen question text earlier and in a bolder style.",
    "Add captions for accessibility and social viewing without sound."
  ],
  "answer": "1. 'Ever wonder why the Moon is covered in circles? Let me show you with a golf ball and a tray of dirt.' 2. 'The Moon has no air, so every crash from billions of years ago is still there.' 3. 'Astronauts might drink water from a crater that has never seen sunlight. Here's how.'",
  "pacing": {"cuts": 26, "shots": 27, "avgShotSeconds": 4.44, "cutsPerMinute": 13, "firstCutSeconds": 10.53, "longestShotSeconds": 13.7, "measuredSeconds": 120},
  "shots": [
    {"index": 2, "timeSeconds": 20.28, "shotStart": 19.13, "shotEnd": 21.43,
     "frameUrl": "https://api.apify.com/v2/key-value-stores/…/records/v0-…-02.jpg",
     "description": "Presenter holds a question card while a lower-third name banner appears.",
     "onScreenText": "WHAT IS UNIQUE ABOUT THE SURFACE OF THE MOON? Jacob Bleacher Chief Exploration Scientist",
     "shotType": "medium"}
  ],
  "timestampedTranscript": [{"start": 0, "end": 6.5, "text": "Hi, I'm Jacob Bleacher. I'm a geologist. …"}],
  "note": "Only the first 2 min were analyzed.",
  "charged": true
}
```

`summary` mode returns `summary`, `keyPoints`, `chapters` (start, title, summary) and `topics` instead of the creative fields. The **Shot list** view of the dataset shows one row per keyframe with its image.

### Pricing

Pay per result — no subscription, no API keys of your own:

| Event | Price (Free plan) | Gold+ (-20 %) |
|---|---|---|
| Video analyzed (up to 3 minutes) | **$0.025** | $0.02 |
| Each extra minute beyond 3 | $0.008 | $0.0064 |

A 30-second ad costs $0.025; a 10-minute webinar costs $0.025 + 7 × $0.008 = $0.081. Videos that fail (private, broken, no video track) are **free**. Set **Max cost per run** in Apify to cap any run.

On the free Apify plan the Actor runs as a demo: 1 video per run, first 3 minutes, up to 8 keyframes.

### FAQ

**Can I analyze YouTube, TikTok or Instagram videos?** No. Their terms forbid downloading, so links to those platforms (and their CDNs) are refused for free. Use video files you own or have the right to analyze — your ads, your creators' deliveries, your courses. For YouTube text, use our [YouTube Transcript Scraper](https://apify.com/tidydata/youtube-transcript-scraper).

**Are the pacing numbers made up by the AI?** No. Cuts are measured with FFmpeg's scene detection on every frame (first 15 minutes of each video); the AI only describes what it sees and hears.

**Will it tell me who the people are?** No. People are described by role, look and action. Names appear only when they are said or written in the video itself.

**What if the video has no speech?** It still works from the keyframes and says the video has no speech (`hasSpeech: false`).

**How long can a video be?** Up to 1 GB and 120 minutes per video (`maxVideoMinutes`). Long videos get more keyframes spread over their whole length.

**Can I use it from n8n, Make or an AI agent?** Yes — call the Actor with `videoUrls` and read the dataset. It runs with **limited permissions**, so it works without extra approval from MCP clients and automations.

**Is my video stored?** Only the keyframe images you choose to save stay in your own run storage. The video file is deleted when the run ends.

### Related Actors

- [Speech to Text — Audio & Video Transcription](https://apify.com/tidydata/audio-video-transcription): transcripts with SRT/VTT subtitles, $0.005 per minute.
- [Video Frame Extractor](https://apify.com/tidydata/video-frame-extractor): every N seconds or a fixed number of frames as JPG/PNG/WebP.
- [Merge Datasets & Remove Duplicates](https://apify.com/tidydata/merge-dedupe-datasets): combine, filter and export the results of several runs to CSV or Excel.

Made by [TidyData](https://apify.com/tidydata). Questions or a feature you need? Open an issue on the Actor's page — we answer every one.

# Actor input Schema

## `videoUrls` (type: `array`):

One link per line. Videos you own or have the right to analyze: direct files (.mp4, .mov, .webm, .mkv, .avi… up to 1 GB), Google Drive files or public folders, Dropbox, OneDrive/SharePoint share links, archive.org, Wikimedia Commons, Amazon S3 / Cloud Storage links, .m3u8 streams or a web page that contains a video file. YouTube, TikTok, Instagram, X, Vimeo and other platforms are not supported (their terms forbid downloading).

## `analysis` (type: `string`):

Creative breakdown scores the opening hook and splits the video into labelled sections (Hook, Problem, Demo, CTA…). Summary gives key points and chapters with start times. Every mode includes the shot list with keyframes and on-screen text, the measured pacing and the transcript.

## `question` (type: `string`):

Anything you want to know, answered in the 'answer' field. Examples: 'List every product shown with the time it appears', 'Is the price mentioned? When?', 'Write 3 alternative hooks for this ad'. Required in 'Answer my question' mode.

## `outputLanguage` (type: `string`):

Language of the analysis. Quotes of spoken words and on-screen text stay in their original language.

## `translateQuotes` (type: `boolean`):

Add a translation in brackets after quotes of spoken words and on-screen text.

## `datasetId` (type: `string`):

A dataset from another run that has links to video files (for example our Google Drive or bulk file tools). Only read access to this one dataset is requested.

## `datasetUrlField` (type: `string`):

Leave empty to detect it (videoUrl, mediaUrl, fileUrl, url… or any value ending in .mp4/.mov/.webm).

## `maxFrames` (type: `integer`):

0 = automatic: one per shot, 6-16 for videos up to 5 minutes and 12-20 for longer ones. More keyframes = more detail in the shot list (same price).

## `maxVideoMinutes` (type: `integer`):

Longer videos are analyzed up to this point (and billed only for what is analyzed).

## `includeTranscript` (type: `boolean`):

Adds 'transcript' and 'timestampedTranscript' (Whisper large-v3-turbo, 99 languages).

## `saveFrames` (type: `boolean`):

Saves each keyframe as a JPEG and adds its link to shots\[].frameUrl (handy for storyboards, Notion or Sheets).

## `spokenLanguage` (type: `string`):

Two-letter code like en, es, pt, de. 'auto' detects it. Set it if the transcript comes out in the wrong language.

## `maxVideos` (type: `integer`):

Safety limit for folders and datasets with many videos.

## Actor input object example

```json
{
  "videoUrls": [
    "https://images-assets.nasa.gov/video/NHQ_2020_0127_AskNASA%E2%94%83%20How%20Will%20Astronauts%20Dig%20on%20the%20Moon/NHQ_2020_0127_AskNASA%E2%94%83%20How%20Will%20Astronauts%20Dig%20on%20the%20Moon~small.mp4"
  ],
  "analysis": "creative",
  "outputLanguage": "English",
  "translateQuotes": false,
  "maxFrames": 0,
  "maxVideoMinutes": 30,
  "includeTranscript": true,
  "saveFrames": true,
  "spokenLanguage": "auto",
  "maxVideos": 50
}
```

# Actor output Schema

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

One row per video: hook, structure, shots with keyframes, pacing, summary and transcript.

## `keyframes` (type: `string`):

Keyframe images (JPEG) saved by the run.

# 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 = {
    "videoUrls": [
        "https://images-assets.nasa.gov/video/NHQ_2020_0127_AskNASA%E2%94%83%20How%20Will%20Astronauts%20Dig%20on%20the%20Moon/NHQ_2020_0127_AskNASA%E2%94%83%20How%20Will%20Astronauts%20Dig%20on%20the%20Moon~small.mp4"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("tidydata/video-ai-analyzer").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 = { "videoUrls": ["https://images-assets.nasa.gov/video/NHQ_2020_0127_AskNASA%E2%94%83%20How%20Will%20Astronauts%20Dig%20on%20the%20Moon/NHQ_2020_0127_AskNASA%E2%94%83%20How%20Will%20Astronauts%20Dig%20on%20the%20Moon~small.mp4"] }

# Run the Actor and wait for it to finish
run = client.actor("tidydata/video-ai-analyzer").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 '{
  "videoUrls": [
    "https://images-assets.nasa.gov/video/NHQ_2020_0127_AskNASA%E2%94%83%20How%20Will%20Astronauts%20Dig%20on%20the%20Moon/NHQ_2020_0127_AskNASA%E2%94%83%20How%20Will%20Astronauts%20Dig%20on%20the%20Moon~small.mp4"
  ]
}' |
apify call tidydata/video-ai-analyzer --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,tidydata/video-ai-analyzer"
        }
    }
}
```

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/vWpNqumeAx82jldTW/builds/bSL9V9okZUbk3XAV6/openapi.json