Extract Video Frames — Timed Stills by Interval or Scene Cut

Extract video frames from direct video-file URLs at intervals, scene changes or chosen timestamps as JPEG, PNG or WebP, with duration, resolution and codecs; scene mode scans the full video and has a separate scanning event. AI agents can call and pay through Apify MCP.

The active Apify pricing record determines your bill; for the previous/checked schedules, frame-extracted previous/checked $0.001; video-probed previous/checked $0.002; minute-scanned previous/checked $0.015; usage is included and failed results are free.

Example result

Example record, as this Actor returned it on 2026-10-16 for the input of the example task "Extract a still frame every 5 seconds from a video" (intervalSec: 5, maxFrames: 10), run locally with the image's ffmpeg on the file fetched from that URL; the key-value store's id, set by the platform per run, is shown as <storeId>:

{
  "url": "https://raw.githubusercontent.com/intel-iot-devkit/sample-videos/57978890822836f2b4743852f04f62fc511757e4/car-detection.mp4",
  "ok": true,
  "metadata": {"durationSec": 30.16, "width": 768, "height": 432, "fps": 12.5, "videoCodec": "h264", "audioCodec": "aac", "hasAudio": true, "bitrate": 745770, "sizeBytes": 2811553},
  "frames": [
    {"timestampSec": 0.0, "key": "frame-00-000.jpg", "url": "https://api.apify.com/v2/key-value-stores/<storeId>/records/frame-00-000.jpg", "width": 768, "height": 432},
    {"timestampSec": 5.04, "key": "frame-00-001.jpg", "url": "https://api.apify.com/v2/key-value-stores/<storeId>/records/frame-00-001.jpg", "width": 768, "height": 432},
    {"timestampSec": 10.0, "key": "frame-00-002.jpg", "url": "https://api.apify.com/v2/key-value-stores/<storeId>/records/frame-00-002.jpg", "width": 768, "height": 432},
    {"timestampSec": 15.04, "key": "frame-00-003.jpg", "url": "https://api.apify.com/v2/key-value-stores/<storeId>/records/frame-00-003.jpg", "width": 768, "height": 432},
    {"timestampSec": 20.0, "key": "frame-00-004.jpg", "url": "https://api.apify.com/v2/key-value-stores/<storeId>/records/frame-00-004.jpg", "width": 768, "height": 432},
    {"timestampSec": 25.04, "key": "frame-00-005.jpg", "url": "https://api.apify.com/v2/key-value-stores/<storeId>/records/frame-00-005.jpg", "width": 768, "height": 432},
    {"timestampSec": 30.0, "key": "frame-00-006.jpg", "url": "https://api.apify.com/v2/key-value-stores/<storeId>/records/frame-00-006.jpg", "width": 768, "height": 432}
  ]
}

How to use it

Start a run in Apify Console, by API or from an agent with an input like this one — it is the input Apify runs every day to test this Actor:

{"urls": ["https://media.w3.org/2010/05/sintel/trailer.mp4"], "mode": "interval", "intervalSec": 10, "maxFrames": 3}

Start with the minimal JSON example above, then adjust the fields in the table below. Read the Example result and Output fields sections for the returned record, Errors for failure codes, and Events and prices for result events and the separate platform start.

Field	Type	Required	Default	Meaning
urls	array of strings	yes	—	Video file URLs (MP4, MOV, MKV, WebM, AVI, MPEG-TS, MPEG, FLV, OGG, MXF), http or https, 1–20 per run, up to 500 MB each. A link to the file itself; playlists (HLS, DASH) and video-platform pages are not read.
mode	enum interval · scenes · timestamps	no	interval	How frames are chosen: interval one every intervalSec seconds from the start; scenes the first frame and every scene change, decoding the whole video (also charged per started minute scanned); timestamps the seconds listed in timestamps.
intervalSec	integer	no	10	Seconds between frames in interval mode, 1–3,600: frames at 0, intervalSec, 2 × intervalSec, … up to the video's end.
timestamps	array of numbers	no	—	Seconds from the start for timestamps mode, e.g. [0, 12.5, 30]; at most 200, each 0 or more. Sorted and deduplicated; those past the video's end give no frame and the record says so. Required in timestamps mode.
maxFrames	integer	no	20	At most this many frames per video, 1–200; the earliest are kept.
format	enum jpeg · png · webp	no	jpeg	The frames' image format.
maxWidth	integer	no	1280	Frames wider than this are scaled down to it, keeping the aspect ratio; narrower frames keep their size (never scaled up). 32–7,680; dimensions are always even.

