# Video Frame Extractor: Video URL to JPG, PNG & WebP Frames (`atesen-software/video-frame-extractor`) Actor

Extract frames from video file URLs with ffmpeg. Pick every N seconds, N evenly spaced frames, scene changes or exact timestamps. Get JPG, PNG or WebP images with public links, timestamps and sizes, ready for AI vision, thumbnails and video analysis.

- **URL**: https://apify.com/atesen-software/video-frame-extractor.md
- **Developed by:** [Atesen Software](https://apify.com/atesen-software) (community)
- **Categories:** Videos, AI, Developer tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$2.00 / 1,000 frame extracteds

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

## Video Frame Extractor: Video URL to JPG, PNG & WebP Frames

Give this Actor a link to a video file and it returns still images from it: **one frame every N seconds, N evenly spaced frames, a frame at every scene change, or frames at exact timestamps**. Every frame is saved as a JPG, PNG or WebP image with a public link, and every frame gets one dataset row with its timestamp, size and image URL.

Use it to feed **video to AI vision models**, to build **video thumbnails and contact sheets**, to sample **training data for machine learning**, to check **video quality**, or to turn a video into a set of pictures a person or a model can skim.

### What it does

- **Extract frames from a video URL.** The Actor downloads the file once, reads it with ffmpeg and cuts the frames you asked for.
- **Four ways to pick frames.** Interval (every N seconds), count (N evenly spaced frames), scene changes (video keyframes at every cut, with a strength score) and exact timestamps.
- **Image output you control.** JPG, PNG or WebP, maximum width (frames are scaled down, never up), JPG/WebP quality, start and end of the range.
- **Ready-to-use results.** One dataset row per frame: `videoUrl`, `frameIndex`, `timestampSec`, `imageUrl`, `width`, `height`, `bytes`, `mode`. Open the images by link, or export the rows as JSON, CSV or Excel.
- **Many videos per run.** Up to 200 URLs per run, each with its own result and error message.
- **No account on the video site, no proxy, no browser.**

### What it does not do

- **It reads direct links to video files only** (the URL opens the .mp4, .webm, .mov, .mkv, .avi, .flv or .ts file itself). **Page links from YouTube, Vimeo, TikTok, Instagram, Facebook, X and other video platforms are not supported**, and the Actor does not try to download from them. Use a file you host (S3, Cloudflare R2, Google Cloud Storage, a CDN, your own server, Dropbox links ending in `?dl=1`) or a file you are allowed to fetch.
- It does not read streaming playlists (HLS .m3u8, DASH .mpd), DRM-protected files or videos behind a login.
- It does not transcribe audio, recognise text or faces, or describe the pictures. It gives you the frames; send them to the AI model of your choice.
- Local, private and internal addresses are blocked on purpose (see Security).

### Input

| Field | What it does | Default |
|---|---|---|
| `videoUrls` | Direct video file URLs, one per line (up to 200). | two sample clips |
| `mode` | `interval`, `count`, `scenes` or `timestamps`. | `interval` |
| `intervalSeconds` | Interval mode: seconds between frames. | 5 |
| `frameCount` | Count mode: how many frames per video. | 8 |
| `sceneThreshold` | Scenes mode: sensitivity (0.15 very sensitive, 0.3 balanced, 0.5 hard cuts only). | 0.3 |
| `timestamps` | Timestamps mode: seconds (`12.5`) or clock time (`1:30`, `01:02:03.5`). | none |
| `imageFormat` | `jpg`, `png` or `webp`. | `jpg` |
| `maxWidth` | Longest width in pixels; 0 keeps the original size. | 1280 |
| `quality` | 1-100 for JPG and WebP. | 85 |
| `startSec` / `endSec` | Only use this part of the video (not used by timestamps mode). | whole video |
| `maxFramesPerVideo` | Safety cap per video (1-1000). | 100 |
| `maxVideoSizeMb` | Skip files larger than this (1-1024 MB). | 200 |
| `downloadTimeoutSecs` | Skip a video that does not download in time. | 600 |

Example: one frame per second from the first minute of two videos, as WebP.

```json
{
  "videoUrls": ["https://example.com/demo.mp4", "https://example.com/tour.webm"],
  "mode": "interval",
  "intervalSeconds": 1,
  "startSec": 0,
  "endSec": 60,
  "imageFormat": "webp",
  "maxWidth": 960
}
```

Example: scene changes only, for an AI vision pipeline.

```json
{ "videoUrls": ["https://example.com/ad.mp4"], "mode": "scenes", "sceneThreshold": "0.3", "maxFramesPerVideo": 30 }
```

### Output

Each delivered frame is one dataset row:

```json
{
  "videoUrl": "https://www.w3schools.com/html/mov_bbb.mp4",
  "frameIndex": 2,
  "timestampSec": 4,
  "imageUrl": "https://api.apify.com/v2/key-value-stores/<storeId>/records/v1-f0002-t4000ms.jpg",
  "key": "v1-f0002-t4000ms.jpg",
  "width": 320,
  "height": 176,
  "bytes": 5142,
  "format": "jpg",
  "mode": "interval",
  "sceneScore": null,
  "error": null
}
```

- The images live in the run's **key-value store**; `imageUrl` is the link to each one. Keys read `v<video number>-f<frame number>-t<milliseconds>.<format>`.
- A video that cannot be processed produces one row with an `error` text (for example "The video URL returned 404") and no image.
- The key-value store also holds a `SUMMARY` record: per video the duration, size, frames delivered, notes (for example "3 timestamps are beyond the end of the video"), and why the run stopped.
- Storage follows your Apify plan's data retention; download the frames you want to keep.

#### How the modes behave

- **Interval:** frames at start, start + N, start + 2N, ... and never at or past the end of the video. If more than `maxFramesPerVideo` would result, it stops at the cap.
- **Count:** the range is cut into N equal slices and the frame is taken from the middle of each, which avoids black first and last frames.
- **Scenes:** the opening frame plus one frame at every detected cut. Each cut row carries `sceneScore` (0 to 1). If there are more cuts than `maxFramesPerVideo`, the strongest cuts are kept.
- **Timestamps:** exactly the times you list, in time order. Times after the end of the video are skipped and reported in `SUMMARY`.

### Use cases

- Send video frames to GPT, Claude, Gemini or another **vision model** for captioning, moderation or search.
- Build **thumbnails, storyboards and preview images** for a video library.
- Collect **frames for machine learning datasets** (every N seconds or at scene changes).
- Check what a video looks like at known moments (QA, compliance review, ad review).
- Create **keyframes** for slide-style summaries of talks and demos.

### Pricing and cost control

You pay for **delivered frames** (pay per event: one event per frame saved and returned as a dataset row). Videos that fail, blocked URLs, frames that cannot be decoded, and timestamps beyond the end of the video cost nothing. Set **Maximum cost per run** in the run options: the Actor stops cleanly at that limit and never delivers frames it could not charge.

**Maximum items is a hard cap on charged rows.** Set `maxItems` in the run options (or `?maxItems=` in the API) and the run stops after that many frames: it never writes or charges more rows than that number. Leave it empty for no cap. Free status rows are not counted.

### Security and limits

- Only `http` and `https` URLs are fetched. The Actor refuses localhost, private network ranges, link-local and cloud metadata addresses, IPv6 equivalents and names that resolve to them, and it checks every redirect. Credentials inside a URL are not accepted.
- Each video is downloaded to a temporary file first (size and time limits apply); ffmpeg only ever reads that local file, and the file type is verified before it is opened.
- Limits: 200 URLs per run, files up to 1 GB (200 MB by default; the run disk is twice the run memory, so very large files need more memory), videos up to 120 minutes, pictures up to 4K (4096 x 2304 pixels; larger videos such as 8K are skipped for free), up to 1000 frames per video.
- Only the frames you request are stored. The Actor collects no personal data. You are responsible for having the right to process the videos you submit, including any people or private content shown in them.
- **Privacy of the frame links:** the images are stored in your run's key-value store and `imageUrl` is a link that opens the picture for anyone who holds it. Do not post the links of frames that show private or sensitive content, and delete the run's storage when you no longer need the images.

### Use via API

One request runs the Actor, waits for it and returns the dataset items as JSON. Send your token in the `Authorization` header, not in the URL:

```bash
curl -X POST "https://api.apify.com/v2/acts/atesen-software~video-frame-extractor/run-sync-get-dataset-items?timeout=120" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"videoUrls":["https://www.w3schools.com/html/mov_bbb.mp4"],"mode":"interval","intervalSeconds":2,"imageFormat":"jpg"}'
```

The synchronous endpoint waits up to 300 seconds. For longer jobs start a run with `POST https://api.apify.com/v2/acts/atesen-software~video-frame-extractor/runs` and read the dataset when it finishes.

**JavaScript** (`npm install apify-client`):

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('atesen-software/video-frame-extractor').call({ videoUrls: ["https://www.w3schools.com/html/mov_bbb.mp4"], mode: "interval", intervalSeconds: 2, imageFormat: "jpg" });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Use with AI agents (MCP)

Claude Desktop, Cursor, VS Code and other MCP clients can call this Actor as a tool through the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp). Load only this Actor with:

```text
https://mcp.apify.com?tools=atesen-software/video-frame-extractor
```

Client config (sign in with Apify OAuth when the browser opens, or add an `Authorization: Bearer <APIFY_TOKEN>` header instead):

```json
{
  "mcpServers": {
    "apify": { "url": "https://mcp.apify.com?tools=atesen-software/video-frame-extractor" }
  }
}
```

Then ask in plain words, for example: "Extract one JPG frame every 2 seconds from https://www.w3schools.com/html/mov_bbb.mp4." The agent fills the same input fields you see on the Input tab, and runs are billed to your Apify account at the prices on the Pricing tab.

### FAQ

**Can I use a YouTube link?** No. YouTube, Vimeo, TikTok, Instagram and similar pages are not supported. The Actor needs a link that opens the video file itself.

**Why did my link fail with "web page, not a video file"?** The server answered with an HTML page (a player page, a login page or an error). Open the link in a browser: it should start downloading or playing the raw file.

**Which video formats work?** MP4/MOV/M4V, WebM/MKV, AVI, FLV, MPEG-TS/PS, Ogg, ASF/WMV and GIF containers, with the codecs ffmpeg can decode (for example H.264, H.265 and VP9).

**Are rotated phone videos handled?** Yes, frames come out upright and with square pixels.

