# Extract frames from a video

Save up to 20 frames of a video as pictures, evenly spaced or one per scene. Made for showing a video to a vision model.

- Endpoint: `POST https://setget.net/v1/tools/video-frames` with JSON `{"input": {...}}` (add `"wait": 30` to hold the reply until the job finishes)
- MCP: `run_tool` with `slug` = `video-frames`
- Page: https://setget.net/tools/video-frames

## Files in, files out

This is a file tool. Its file inputs take file references, not file contents and not web addresses.

- Get a reference by uploading: `curl -T FILE https://setget.net/drop/` prints a line `ref  <id>/f1`. Or `POST https://setget.net/v1/drops` with `{"files":[{"name","size"}]}`, PUT the bytes to the returned `upload.url` with the listed headers, and use the file's `ref`. Over MCP use the `drop` tool. A file under about 700 KB can also be sent in place as a `data:<type>;base64,<content>` URI.
- Uploads are at most 100 MB per file, are readable by anyone with the link, and expire (one hour by default). Programs are refused.
- The tool runs as a job. The reply is `{"tool", "ms", "result", "files", "job"}`: `result` is JSON, and every result file comes back in `files` as `{"name", "size", "content_type", "kind", "url", "ref"}`. Download it from `url`, or pass `ref` as the input of another file tool.
- A job still running when the wait ends answers 202 with `job`. Follow it with `GET https://setget.net/v1/jobs/<id>?wait=30`, or stream progress from `GET https://setget.net/v1/jobs/<id>/events` (over MCP: the `job` tool). A person can watch it at `job.url`.

## Inputs

- `video` (required, file, a file reference such as `DROP_ID/f1`, accepts video): The video to take frames from.
- `count` (optional, integer, default `8`, range 1..20): How many frames to save, at most.
- `mode` (optional, string, one of `even`, `scenes`, default `"even"`): even spreads the frames over the video. scenes saves the first frame of each scene.
- `format` (optional, string, one of `jpg`, `png`, default `"jpg"`): Picture format of the frames. JPG is small; PNG keeps every pixel exactly.
- `width` (optional, integer, range 16..3840): Largest width of each frame in pixels. Left empty, frames keep the size of the video.
- `start` (optional, number, default `0`, range 0..): Only look at the video from this time on, in seconds.
- `end` (optional, number, range 0..): Only look at the video up to this time, in seconds.
- `threshold` (optional, number, default `0.3`, range 0.05..0.95): For scenes mode: how big a change counts as a new scene, from 0.05 (small changes) to 0.95 (only hard cuts).
- `zip` (optional, boolean, default `false`): Return one zip archive holding the frames instead of separate picture files.

## Example 1: Four evenly spaced frames

Upload first. Each placeholder below stands for the reference of one upload: `DROP_ID/f1` = [sample.mp4](https://setget.net/static/samples/sample.mp4).

```json
{"input":{"video":"DROP_ID/f1","count":4},"wait":30}
```

## Example 2: One frame per scene, as small PNGs

Upload first. Each placeholder below stands for the reference of one upload: `DROP_ID/f1` = [sample.mp4](https://setget.net/static/samples/sample.mp4).

```json
{"input":{"video":"DROP_ID/f1","count":6,"mode":"scenes","format":"png","width":160},"wait":30}
```

## Example 3: Five frames in one zip

Upload first. Each placeholder below stands for the reference of one upload: `DROP_ID/f1` = [sample.mp4](https://setget.net/static/samples/sample.mp4).

```json
{"input":{"video":"DROP_ID/f1","count":5,"zip":true},"wait":30}
```

**How do I show a video to an AI model?** Most vision models read pictures, not video. Save 8 to 20 frames here and send them in order together with the times given in the result. For a single picture of the whole video, use video-contact-sheet.

**Which mode should I use?** even is predictable and good for steady footage. scenes follows the cuts, so an edited video gets one frame for each shot. If no cuts are found, evenly spaced frames are saved instead.

**Why did I get fewer frames than I asked for?** A very short video has fewer frames than the count, and scenes mode saves only as many frames as it finds scenes.