Every limit above is enforced by the input schema and again in code.

Events and prices

The active Apify pricing record determines your bill; each schedule below is conditional on that exact record being active. A pending record does not authorise its charges. Before submission, while pending, and after activation, use the actual active record, not the requested calendar, to determine the bill.

Observed effective start: 2026-10-17T03:18:59.775Z, confirmed by the pricing record; this stage requests no pricing mutation.

Previous schedule — only if that record is active

apify-actor-start: FREE $0.00005, BRONZE $0.00005, SILVER $0.00005, GOLD $0.00005, PLATINUM $0.00005, DIAMOND $0.00005; frame-extracted: FREE $0.001, BRONZE $0.001, SILVER $0.0009, GOLD $0.0008, PLATINUM $0.0008, DIAMOND $0.0008; video-probed: FREE $0.002, BRONZE $0.002, SILVER $0.0018, GOLD $0.0016, PLATINUM $0.0016, DIAMOND $0.0016; minute-scanned: FREE $0.015, BRONZE $0.015, SILVER $0.0135, GOLD $0.012, PLATINUM $0.012, DIAMOND $0.012.

Checked schedule — only if that record is active

Event	Title	Charged when	FREE / BRONZE	SILVER	GOLD / PLATINUM / DIAMOND
frame-extracted	Frame extracted	One still frame saved.	$0.001	$0.0009	$0.0008
video-probed	Video probed	One video's metadata read.	$0.002	$0.0018	$0.0016
minute-scanned	Minute scanned	One started minute of video decoded by the scene scan (scenes mode only).	$0.015	$0.0135	$0.012

Platform event in the checked schedule: apify-actor-start: FREE $0.00005, BRONZE $0.00005, SILVER $0.00005, GOLD $0.00005, PLATINUM $0.00005, DIAMOND $0.00005.

The checked start at default memory is (1 event, $0.00005, at the default 1,024 MB).

Worked event subtotal, checked schedule at FREE: if 10 frame-extracted events are charged, 10 × $0.001 = $0.01 for that event alone. All other charged events and the platform start event add their listed fees; this subtotal is not a run total. The configured maximum-charge floor is $0.02. Platform usage is included; failed results are uncharged.

Call it from an agent

Through Apify's MCP server (https://mcp.apify.com), tool call-actor:

{"actor": "hermeskd/video-frames", "input": {"urls": ["https://media.w3.org/2010/05/sintel/trailer.mp4"], "mode": "interval", "intervalSec": 10, "maxFrames": 3}, "callOptions": {"maxTotalChargeUsd": 0.05, "timeout": 1800}, "waitSecs": 30}

The call returns the run's status and its defaultDatasetId. Read the records with get-dataset-items:

{"datasetId": "<defaultDatasetId from the call>", "limit": 50}

Each frame in a record carries url, the frame's record in the run's key-value store: fetch it to see the image. As a dedicated tool, add https://mcp.apify.com?tools=hermeskd/video-frames to your MCP client. A short video finishes well inside the 30-second wait, so one call-actor plus one get-dataset-items is the whole exchange. maxTotalChargeUsd caps what the run can charge: a video gets only the frames the remaining budget pays for (charge_limit_capped), and the URLs after it come back as charge_limit_reached records, not charged. In scenes mode the budget must also pay for every minute of the video (a video that states its duration and whose minutes it does not cover is charge_limit_reached, not scanned and not charged).

Output fields

One record per input URL; the frames themselves are image files in the run's default key-value store.

