Video Frame Extractor (direct video URLs)

Give it links to video files, get still images (JPG or PNG) back from a key-value store, with one dataset row per frame. It is meant for people who build automations in no-code tools (n8n, Make, Zapier-style flows) or AI agents and who need frames from a video but do not want to install or host ffmpeg themselves.

If you already run ffmpeg on your own machine or server, you do not need this Actor.

What it does

• Downloads each video you list (direct http/https links to a video file only).
• Picks frames in one of three ways:
  • interval: one frame every N seconds (at 0, N, 2N, ...)
  • count: N evenly spaced frames (taken from the middle of N equal segments)
  • timestamps: the exact times in seconds you list (times past the end are skipped)
• Saves each frame as JPG or PNG, optionally scaled down to a maximum width.
• Writes one dataset item per frame: source URL, timestamp, public image URL, width, height, byte size.
• A video that fails produces one error item (with an error code and message) and the run continues with the next video. The run itself only fails on invalid input.

What it does not do

• It does not accept YouTube, TikTok, Vimeo, Instagram, Facebook, X/Twitter, Twitch or similar page URLs. Those are rejected with a clear message. Only direct links to video files work (for example https://example.com/media/clip.mp4).
• It does not bypass logins, paywalls, DRM, geo-blocks or any other access control. If a URL needs credentials, it fails.
• It does not read HLS/DASH playlists, local files or other protocols.

Your responsibility

You must have the right to download and process every video you submit, and to use the frames you get. The Actor does not check this for you.

Input

Field	Meaning	Default
videoUrls	Direct video file URLs, up to 100 per run	required
samplingMode	interval, count or timestamps	interval
intervalSeconds	Seconds between frames (interval mode)	10
frameCount	Number of frames (count mode)	5
timestamps	List of seconds (timestamps mode)	[]
outputFormat	jpg or png	jpg
maxWidth	Scale down frames wider than this; 0 keeps the original	0
maxFramesPerVideo	Cap on frames per video (hard limit 200)	30

Example:

{
  "videoUrls": ["https://example.com/media/clip.mp4"],
  "samplingMode": "count",
  "frameCount": 8,
  "outputFormat": "jpg",
  "maxWidth": 1280
}

Output

Frame item:

{
  "type": "frame",
  "sourceUrl": "https://example.com/media/clip.mp4",
  "frameIndex": 0,
  "timestampSeconds": 1.25,
  "key": "video-001_t00001250ms.jpg",
  "publicUrl": "https://api.apify.com/v2/key-value-stores/<storeId>/records/video-001_t00001250ms.jpg",
  "format": "jpg",
  "width": 1280,
  "height": 720,
  "byteSize": 48211,
  "videoDurationSeconds": 20
}

Error item:

{ "type": "error", "sourceUrl": "https://example.com/missing.mp4", "errorCode": "DOWNLOAD_FAILED", "message": "The server responded with HTTP 404." }

Error codes include PLATFORM_URL_NOT_SUPPORTED, INVALID_URL, UNSUPPORTED_PROTOCOL, BLOCKED_ADDRESS, TOO_MANY_REDIRECTS, DOWNLOAD_FAILED, DOWNLOAD_TIMEOUT, FILE_TOO_LARGE, NOT_A_VIDEO_FILE, FFMPEG_FAILED, FFMPEG_TIMEOUT, VIDEO_TOO_LONG, NO_FRAMES, SPEND_LIMIT_REACHED.

Who can open the publicUrl depends on your Apify storage access settings; check them if you share the links outside your account.

Pricing (pay per event)

Prices:

• video-processed: $0.005 per video that delivered at least one frame

• frame-extracted: $0.0015 per delivered frame

• apify-actor-start: a very small Apify start fee of $0.00005, charged for every run

Example: one video with 10 frames costs about $0.005 + 10 x $0.0015 = $0.02. Platform usage is included.

Apart from the start fee, you are charged only for results that were delivered. Failed videos, rejected URLs, and frames that could not be produced are free. If you set a maximum charge per run, the Actor stops cleanly when the next video would not fit: it delivers only the frames it can charge for and lists the remaining videos as SPEND_LIMIT_REACHED items without charging for them.

(The prices are configured in Apify Console, not in this repository; .actor/pay_per_event.json only records the suggestion.)

Limits

Limit	Value
Videos per run	100
Download size per video	500 MB
Video duration	2 hours
Frames per video	30 by default, 200 maximum
Redirects followed	5
Download time per video	5 minutes
ffmpeg time per operation	60 seconds

Requests to private, loopback, link-local and cloud-metadata addresses are blocked, including when a public hostname resolves to one and when a redirect points to one. Only http and https are allowed. ffmpeg is started without a shell and is restricted to local plain media container formats, so a crafted playlist cannot make it read local files or contact other hosts.

FFmpeg licensing

This Actor runs FFmpeg as a separate program, installed from the Alpine package repository when the image is built. The build was checked on 2026-11-04 and is configured with --enable-gpl --enable-version3, so it is licensed under the GPL version 3 or later. See FFmpeg's licensing page.

Development

npm install
npm test        # needs ffmpeg/ffprobe; set FFMPEG_PATH / FFPROBE_PATH if they are not on PATH
npm run build

Tests generate their own video with the local ffmpeg and serve it from a local HTTP server. The test-only way to reach 127.0.0.1 is the VFE_TEST_ALLOW_HOSTS environment variable (exact host:port entries); it cannot be set through Actor input and is ignored on the Apify platform.