Video frame extractor: how to get frames and thumbnails from a video (API, Python, no code)

Q: How do I use the Video frame extractor from Python?

Install the apify-client package, create a client with your Apify API token, call the Actor v0iddo/video-frame-extractor with an input like the one above, and read the rows from the run's dataset. The Python snippet above does exactly that.

Q: How do I limit the number of results?

Set the maxItems input field to the number of results you need; the run stops there, so it also caps the cost of one run. You can also set a maximum cost for a run in the run options on Apify, and the run stops when it is reached.

Extract still frames from video files as JPEG, PNG or WebP images with timecodes: one every N seconds, a number evenly spaced, exact times, one per scene or every keyframe, plus a contact sheet. This guide shows the output fields, a working input, and Python, JavaScript and cURL code for the Actor v0iddo/video-frame-extractor on Apify.

Open Video frame extractor on Apify

What data you get

One row per result. Every row can be downloaded as JSON, CSV, Excel or HTML, or read through the API.

Field	Label	Type	Example
`imageUrl`	Frame	image URL	https://api.apify.com/v2/key-value-stores/qp1WtKypldaV10Cny/records...
`timecode`	Time	text	00:00:03.045
`frameNumber`	No.	number	1
`kind`	Row	text	frame
`videoFile`	Video	text	Modern_Times_trailer_(1936).webm
`imageWidth`	Width	number	472
`imageHeight`	Height	number	360
`videoDurationSeconds`	Video length (s)	number	121.5
`videoUrl`		text	https://upload.wikimedia.org/wikipedia/commons/8/86/Modern_Times_tr...
`requestedSeconds`		number	3.039
`timeSeconds`		number	3.045
`imageFormat`		text	jpeg
`imageBytes`		number	22885
`keyframe`		true/false	false
`mode`		text	count
`videoWidth`		number	472
`videoHeight`		number	360
`videoFps`		number	23.976
`videoCodec`		text	vp8
`videoContainer`		text	matroska
`videoBytes`		number	10916363
`frames`		number	1
`extractedAt`		text	2026-10-26T07:24:02Z

Input example

This is the input that is pre-filled on the Actor page. Change the values for your own run.

{
  "videoUrls": [
    "https://upload.wikimedia.org/wikipedia/commons/8/86/Modern_Times_trailer_%281936%29.webm"
  ],
  "mode": "count",
  "frameCount": 20,
  "maxItems": 20
}

Input field	Type	What it does
`videoUrls` (required)	array	Direct links to video files: MP4, MOV, M4V, WEBM, MKV, AVI, FLV, MPEG TS, OGV, WMV, MXF or animated GIF.
`mode`	string	Every N seconds (Seconds between frames), a number of frames spread evenly over the video (Number of frames), the times you list (Times), the first frame of each scene...
`intervalSeconds`	integer	For One frame every N seconds: the first frame is at Start at second.
`frameCount`	integer	For evenly spaced frames: each frame sits in the middle of its equal part of the video, so the first and last are not the black start and end.
`timestamps`	array	For Frames at exact times: seconds or hours:minutes:seconds, such as 90, 1:30 or 00:01:30.5.
`sceneSensitivity`	string	For One frame per scene: how much the picture must change to count as a new scene.
`startSeconds`	integer	Skip the part of each video before this second.
`endSeconds`	integer	Stop at this second of each video; 0 reads to the end.
`maxFramesPerVideo`	integer	Caps the frames of one video in every mode.
`maxWidth`	integer	Wider frames are scaled down to this width, keeping their shape; 0 keeps the size of the video.
`imageFormat`	string	File type of the frame images.
`imageQuality`	integer	JPEG and WebP quality from 1 to 100; PNG is always lossless.
`contactSheet`	boolean	Add one image per video that shows its frames side by side with their times (up to 100 frames).
`maxItems`	integer	The run stops after this many result rows.

Output sample

Real rows from a run of the Actor. Fields that name people are left out of the sample.