Field	Meaning
url	The input URL.
ok	true when the video was read; false with error.
metadata	{durationSec, width, height, fps, videoCodec, audioCodec, hasAudio, bitrate, sizeBytes}: duration in seconds; the picture size as displayed (rotation and non-square pixels applied); average frames per second; ffmpeg's codec names (h264, hevc, vp9, av1, aac, opus, …); overall bits per second; the file's size in bytes. A value the file does not state is null; audioCodec is null without audio.
frames	Each frame as {timestampSec, key, url, width, height}, in time order: the second it was taken at (the first frame at or after the time asked for), its record key in the run's default key-value store (frame-<input index>-<frame index>.<ext>), its API record URL, and its size in pixels.
minutesScanned	scenes mode only: started minutes of the video the scene pass decoded, each charged as minute-scanned — the whole video, or as far as the pass read when it stopped at maxFrames or at the charge limit. Absent in interval and timestamps mode.
warnings	Present when fewer frames came back than the input asked for: frames_capped (more frames were chosen than maxFrames; the earliest kept), timestamps_beyond_end (some timestamps are past the video's last frame and gave no frame), charge_limit_capped (the run's maximum total charge paid for fewer frames, or in scenes mode for fewer minutes of a video that states no duration), frames_unreadable (some planned frames could not be decoded).
error	{code, message} when ok is false.

A video whose metadata was read but that yields no frame — every timestamp asked for is past its end — is ok: true with frames: [] and timestamps_beyond_end, and only video-probed is charged: the video was read.

Limits and run time

