# ffpipe Frame Extraction

> ffpipe Frame Extraction is a paid API for AI agents from ffpipe.dev, paid per call via x402, $0.01/call, status unknown (last checked 2026-10-13, last successful call 2026-09-07).

Extracts frames from a video source as images using configurable sampling modes, paid per job in USDC via x402

## Facts

- Endpoint: POST https://ffpipe.dev/v1/frames?utm_source=zero.xyz
- Price: $0.01/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-13
- Last successful call: 2026-09-07
- Success rate: 100% of calls made through Zero
- Activations on Zero: 1
- Tags: x402
- Canonical page: https://www.zero.xyz/c/ffpipe-frame-extraction-7c2a4dd0
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_cB-UCmNE8f2ahJ0FC7rF-

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability ffpipe-frame-extraction-7c2a4dd0 -d '<json body>'
```

Example prompt: 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.

## When to prefer this

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.

## Known failure modes

- 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

## How this service works

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.

## Output

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.

## Request schema (JSON Schema)

```json
{
 "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."
  },
  "quali
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "jobId": "6f1e28d4-3b52-4d0a-9c1f-2ab5cbe2f9c3",
  "status": "queued",
  "statusUrl": "https://ffpipe.example/v1/jobs/6f1e28d4-3b52-4d0a-9c1f-2ab5cbe2f9c3?t=9a1b2c3d4e5f60718293a4b5c6d7e8f9"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/ffpipe-frame-extraction-7c2a4dd0/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from ffpipe.dev](https://www.zero.xyz/host/ffpipe.dev/llms.txt)