extract_frames
Queue an asynchronous frame extraction - the tool to reach for when you need to SEE a video: fetches sourceUrl (or, with upload: true, waits for you to PUT the bytes to the returned uploadUrl) and extracts still frames as jpeg, webp or png. mode is REQUIRED and picks the sampling (all, every_nth, interval, keyframes, evenly_spaced, timestamps); there is no default because every candidate implies a rate you did not ask for. A finished job's resultUrl is a JSON MANIFEST: source display dimensions, fps, rotation, an echo of your parameters, frame_count, and one entry per frame with index, pts_time (seconds in the source) and its own download url on this gateway - fetch the manifest, then the frames you want. Need just ONE frame at a moment - a thumbnail, poster frame or screenshot at a given second? Use mode "timestamps" with a single value, e.g. timestamps=[5], format=jpeg; the result is still a one-entry manifest pointing at that image (if you would rather have the image bytes returned directly instead of via a manifest, tell us with leave_feedback - demand decides whether we add it). Up to 1000 frames per job; "all"/"interval" on a long source can exceed that and fail fast, so prefer interval, evenly_spaced or timestamps. Unreadable input, audio-only files and still images FAIL here (probe_media diagnoses those). Download within 24 hours. Paid: $0.01 USDC via x402 (base mainnet), or a frames-kind retryVoucher.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | every_nth only: keep every Nth DECODED frame (a frame index, not a time). | |
| fps | No | interval only: frames per second, may be below 1 (0.5 = one frame every two seconds). | |
| mode | Yes | How to pick frames (required): "all" every frame; "every_nth" every Nth decoded frame (needs n); "interval" a fixed rate in seconds (needs fps, may be below 1); "keyframes" keyframes only, cheap on long sources; "evenly_spaced" count samples across the window (needs count); "timestamps" one frame per given second (needs timestamps). | |
| count | No | evenly_spaced only: how many frames to spread across the window. | |
| format | No | Image format of each frame, default jpeg (small and accepted by every vision API). png is lossless. | |
| upload | No | Set true to upload the bytes yourself instead of giving a sourceUrl (exactly one of the two). The paid result then returns status awaiting_upload plus uploadUrl and uploadExpiresAt: HTTP PUT the raw bytes to uploadUrl before the deadline (201 -> queued). You are charged at acceptance; an abandoned upload window errors with no refund, while a pipeline failure after your upload earns a retryVoucher. | |
| endTime | No | Window end in seconds (0 or omitted = to the end); must exceed startTime. | |
| quality | No | Encoder quality for jpeg/webp, default 85; ignored for png. | |
| maxFrames | No | Ceiling on frames produced, default and hard limit 1000. A request whose sampling would exceed it fails before any decoding. | |
| sourceUrl | No | https URL of the input media (<= 100 MiB). Fetched from datacenter IP ranges - prefer a presigned URL from storage you control; no IP literals, no localhost/.internal/.local. Provide EXACTLY ONE of sourceUrl or upload. | |
| startTime | No | Window start in seconds (default 0). | |
| timestamps | No | timestamps only: seconds into the source, one accurate frame each. Sorted for you. | |
| retryVoucher | No | Retry-voucher credential (`uuid.hmac`) from a failed paid job's status - pays for this call instead of x402. Single use, kind-matched. | |
| maxOutputWidth | No | Fit box width applied to the source's DISPLAY dimensions: aspect preserved, never upscaled, oriented to the input. 0 = no limit on this axis. | |
| maxOutputHeight | No | Fit box height, same rules as maxOutputWidth. |