**Do I get the whole video as images?** Only as many frames as you ask for. Use a small interval and a high `maxFramesPerVideo` for dense sampling.

**What are the sample videos?** The default input uses two short public clips so the Actor works out of the box. The first is a Big Buck Bunny clip, (c) copyright 2008 Blender Foundation, www.bigbuckbunny.org, licensed [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/), as hosted by w3schools.com; the frames you get from it are cut-outs of that clip and keep that license and credit. The second is the "flower" clip from the MDN Web Docs sample media, released under CC0 (public domain). Replace both with your own links.

### Support

Questions or a video type that does not work? Open an issue on the Actor page and include the run link. Built by Atesen Software.

### Related actors

- [Audio & Video Transcriber API: Speech to Text, SRT, VTT](https://apify.com/atesen-software/audio-video-transcriber)
- [Bulk Image Downloader: Download Images from a URL List to ZIP](https://apify.com/atesen-software/bulk-image-downloader)
- [Website Screenshot & PDF API (Bulk, No Cookie Banners)](https://apify.com/atesen-software/website-screenshot-pdf-api)

# Actor input Schema

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

Direct links to video files (.mp4, .mov, .webm, .mkv, .avi, .flv, .ts), one per line, up to 200 per run. The link must open the file itself and be public. Page links from YouTube, Vimeo, TikTok, Instagram and similar sites are not supported.

## `mode` (type: `string`):

Interval: one frame every N seconds. Count: N frames spread evenly (each taken from the middle of an equal slice). Scenes: the opening frame plus one frame at every scene change. Timestamps: frames at the exact times you list.

## `intervalSeconds` (type: `number`):

Interval mode: seconds between frames, starting at the start time. Use 1 for one frame per second.

## `frameCount` (type: `integer`):

Count mode: how many frames to take per video, spread evenly between the start and end time.

## `sceneThreshold` (type: `string`):

Scenes mode: how different two neighbouring pictures must be to count as a cut. Lower finds more, subtler changes (0.2 catches soft cuts), higher finds only hard cuts (0.5).

## `timestamps` (type: `array`):

Timestamps mode: the moments to capture, one per line. Seconds (90 or 12.5) or clock time (1:30, 01:02:03.5). Times after the end of the video are skipped and cost nothing.

## `imageFormat` (type: `string`):

JPG is the smallest and works everywhere. PNG is lossless and much larger. WebP is small with high quality.

## `maxWidth` (type: `integer`):

Frames wider than this are scaled down with the aspect ratio kept. Frames are never scaled up. 1280 is plenty for AI vision models. Use 0 to keep the original size.

## `quality` (type: `integer`):

1 to 100. Applies to JPG and WebP. PNG is always lossless.

## `startSec` (type: `number`):

Ignore everything before this point. Applies to interval, count and scenes modes.

## `endSec` (type: `number`):

Ignore everything after this point. Leave empty to run to the end of the video.

## `maxFramesPerVideo` (type: `integer`):

Safety cap per video, 1 to 1000. When a mode would produce more, interval and timestamps stop at the cap, and scenes keeps the strongest cuts.

## `maxVideoSizeMb` (type: `integer`):

Videos larger than this are skipped for free (1 to 1024 MB). The Actor downloads each video once, so large files take longer.

## `downloadTimeoutSecs` (type: `integer`):

A video that is not fully downloaded within this time is skipped for free.

## Actor input object example

```json
{
  "videoUrls": [
    "https://www.w3schools.com/html/mov_bbb.mp4",
    "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
  ],
  "mode": "interval",
  "intervalSeconds": 2,
  "frameCount": 8,
  "sceneThreshold": "0.3",
  "imageFormat": "jpg",
  "maxWidth": 1280,
  "quality": 85,
  "startSec": 0,
  "maxFramesPerVideo": 100,
  "maxVideoSizeMb": 200,
  "downloadTimeoutSecs": 600
}
```

# Actor output Schema

## `frames` (type: `string`):

One row per frame: video URL, frame index, timestamp, public image URL, size

## `images` (type: `string`):

All frame images in the run's key-value store

## `summary` (type: `string`):

Per-video result: frames delivered, duration, size, notes and why the run stopped

# 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://www.w3schools.com/html/mov_bbb.mp4",
        "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
    ],
    "intervalSeconds": 2
};

// Run the Actor and wait for it to finish
const run = await client.actor("atesen-software/video-frame-extractor").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://www.w3schools.com/html/mov_bbb.mp4",
        "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
    ],
    "intervalSeconds": 2,
}

# Run the Actor and wait for it to finish
run = client.actor("atesen-software/video-frame-extractor").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://www.w3schools.com/html/mov_bbb.mp4",
    "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
  ],
  "intervalSeconds": 2
}' |
apify call atesen-software/video-frame-extractor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,atesen-software/video-frame-extractor"
        }
    }
}
```

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/muWCR1A87aaQIh0n1/builds/UmzZyagqKezyzzuAw/openapi.json
