---
title: "Video Frames"
method: POST
path: "/media/video-frames"
tags: ["media"]
---

# Video Frames

`POST /media/video-frames`

## Request

- Base URL: `https://api.moda.app/v1`
- URL: `https://api.moda.app/v1/media/video-frames`
- Auth: HTTP bearer

Sample still frames out of a video so a model can SEE what was generated (uncharged).

Closes the loop the generate verbs leave open: generate → sample frames → judge them against
the brief → regenerate or accept. Frames come back inline as JPEG data URLs, the way
``POST /v1/canvases/{ref}/screenshot`` returns page captures — nothing is stored in the team's
library and nothing is charged.

Omit ``timestamps_ms`` for an even survey across the clip (first and last frame always
included). Supply it — off the ``duration_ms`` a previous call reported — to look closely at
one moment instead.

Best-effort by contract: a codec Moda cannot read returns ``frames: []`` with a
``no_frames_decoded`` warning. That means "we could not look", NOT "the video is bad" — do not
regenerate on it.

## Headers

- `Moda-Version` '2026-04-12' | '2026-05-01'

## Request body

- VideoFramesRequest
  - `video` string, required: The video to look at: a file_ id from an upload or a generate-video result.
  - `count` integer, nullable: Frames to sample evenly across the clip, first and last always included (default 4). Mutually exclusive with timestamps_ms — supplying both is rejected.
  - `timestamps_ms` integer[], nullable: Exact moments to sample instead of an even survey — read them off the duration_ms a previous call reported. Out-of-range values clamp to the clip rather than failing, and duplicates collapse. Mutually exclusive with count: the list is its own count, so supplying both is rejected rather than silently honouring one.

## Response `200`

Successful Response

- object

## Other responses

- `401`: Authentication required.
- `402`: Insufficient credits for a metered operation.
- `403`: Permission denied for this scope.
- `404`: Resource not found.
- `409`: Conflict (idempotency / resource state).
- `422`: Request validation failed.
- `429`: Rate limit exceeded.
- `500`: Internal error.

## Changes

- **2026-11-03** `9ac6a3abc0f8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/moda/apis/moda-public-api/changes/media/video-frames/post.md)

---

[API](https://skmtc.dev/moda/apis/moda-public-api.md) - [All operations](https://skmtc.dev/moda/apis/moda-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/moda/apis/moda-public-api/revisions/9ac6a3abc0f8?raw)