---
title: "Cut a snapshot frame from the event's clip at an operator-picked offset"
method: POST
path: "/events/{event_id}/snapshot-frame"
tags: ["events"]
---

# Cut a snapshot frame from the event's clip at an operator-picked offset

`POST /events/{event_id}/snapshot-frame`

## Request

- Base URL: `https://api.verdun.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.verdun.ai/events/{event_id}/snapshot-frame`
- Auth: HTTP bearer

Extracts one JPEG from the event's clip at `offset_ms` (server-side, ffmpeg), stores it beside the clip under a key derived from (clip key, offset), and returns a presigned preview. Idempotent: the same offset is a cache hit. The operator then sends the text with `attach_snapshot: true` and `snapshot_offset_ms` set to the returned `offset_ms`; the send path re-derives the key and proves the object exists before anything is written or sent. Requires `notify_property_owner` (the only consumer of a picked frame is the text that carries it) and tenant scope exactly like `clip-url` (out of scope is 403). 409 SNAPSHOT_UNAVAILABLE when the event has no clip, its clip key derives no snapshot key (demo/training rows), the clip object is missing, or there is no frame at that offset (past the end of the clip).

## Path parameters

- `event_id` string, required

## Request body

- SnapshotFrameRequest
  - `offset_ms` integer, required: Milliseconds from the start of the event's clip (the fast clip that `clip_url` plays, NOT the extended pre-roll). Rounded to a tenth of a second server-side; the response says which offset was used. Send the same value back as `snapshot_offset_ms` on the text.

## Response `200`

Successful Response

- SnapshotFrameResponse
  - `offset_ms` integer, required: The offset actually used, after rounding to a tenth of a second
  - `url` string, required: Presigned preview of the frame. A bearer: never persist it, never log it. The text sends `snapshot_offset_ms`, never this.
  - `expires_in` integer, required: Seconds until `url` expires

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/verdun/apis/verdun-api.md) - [All operations](https://skmtc.dev/verdun/apis/verdun-api/llms.txt) - [OpenAPI document](https://skmtc.dev/verdun/apis/verdun-api/revisions/35a2a6ebedda?raw)