[
  {
    "kind": "frame",
    "videoUrl": "https://upload.wikimedia.org/wikipedia/commons/8/86/Modern_Times_trailer_%281936%29.webm",
    "videoFile": "Modern_Times_trailer_(1936).webm",
    "frameNumber": 1,
    "requestedSeconds": 3.039,
    "timeSeconds": 3.045,
    "timecode": "00:00:03.045",
    "imageUrl": "https://api.apify.com/v2/key-value-stores/qp1WtKypldaV10Cny/records/000001-Modern_Times_trailer_(1936)-0001-00h00m03s045.jpg?signature=1j...",
    "imageFormat": "jpeg",
    "imageWidth": 472,
    "imageHeight": 360,
    "imageBytes": 22885,
    "keyframe": false,
    "mode": "count",
    "videoDurationSeconds": 121.5,
    "videoWidth": 472,
    "videoHeight": 360,
    "videoFps": 23.976,
    "videoCodec": "vp8",
    "videoContainer": "matroska",
    "videoBytes": 10916363,
    "frames": 1,
    "extractedAt": "2026-10-26T07:24:02Z"
  },
  {
    "kind": "frame",
    "videoUrl": "https://upload.wikimedia.org/wikipedia/commons/8/86/Modern_Times_trailer_%281936%29.webm",
    "videoFile": "Modern_Times_trailer_(1936).webm",
    "frameNumber": 2,
    "requestedSeconds": 9.116,
    "timeSeconds": 9.134,
    "timecode": "00:00:09.134",
    "imageUrl": "https://api.apify.com/v2/key-value-stores/qp1WtKypldaV10Cny/records/000002-Modern_Times_trailer_(1936)-0002-00h00m09s134.jpg?signature=rp...",
    "imageFormat": "jpeg",
    "imageWidth": 472,
    "imageHeight": 360,
    "imageBytes": 25440,
    "keyframe": false,
    "mode": "count",
    "videoDurationSeconds": 121.5,
    "videoWidth": 472,
    "videoHeight": 360,
    "videoFps": 23.976,
    "videoCodec": "vp8",
    "videoContainer": "matroska",
    "videoBytes": 10916363,
    "frames": 1,
    "extractedAt": "2026-10-26T07:24:02Z"
  }
]

Code: Python, JavaScript and cURL

Get your API token in Apify Console under Settings, then Integrations. The Actor id is v0iddo/video-frame-extractor.

Python (apify-client)

from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run_input = {'videoUrls': ['https://upload.wikimedia.org/wikipedia/commons/8/86/Modern_Times_trailer_%281936%29.webm'],
 'mode': 'count',
 'frameCount': 20,
 'maxItems': 20}

run = client.actor("v0iddo/video-frame-extractor").call(run_input=run_input)
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

JavaScript (apify-client)

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const input = {
  "videoUrls": [
    "https://upload.wikimedia.org/wikipedia/commons/8/86/Modern_Times_trailer_%281936%29.webm"
  ],
  "mode": "count",
  "frameCount": 20,
  "maxItems": 20
};

const run = await client.actor('v0iddo/video-frame-extractor').call(input);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

cURL

curl -X POST "https://api.apify.com/v2/acts/v0iddo~video-frame-extractor/run-sync-get-dataset-items" \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"videoUrls": ["https://upload.wikimedia.org/wikipedia/commons/8/86/Modern_Times_trailer_%281936%29.webm"], "mode": "count", "frameCount": 20, "maxItems": 20}'

Price

$1.50 per 1,000 results. You pay per result row. There is no separate charge per run. Higher Apify plans pay less per result, down to $1.05 per 1,000. See the pricing tab for your plan. A new Apify account gets $5 of platform credit every month.

Good to know

One row per frame: the image link (imageUrl), its time in seconds and as a timecode, its size, whether it is a keyframe, and the length, size, frame rate, codec and container of the video. With...
The images are files in the run's key-value store; imageUrl opens them directly and works in the dataset table, in spreadsheets and in your own code. They are kept as long as your Apify plan keeps...
Files up to 250 MB are downloaded once and read from disk. Bigger ones are read with range requests around each frame, so ten frames from a two hour film read a small part of the file. Scene and...
Scenes: the frame is the first keyframe of each new scene. Most web video has a keyframe at every cut; camera files and some screen recordings place keyframes every one or two seconds, so a scene...

FAQ

What data does the Video frame extractor return?

Each result is one row in an Apify dataset. Fields include imageUrl, timecode, frameNumber, kind, videoFile, imageWidth, imageHeight, videoDurationSeconds, and more. The table above shows every field with an example value.

How do I use the Video frame extractor from Python?

Install the apify-client package, create a client with your Apify API token, call the Actor v0iddo/video-frame-extractor with an input like the one above, and read the rows from the run's dataset. The Python snippet above does exactly that.

Can I use it without writing code?

Yes. Open the Actor page on Apify, fill in the input form (an example is already filled in), press Start, and download the results as JSON, CSV, Excel or HTML. You can also schedule runs there.

How much does it cost?

$1.50 per 1,000 results. You pay per result row. There is no separate charge per run. Higher Apify plans pay less per result, down to $1.05 per 1,000. A new Apify account gets $5 of platform credit every month.

How do I limit the number of results?

Set the maxItems input field to the number of results you need; the run stops there, so it also caps the cost of one run. You can also set a maximum cost for a run in the run options on Apify, and the run stops when it is reached.

Can I send the results to Google Sheets, Make, Zapier or n8n?

Yes. Apify datasets connect to Google Sheets, Slack, Make, Zapier and n8n, and a webhook can call your own service when a run finishes. You can also export the dataset as JSON, CSV or Excel.

Open Video frame extractor on Apify

Related guides

Google Maps Scraper: Scrape Google Maps business listings by search and place: name, category, address, coordinates, rating, rev...
Bulk file and image downloader: Download files in bulk from direct links, or every image, video, audio file, PDF, document or archive on a...
Website screenshot API: Capture a public web page as a PNG, JPEG or WEBP image: any viewport size, full page, retina scaling, optio...