{"slug":"ffpipe-dev-v1-frames-c5825f","title":"Extract still frames from any video as JPEG, WebP or PNG","host":"ffpipe.dev","method":"POST","resource":"https://ffpipe.dev/v1/frames","category":"image","description":"Extract still frames from any video as JPEG, WebP or PNG: sample many for a vision model, or grab one frame at a given timestamp (a thumbnail/poster/screenshot). Modes: every frame, every Nth, a rate in seconds, keyframes, N evenly spaced, or exact timestamps. One frame at 5s: mode=timestamps, times","price_listed":0.01,"price_asked":0.01,"state":"answering","state_label":"Answering","checks_7d":1,"answered_7d":1,"latency_ms_median":25,"reported_calls_30d":2,"reported_payers_30d":2,"networks":["eip155:8453"],"badge":"unverified","paid_checks_7d":0,"paid_ok_7d":0,"example_input":{"body":{"fps":1,"maxOutputHeight":720,"maxOutputWidth":1280,"mode":"interval","sourceUrl":"https://storage.example.com/clip.mov?signature=abc123"},"bodyType":"json","method":"POST","type":"http"},"output_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","properties":{"input":{"additionalProperties":false,"properties":{"body":{"additionalProperties":true,"description":"Provide EXACTLY ONE of sourceUrl (we fetch it) or upload: true (you PUT the bytes to the uploadUrl returned in the 202), plus mode. The parameter each mode needs is stated in mode's own description; every number must be a JSON number, not a string. The result is a manifest listing each frame with its timestamp and its own download URL. Unknown properties are ignored; validation runs before any charge.","oneOf":[{"required":["sourceUrl"]},{"required":["upload"]}],"properties":{"count":{"description":"`evenly_spaced` only: how many frames to spread across the window.","maximum":1000,"minimum":1,"type":"integer"},"endTime":{"description":"Window end in seconds (0 = to the end). Must be greater than `startTime`; past the end of the media it is clamped.","minimum":0,"type":"number"},"format":{"default":"jpeg","description":"Image format of each frame. `jpeg` (default) is small and accepted by every vision API; `png` is lossless; `webp` splits the difference. `jpg` is accepted as a spelling of `jpeg`.","enum":["jpeg","jpg","webp","png"],"type":"string"},"fps":{"description":"`interval` only: frames per second, framerate-independent. May be below 1 - `0.5` is one frame every two seconds.","exclusiveMinimum":0,"maximum":120,"type":"number"},"maxFrames":{"default":1000,"description":"Ceiling on how many frames this job may produce, and also the hard limit: 1000 frames is what one job's flat price covers. A request whose sampling would exceed it fails before any decoding, with the predicted count in the message.","maximum":1000,"minimum":1,"type":"integer"},"maxOutputHeight":{"description":"Fit box height. Same rules as `maxOutputWidth`.","maximum":4096,"minimum":0,"type":"integer"},"maxOutputWidth":{"description":"Fit box width for each frame, applied to the source's DISPLAY dimensions: aspect preserved, never upscaled, oriented to the input (a portrait clip given 1920x1080 yields 1080x1920). 0 = no limit on this axis.","maximum":4096,"minimum":0,"type":"integer"},"mode":{"description":"How to pick frames. Required - there is no default, because every possible one implies a sampling rate you did not ask for. `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` N samples across the window (needs `count`); `timestamps` one frame per given second (needs `timestamps`). Every mode is bounded by `maxFrames` (1000): `all` and `interval` on a long source, and `keyframes` on a dense one, can exceed it - the job then fails fast and, being our own limit rather than your mistake, earns the usual retry voucher. For long inputs prefer `interval`, `evenly_spaced` or `timestamps`.","enum":["all","every_nth","interval","keyframes","evenly_spaced","timestamps"],"type":"string"},"n":{"description":"`every_nth` only: keep every Nth DECODED frame. This is a frame index, not a time - on a variable-frame-rate source the spacing in seconds varies.","minimum":1,"type":"integer"},"quality":{"default":85,"description":"Encoder quality for `jpeg`/`webp`; ignored for the lossless `png`.","maximum":100,"minimum":1,"type":"integer"},"sourceUrl":{"description":"https URL we fetch the input from. Rejected before any charge if it is not https, is an IP literal, or resolves to a localhost/.internal/.local name; redirects are followed (max 3) and every hop is re-checked. We fetch from datacenter IP ranges - hosts that block datacenter egress will fail with `ingest_failed`, so prefer a presigned URL from storage you control. Body size cap: 100 MiB by default, enforced while streaming.","examples":["https://storage.example.com/clip.mov?signature=abc123"],"format":"uri","type":"string"},"startTime":{"description":"Window start in seconds (0 = from the beginning). Applies to every mode.","minimum":0,"type":"number"},"timestamps":{"description":"`timestamps` only: seconds into the source, one accurate frame each. Sorted for you. A timestamp at or past the end of the media fails the job.","examples":[[1.5,30,90.25]],"items":{"minimum":0,"type":"number"},"maxItems":1000,"type":"array"},"upload":{"const":true,"description":"Push intake: instead of a `sourceUrl`, reserve an upload window and PUT the raw bytes (<= 100 MiB, same cap) to the `uploadUrl` in the 202 before `uploadExpiresAt`. You are charged at the 202, before any bytes move: letting the window expire is a terminal `error` with no refund; a pipeline failure after your upload earns a `retryVoucher`.","type":"boolean"}},"required":["mode"]},"bodyType":{"enum":["json","form-data","text"],"type":"string"},"method":{"enum":["POST"],"type":"string"},"type":{"const":"http","type":"string"}},"required":["type","method","bodyType","body"],"type":"object"},"output":{"properties":{"example":{"description":"The 202 acceptance body. Every non-2xx answer is JSON { error: { code, message } } with code one of: invalid_request, invalid_source_url, source_too_large, ingest_failed, pipeline_error, payment_denied, rate_limited, daily_cap_exceeded, not_found, literal_path_template, gone, unknown_job, unauthorized, not_configured, unavailable - and, by the capture rule, a non-2xx response is never charged.","properties":{"fundingSource":{"description":"What paid for this acceptance: `x402` (the on-chain payment you signed), `credits` (your account's balance, when you sent a Bearer token) or `voucher` (a free retry). Stated back to you so a caller holding both a token and a wallet never has to guess which one it just spent.","enum":["x402","credits","voucher"],"type":"string"},"jobId":{"format":"uuid","type":"string"},"status":{"description":"`queued` for pull mode; `awaiting_upload` for upload mode (the job queues when your PUT completes).","enum":["queued","awaiting_upload"],"type":"string"},"statusUrl":{"description":"Free, token-gated status endpoint for this job. Keep it: the token is the only proof of ownership and is not recoverable.","format":"uri","type":"string"},"uploadExpiresAt":{"description":"Upload mode only: deadline for the PUT. Past it the job becomes a terminal `error` with no refund.","format":"date-time","type":"string"},"uploadUrl":{"description":"Upload mode only: PUT the raw bytes here before `uploadExpiresAt`. Keep it - this response is the ONLY place the upload token is handed out (the status route never repeats it), and it is not recoverable.","format":"uri","type":"string"}},"required":["jobId","status","statusUrl"],"type":"object"},"type":{"type":"string"}},"required":["type"],"type":"object"}},"required":["input"],"type":"object"},"history":[{"day":"2026-09-24","reachable":true,"status":402,"valid_402":true,"asked_usdc":0.01,"price_match":true,"latency_ms":25,"error":null}],"description_full":"Extract still frames from any video as JPEG, WebP or PNG: sample many for a vision model, or grab one frame at a given timestamp (a thumbnail/poster/screenshot). Modes: every frame, every Nth, a rate in seconds, keyframes, N evenly spaced, or exact timestamps. One frame at 5s: mode=timestamps, timestamps=[5], format=jpeg. Up to 1000 frames/job; result is a manifest of frames with timestamps and download URLs, kept 24h. USDC over x402; no account; input <=100 MB.","last_updated":"2026-09-22T15:35:00.567Z","schemes":["exact"]}