Video Frame Extractor: Keyframes, Scenes & Thumbnails for AI

This video frame extractor turns a video file URL into a set of image files: keyframes, scene changes, evenly spaced frames, a frame every N seconds, or one thumbnail. Give it direct video links, get a JPG, PNG or WebP image for each frame, with its timestamp, ready for AI vision models, video search, dataset building and thumbnail generation. It runs ffmpeg, so there is no browser or API key to set up.

Rights and sources. This Actor reads direct video files (mp4, webm, mov, mkv...) from a URL or from your own key-value store. It does not download from YouTube, Vimeo, TikTok, Instagram or other streaming sites, and it rejects those page links without charge. Use it only on videos you own or have the right to process.

What can you extract from a video

• Every N seconds: one frame at 0 s, 2 s, 4 s... for a quick storyboard or sampling for AI.
• N evenly spaced frames: 10 frames spread across the whole video, whatever its length.
• Keyframes (I-frames): the frames the encoder stores in full. Fast, and a natural way to sample a video.
• Scene detection: a frame at every cut or scene change, using ffmpeg's scene score with a threshold you control.
• Single thumbnail: the frame at a time you choose, or the most representative frame of the first seconds.
• Output images: JPG, PNG or WebP, optional resize (width and/or height, aspect ratio kept, never upscaled), JPG/WebP quality.
• Contact sheet: one grid image per video with a timecode on every tile. Not charged.
• Base64 for AI pipelines: optional imageBase64 in each row (off by default, size-capped).

How to extract frames from a video

1. Paste one or more direct video URLs (or the keys of video files in a key-value store).
2. Pick a mode and its setting (interval, number of frames, scene threshold or thumbnail time) and a max frames per video.
3. Run it. Each frame is saved to the key-value store and listed in the dataset with its link and timestamp. The run summary (duration, resolution, fps, codec, frames returned per video) is in the SUMMARY record.

Input example

{
  "videoUrls": ["https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"],
  "mode": "everyNSeconds",
  "intervalSeconds": 2,
  "maxFrames": 5,
  "imageFormat": "jpg",
  "width": 1280,
  "contactSheet": true
}

Other modes: "mode": "sceneChanges", "sceneThreshold": 0.3, "mode": "keyframes", "mode": "evenlySpaced", "frameCount": 12, "mode": "thumbnail", "thumbnailTimestamp": 12.5.

Output

One dataset row per frame:

{
  "videoUrl": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
  "videoIndex": 1, "frameIndex": 2, "timestampSec": 2.0, "timecode": "00:00:02.000",
  "frameUrl": "https://api.apify.com/v2/key-value-stores/.../records/v01-frame-0002.jpg",
  "width": 960, "height": 540, "sizeBytes": 26328, "mode": "everyNSeconds",
  "imageFormat": "jpg", "key": "v01-frame-0002.jpg"
}

With a contact sheet the rows also carry contactSheetUrl; with includeBase64 they carry imageBase64. The SUMMARY record in the key-value store lists, for each video, its duration, resolution, fps, codec, container, whether it has audio, how many frames were returned, and any error or note (for example "maxFrames reached", or why a video was rejected).

Scene detection, keyframes and thumbnails: which mode to use

• Scene changes find the moments that look different from the frame before. Lower the threshold (0.1 to 0.2) for soft transitions, raise it (0.4 and up) to catch only hard cuts. If nothing changes, you still get the first frame and a note.
• Keyframes are placed by the encoder (often every 1 to 10 seconds), not by the content. They are fast to find and good for even coverage.
• Every N seconds and evenly spaced give predictable timestamps. timestampSec is the requested time; the image is the frame at that time.
• Thumbnail picks the frame at thumbnailTimestamp, or the most representative frame of the first seconds (thumbnailWindowSeconds, default 10) when you leave the time empty.

Video frame extractor API

Call this Actor from the Apify API, Python, JavaScript, Make, Zapier or n8n and get frame image URLs as JSON. Example with the Apify Python client:

from apify_client import ApifyClient

run = ApifyClient("<APIFY_TOKEN>").actor("data-done-right/video-frame-extractor").call(run_input={
    "videoUrls": ["https://example.com/clip.mp4"], "mode": "sceneChanges", "maxFrames": 20, "includeBase64": True})

Then read the frames from the run's default dataset. Set includeBase64 to send the images straight to a vision model, or pass frameUrl if your model fetches images by URL.

Use it in Claude, ChatGPT and Cursor

Connect Apify's MCP server (mcp.apify.com) and your AI assistant can look inside a video file itself. For example: "extract the scene changes from this mp4 and describe each scene". The only required input is a video URL (videoUrls).

Use cases

• AI and vision pipelines: sample frames for GPT, Claude or Gemini vision, captioning, OCR, moderation or embeddings.
• Thumbnails and previews: poster images, storyboards and contact sheets for a video library or CMS.
• Video search and datasets: build image datasets from your own footage, with a timestamp for every frame.
• Review and QA: check a long recording quickly with one frame per scene or per minute.

How much does it cost

Pay per event: $0.0018 per frame (frame), charged once for each frame image delivered. Example: 100 frames cost about $0.18. Contact sheets, the SUMMARY record, rejected links and failed videos are free. Apify Silver plans get 10% off, Gold and higher 20%. maxFrames caps what one video can cost, and if you set a maximum spend per run the Actor stops cleanly when it is reached and keeps the frames already delivered.

FAQ

How do I extract frames from a video?

Paste a direct video URL, choose a mode (every N seconds, keyframes, scene changes, evenly spaced or thumbnail) and run. You get one image link per frame, with its timestamp, in the dataset.

Can it extract frames from a YouTube video?

No. It does not download from YouTube, Vimeo, TikTok, Instagram or other streaming sites, and those links are rejected with a clear message and no charge. Use a direct link to a video file you have the rights to, or put the file in a key-value store and use videoKeys.

What is the difference between keyframes and scene changes?

Keyframes are chosen by the video encoder at fixed intervals, so they give even coverage. Scene changes are chosen by comparing how different each frame looks from the one before, so they follow the content. Use scene detection when you want one image per shot.

Which video formats work?

MP4, MOV, WebM, MKV, AVI, FLV, MPEG, MPEG-TS and other common files, with any codec ffmpeg can decode. Streaming playlists (HLS .m3u8, DASH .mpd) are not supported.

Are there size limits?

By default a video can be up to 500 MB (up to 2 GB with maxVideoSizeMb) and 120 minutes (maxDurationMinutes). Files are streamed to disk, and each video has a timeout (videoTimeoutSecs). Links to private or internal network addresses are blocked.

How do I send the frames to an AI vision model?

Turn on includeBase64 to get the image bytes in each row (frames above base64MaxKb are skipped, so lower the size with width or the quality), or use frameUrl for models that take image URLs. For public links use a named store (outputStoreName) so the frames stay available after the run.

How long are the frame links kept?

Frames are saved in the run's default key-value store, which expires after your plan's data retention period like other unnamed storages. Set outputStoreName to save them in a named store, which stays until you delete it.

Do I need an API key or login?

No.

Related tools

• All-in-One File Converter: PDF, Office, Images, Audio & Video converts and compresses the videos before you extract frames.
• Transcribe Audio to Text: Files, Podcasts & Video URLs turns the audio of the same video into a transcript.
• PDF to Text & Markdown Converter with Automatic OCR reads text from the frames and documents you extract.