• 1–20 URLs per run, read one after another; files up to 500 MB; at most 200 frames per video and 200 timestamps.
• Video files download at 2 MB/s or faster: each download has a budget of 30 seconds plus 1 second per 2 MB of the file's declared size (of 500 MB when the server declares none), and stops when no byte arrives for 30 seconds; a slower file is download_failed. At most 2 requests a second go to one host.
• Frames in interval and timestamps mode are found by seeking, so their cost does not grow with the video's length: each frame decodes from the keyframe before it. On a container without an index (MPEG-TS, some AVI and MPEG files) a seek that lands off target is redone by decoding forward from 30 seconds before the time asked for, or from the start. A frame is the first one at or after the time asked for.
• scenes decodes the whole video once (the frames no other frame depends on are skipped to halve the work); a scene change is a frame whose difference from the one before scores above 0.3 on ffmpeg's scene-change scale, and the first frame is always included. The pass stops at the maxFramesth frame. Its run time grows with the video's length and resolution — measured on one core of the build host (Apify's cores may be slower), per minute of H.264 film at 24 fps: about 0.3 seconds of CPU at 320×180, 4 at 1280×720, 7 at 1920×1080 and 25 at 3840×2160; so at the default memory (a quarter of a core) a 10-minute 4K video takes about 17 minutes — give long or 4K videos 4,096 MB (one core) or more. The price per minute scanned is the same at every resolution.
• GitHub release links (github.com/…/releases/download/…) are refused with robots_disallowed: github.com's robots.txt disallows every crawler not named in it, HermesBot included. Use the file's raw.githubusercontent.com address or your own storage.
• Typical run time: measured on the build host, the minimal input's work — the probe and three frames of a 52-second 854×480 video — is about half a second of CPU on one thread, plus the download; at the default memory (1,024 MB, a quarter of a CPU core) that is a few seconds. The default run timeout is 1,800 seconds.

Errors

Errors are records with ok: false and error.code; none is charged. Frames already written to the key-value store for a video that then failed stay there, uncharged.

error.code	Meaning
download_failed	The URL did not return the file (status or network error), or the download was slower than its budget.
unsupported_media	Not a decodable video: no video stream (an audio file or a still image), a damaged or truncated file, a playlist or a format outside the supported containers.
too_large	The file is over 500 MB.
robots_disallowed	robots.txt forbids fetching the URL.
blocked_host	The host is on the deny-list (video platforms among them), or resolves to a private or local address.
timeout	The video did not finish within the run's time budget.
internal_error	Unexpected failure; the message carries the class.
charge_limit_reached	The run reached its maximum total charge before this URL; it was not processed.
invalid_input	The run input passed the input schema but cannot be used (for example timestamps mode without timestamps); the message names the field. One record per input given, or one with url: null when none was given; nothing is processed.

The run fails only when every input failed with an Actor-side code (internal_error, timeout), so a broken Actor is visible. Every other run succeeds — including one where nothing was read because of the caller's own inputs (bad URL, robots, deny-list, not a video, invalid input, the charge limit), or where those and Actor-side failures are mixed.

Sources and terms

The source is the caller's video. Process only videos you have the right to process. Fetching follows the Hermes fetch policy: robots.txt is obeyed for the user-agent HermesBot (and *), and a disallowed URL is refused without a request; platforms whose terms forbid automated access — video platforms such as YouTube and TikTok among them — and people-search sites are on a deny-list and refused without a request; private and local addresses are refused, after DNS and on every redirect; the user-agent is HermesBot/1.0 (+https://apify.com/hermeskd); no login, cookies, credentials, CAPTCHA solving, evasion or proxies are used. The file is read only as a single video file: playlists and manifests (HLS, DASH, concat lists), which would make the reader fetch further files, are refused. Frames are returned to the caller as they are in the video; no person or face is identified.

Not affiliated

This Actor is not affiliated with YouTube, TikTok, the FFmpeg project, the Blender Foundation (whose Sintel trailer is the example input) or Intel (whose sample videos are the example tasks' inputs). FFmpeg and Pillow are used under their open-source licences; the example videos are under Creative Commons licences (Sintel CC BY 3.0, Intel's sample videos CC BY 4.0).

Related Hermes Actors

• AI Crawler Checker: Which AI Bots robots.txt Allows per URL — check declared robots.txt permissions for six AI crawlers at URL paths.
• Article Extractor — News & Blog Text, Date and Markdown by URL — an article's clean text, title and publish date, without the rest of the page.
• ATS Job Search — Jobs Confirmed Open on Company Career Boards — search open jobs in the Hermes directory of Greenhouse and Lever boards, each confirmed live.
• Speech to Text — Transcribe Audio & Video URLs, Speaker Labels — speech to text with SRT and VTT subtitles.
• Video Converter — MP4 to MP3, Trim, GIF and Audio Extraction — audio and video conversion: MP4 to MP3, trim, GIF.
• Broken Links Checker — Links, Assets, Redirects and Their Pages — broken links, 404s and redirects on a site.
• ATS Detector — Company Hiring System & Job Board Lookup — which hiring system and job board a company uses.
• SEC EDGAR Filings — Recent Company Forms, Dates and XBRL Flags — Read recent company financial filing metadata from the official SEC JSON API
• DOI Lookup — Crossref Titles, Venues, Dates and Citation Counts — crossref doi metadata.
• CVE Vulnerability Lookup — NVD CVSS Scores and Exploited Flags — look up NVD CVE dates, status, numeric CVSS scores and severity.
• Merge JSON Datasets — Deduplicate Rows, Export JSON and CSV — json dataset cleaner.
• DNS Lookup — Records, SPF Lookup Counts, DKIM & DMARC by Domain — DNS records and SPF, DKIM and DMARC checks.
• DOCX to Markdown — Word, Excel, PowerPoint and EPUB Converter — Word, Excel, PowerPoint and other office files to Markdown.
• Domain Availability Checker — Bulk RDAP Status and Registrar — whether domain names are available, from registry RDAP.
• USGS Earthquake Lookup — Event Magnitude, Depth, Coordinates — Read numeric USGS earthquake metadata for known event identifiers.
• Currency Exchange Rates — ECB Daily Euro Rates and Cross Pairs — Read latest ECB daily currency reference rates and calculated cross pairs.
• Bulk File Downloader — Save URL Lists to Storage With SHA-256 — files and images from URLs, saved with a public link each.
• GitHub Repo Stats — Stars, Forks, Subscribers and Open Issues — Read numeric metrics for known public GitHub repositories.
• Greenhouse Jobs — Live Openings, Offices and Apply Links — every open job on a company's Greenhouse board.
• Hacker News Story Metrics — Scores, Comment Counts, Timestamps — read numeric Hacker News story scores, timestamps and comment counts by ID.
• HTTP GET Request — Bulk Response Bodies, Status and SHA-256 — public http get.
• Security Headers Checker — HSTS, CSP, Framing, Nosniff by URL — Check seven declared HTTP security header families without returning raw values.
• Image Background Remover — U2NetP Cutouts for JPEG, PNG, WebP — Remove image backgrounds with the small U2NetP model and return transparent PNG pixels as base64
• Image Converter — JPEG, PNG and WebP With Resize and Quality — image format converter.
• Image Metadata Remover — EXIF and GPS Scrub, Pixels Verified — GPS location, camera serial numbers and other private metadata removed from photos, losslessly.
• Image to Text OCR — Text With Word Positions and Confidence — OCR: the text in images.
• Image Upscaler — Real-ESRGAN 2x/4x for Photos and Graphics — image upscaling 2x or 4x, and photo restoration.
• Lever Jobs Scraper — Job Board Postings With Salary, US & EU — every published job on a company's Lever site, global or EU.
• Lighthouse Audit — Lab Web Vitals and Scores, Mobile & Desktop — Lighthouse scores and Core Web Vitals.
• npm Package Lookup — Latest Version, License, Dependency Count — read latest npm package versions, license tokens and dependency counts.
• Website Change Monitor — Page Text Diffs Against Your Snapshots — what changed on a page since the last check.
• PDF to Markdown — PDF Parser & Text Extractor With OCR — PDF to Markdown and text, with OCR for scanned pages.
• Public Holidays Calendar — Holiday Dates for Five Countries — build offline public-holiday calendars for five countries and bounded years.
• Remote Jobs Search — Remote OK Jobs by Keyword, Tag and Salary — current remote jobs from Remote OK, with salary and listing links.
• Research Paper Search — OpenAlex Papers, DOIs, Citation Counts — Search OpenAlex for work-level paper metadata without authors, affiliations, abstracts or full text
• RSS Feed Reader — Atom and JSON Feed Parser With Enclosures — every item of an RSS, Atom or JSON feed.
• SEO Audit — On-Page Score, Meta Tags, Schema & Fix Guidance — an on-page SEO audit: meta tags, schema, headings and links.
• Sitemap Extractor — Unique URLs From XML, Gzip & Index Sitemaps — the URLs in a site's sitemaps.
• Text to Speech — Offline English, German, Spanish WAV Voices — Convert short nonpersonal texts to offline formant WAV speech for agents
• Time Zone Converter API — Convert one offset-qualified instant to named IANA time zones using pinned data.
• URL to Markdown — Clean Text for LLM & RAG, With Selectors — a public job page as clean Markdown where the site allows it (deny-listed job sites are refused).
• Website Color Palette — CSS Colors With Alpha and Usage Counts — Extract declared website CSS color literals and counts from public HTML and bounded linked stylesheets
• Favicon Extractor — Icons, Touch Icons, Manifests, Theme Color — declared website icons, theme colors and manifest links.
• Website Screenshot — Full Pages, Elements, Dark Mode & PDF — screenshots and PDF prints of web pages.
• Tech Stack Detector — Website Technologies With Match Evidence — the technologies a website runs, detected live.
• Website Crawler to Markdown — Same-Site Pages for LLM and RAG — bounded whole-site Markdown with robots and crawl-delay enforced

Changelog

• 1.0 (2026-10-26) — store listing rewritten for the people and agents searching for this job: title, description, search-engine title and description, categories, and the README in the order a searcher reads it (what it does, a real result, how to use it, prices, the agent call).
• 1.0 (2026-10-16) — first release: video metadata and still frames by interval, scene change or timestamp, as JPEG, PNG or WebP in the run's key-value store; scene mode charged per minute scanned as well as per frame.