Video Scene Detection, Keyframe Extractor: extract scene frames
Pricing
from $20.00 / 1,000 minute of video processeds
Extract frames from a video file, one per scene, with scene change detection: scene timestamps, JPEG keyframes (40 by default, 100 max) and an ffprobe summary as JSON. No ffmpeg to install, no extra API key. $0.01 a run plus $0.02 a video minute; failed videos are not charged.
Video URL
url
Optional
The URL as supplied, either from videoUrls or read out of the chained dataset.
Platform
platform
Optional
Platform inferred from the URL host. 'other' covers direct CDN links that carry no platform in the hostname.
Video ID
videoId
Optional
Stable 16-character identifier derived from a hash of the URL. Used to name the keyframe keys, so it is safe as a storage key regardless of what the URL contains.
Resolved via
resolvedVia
Optional
How the media URL was obtained. 'direct' means you supplied a media file URL; 'ytdlp' means a page URL had to be resolved first.
Status
status
Optional
Whether this video produced a scene split. Only 'ok' records are charged. 'failed' carries the reason in 'error'. 'skipped' means the run's maximum charge could not cover this video; nothing was charged for it.
Error
error
Optional
Why this video could not be processed, and what to do about it. Null on success. Distinguishes a deleted video, a restricted one, a platform blocking the request, an expired CDN link, an oversized or overlong file, and a spend limit that could not cover it.
Duration (seconds)
durationSeconds
Optional
Measured by ffprobe, from the container header or the video stream. Null when the file states neither, which some MPEG-TS and fragmented MP4 files do not.
Width (px)
width
Optional
Source video width, measured by ffprobe. Not the keyframe width; stills are downscaled to keyframeLongEdge.
Height (px)
height
Optional
Source video height, measured by ffprobe. Not the keyframe height; stills are downscaled to keyframeLongEdge.
Frame rate
fps
Optional
Frames per second, parsed from ffprobe's rational rate. 29.97 content reports 29.97, not 30. Null when the file does not state a rate.
Video codec
videoCodec
Optional
Codec of the video stream, as ffprobe names it.
Audio codec
audioCodec
Optional
Codec of the first audio stream, as ffprobe names it. Null when the file has no audio.
Has audio
hasAudio
Optional
Whether the file carries an audio stream at all. Checked by looking for one, not assumed from the container type.
Bitrate (kbps)
bitrateKbps
Optional
Overall container bitrate. Falls back to the video stream's own bitrate when the container does not state one, which undercounts by the audio track.
File size (bytes)
sizeBytes
Optional
Size of the downloaded file as ffprobe reports it. Capped at 200 MB; anything larger fails with a specific error rather than being truncated.
Container format
containerFormat
Optional
Container as ffprobe names it. Often a comma-separated list of compatible names for MP4-family files.
Scene count
sceneCount
Optional
How many scenes the video was cut into. Always at least 1: a single-shot video is one scene spanning the whole file. Raise sceneThreshold for fewer, lower it for more.
Cut cadence (seconds)
cutCadenceSeconds
Optional
Median scene length, a measured proxy for editing rhythm. The detector fires on overlays and kinetic text as well as hard cuts, so read it as a rhythm indicator rather than an exact shot count.
Keyframes saved
keyframeCount
Optional
How many stills were written to the key-value store. Lower than sceneCount when maxKeyframes capped it, when includeKeyframes was off, or when a frame could not be decoded.
Keyframes cut short
keyframesTruncated
Optional
True when the per-video time budget stopped keyframe extraction early. The scene list and the technical report are still complete; only some stills are missing.
Scenes
scenes
Optional
Every scene boundary, in order, covering the whole video with no gaps. Each entry carries index, startSeconds, endSeconds, durationSeconds, and keyframeKey (the key-value store key of that scene's still, or null when it did not get one). The key lives inside the scene so you never have to join it by position.
[ { "index": 0, "startSeconds": 0, "endSeconds": 3.44, "durationSeconds": 3.44, "keyframeKey": "scene-9f2a1c7d4e6b8a03-0000.jpg" }]Keyframe keys
keyframeKeys
Optional
Flat list of every stored keyframe key, derived from the scene list so the two can never disagree. Convenience for callers that just want the images; the scenes array is what carries the mapping.
[ "scene-9f2a1c7d4e6b8a03-0000.jpg", "scene-9f2a1c7d4e6b8a03-0004.jpg"]Processing time (seconds)
processingSeconds
Optional
Wall-clock time this Actor spent on this video, from resolve to the last keyframe. Reported so you can see which inputs are slow and why a run took what it took.
Processed at
processedAt
Optional
UTC timestamp when this record was produced, to the second.