{"uid":"cap_cB-UCmNE8f2ahJ0FC7rF-","slug":"ffpipe-frame-extraction-7c2a4dd0","name":"ffpipe Frame Extraction","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, 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.","url":"https://ffpipe.dev/v1/frames?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","properties":{"n":{"type":"integer","minimum":1,"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."},"fps":{"type":"number","maximum":120,"description":"`interval` only: frames per second, framerate-independent. May be below 1 - `0.5` is one frame every two seconds.","exclusiveMinimum":0},"mode":{"enum":["all","every_nth","interval","keyframes","evenly_spaced","timestamps"],"type":"string","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`."},"count":{"type":"integer","maximum":1000,"minimum":1,"description":"`evenly_spaced` only: how many frames to spread across the window."},"format":{"enum":["jpeg","jpg","webp","png"],"type":"string","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`."},"upload":{"type":"boolean","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`."},"endTime":{"type":"number","minimum":0,"description":"Window end in seconds (0 = to the end). Must be greater than `startTime`; past the end of the media it is clamped."},"quality":{"type":"integer","default":85,"maximum":100,"minimum":1,"description":"Encoder quality for `jpeg`/`webp`; ignored for the lossless `png`."},"maxFrames":{"type":"integer","default":1000,"maximum":1000,"minimum":1,"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."},"sourceUrl":{"type":"string","format":"uri","examples":["https://storage.example.com/clip.mov?signature=abc123"],"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."},"startTime":{"type":"number","minimum":0,"description":"Window start in seconds (0 = from the beginning). Applies to every mode."},"timestamps":{"type":"array","items":{"type":"number","minimum":0},"examples":[[1.5,30,90.25]],"maxItems":1000,"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."},"maxOutputWidth":{"type":"integer","maximum":4096,"minimum":0,"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."},"maxOutputHeight":{"type":"integer","maximum":4096,"minimum":0,"description":"Fit box height. Same rules as `maxOutputWidth`."}}},"responseSchema":{"type":"json","example":{"jobId":"6f1e28d4-3b52-4d0a-9c1f-2ab5cbe2f9c3","status":"queued","statusUrl":"https://ffpipe.example/v1/jobs/6f1e28d4-3b52-4d0a-9c1f-2ab5cbe2f9c3?t=9a1b2c3d4e5f60718293a4b5c6d7e8f9"}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"1.00","reviews":0,"stars":null,"state":"rated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.01/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_4SiCkMNogfcNlnYyu2rPq","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Extracts frames from a video source as images using configurable sampling modes, paid per job in USDC via x402","exampleAgentPrompt":"Extract one frame every 2 seconds from this video https://example.com/myvideo.mp4 and give me the frames as JPEGs — use interval mode at 0.5 fps.","exampleUseCases":[{"title":"Vision model scene analysis","prompt":"I need to analyze what's happening in this security camera footage — can you pull out evenly spaced frames, say 20 of them across the whole clip at https://example.com/footage.mp4, as JPEGs so I can pass them to a vision model?"},{"title":"Video thumbnail generation","prompt":"Grab keyframes from this product demo video at https://mysite.com/demo.mp4 and give them back as WebP images — I want to use them as thumbnail options."},{"title":"Timestamp-specific frame capture","prompt":"I need exactly the frames at seconds 10, 45, and 120 from this interview video at https://cdn.example.com/interview.mp4 — extract those three timestamps as high-quality PNGs."}],"resultDescription":"Returns a JSON object with a jobId, initial status ('queued'), and a statusUrl to poll for job completion and retrieve the extracted frame images once processing finishes.","failureModes":["Exceeds maxFrames limit (1000): job fails fast if the selected mode and source length would produce more than 1000 frames — a retry voucher is issued","Invalid mode/parameter combination: e.g. using 'every_nth' without 'n', 'interval' without 'fps', or 'evenly_spaced' without 'count'","Source URL unreachable or unsupported format: job fails if the video cannot be fetched or decoded","Upload window expiry: if using push intake, letting the uploadUrl expire without uploading is terminal — no refund","Payment failure: x402 payment not completed or insufficient USDC balance blocks the job from being accepted"],"whenToPreferThis":"Use this endpoint when you need to sample or extract still frames from a video in a flexible, programmatically controlled way — especially for AI vision pipelines, thumbnail generation, or frame-level analysis. Prefer interval or evenly_spaced modes for long videos to avoid hitting the 1000-frame cap. This is the right choice over general video conversion when your goal is images from video rather than a transcoded video file.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":1,"lastUsedAt":"2026-09-07T21:21:54.418Z","lastSuccessfullyRanAt":"2026-09-07T21:21:54.418Z","lastHealthCheckAt":"2026-10-13T00:31:42.931Z","isFirstParty":false,"canonicalSlug":"ffpipe-frame-extraction-7c2a4dd0"}