Why does a higher detail level not return a bigger image?

Because models downscale anything past 1568 px on the long edge, so a larger sheet costs more tokens and reads no better. Looking closer therefore has to mean fewer frames on the same-sized sheet — at motion, two frames fill a sheet that holds thirty at standard, so each one is fifteen times the area.

What frame rate does motion actually use?

30 frames per second, which puts consecutive frames 33 milliseconds apart. That is the interval at which easing curves, dropped frames and one-frame inserts become visible; at 5 fps they are simply absent from the sheet.

Why are the high levels limited to short windows?

A level's cost is frames per second of video, so motion across a minute would be 1,800 frames and 900 sheets. The caps — 30 seconds at detail, 10 at fine, 3 at motion — keep an expensive level from being asked an inexpensive question. An over-long request answers with the call that would work rather than with a refusal.

Which level should I use by default?

None — leave detail unset and auto picks from the window. It chooses standard for anything under three minutes and overview above that, so a first call always covers the whole video.

Detail levels

Six levels decide how closely Playhead looks, from 0.5 fps across an hour down to 30 fps with consecutive frames 33 milliseconds apart. Looking closer means fewer frames per sheet, never a larger image — models downscale anything past 1568 px on the long edge, so a bigger sheet costs more and reads no better.

Last updated 6 August 2026

The six levels

Grid sizes below are the landscape values. Vertical video uses a taller grid with the same frame count, so a 9:16 sheet is not a wasted one.

Detail levels, their frame rates, grids and window limits
Level	Rate	Frames per sheet	Max window	Answers
`overview`	0.5–2 fps	30 frames	no limit	What is this video, start to end
`standard`	5 fps	30 frames	no limit	What happens when — cuts, overlays, entrances
`detail`	5 fps	6 frames	30 s	Objects and text blocks, tiles four times larger
`fine`	10 fps	2 frames	10 s	Type, logos, subtle transitions
`motion`	30 fps	2 frames	3 s	Animation, easing, dropped frames
`single`	one frame	1 frame	a moment	Reading text at full resolution

The live version of this table, with prices and grid geometry, is GET /v1/detail-levels — it comes out of the same objects the engine enforces, so a client reading it cannot drift from what the server accepts.

Why looking closer means fewer frames, not a bigger picture

This is the piece of arithmetic that decides what this product costs, and it is the one most homegrown pipelines get backwards.

Every model that reads an image downscales it past a ceiling — 1568 px on the long edge is the practical one. Send a 4K frame and it is resized before anything looks at it, so the extra pixels cost tokens on the way in and contribute nothing on the way out.

So a sheet is always about the same size, and the only thing a level changes is how many frames are on it. Thirty frames at standard gives each one a thirtieth of the sheet. Two frames at motion gives each one half. That is a fifteenfold increase in the area of every frame, at the same token cost per sheet.

Window caps, and what happens when you exceed one

An over-long request does not fail with a complaint. It answers with the call that would have worked.

detail is capped at 30 seconds, fine at 10, and motion at 3. overview and standard have no cap at all — a first pass always covers the whole video.

Asking for five seconds at motionjson

{
  "error": {
    "type": "window_too_long_for_detail",
    "message": "motion is limited to 3s windows; you asked for 5s.",
    "suggestion": { "start": 0, "end": 3, "detail": "motion" },
    "max_window_seconds": 3
  }
}

The suggestion object is arguments, not prose — spread it back into the request and the retry works. See Errors.

Choosing one

The honest default is not to choose. Leave the parameter unset unless the question is specific.

Which level answers which question
The question	Level
What is this video about, start to end?	`overview`
What happens when — cuts, entrances, overlays appearing?	`standard`
What objects are in this shot, and what does that text block say?	`detail`
Is that a serif? Did the logo change between these two moments?	`fine`
How does this animation ease? Are frames being dropped?	`motion`
What exactly does that caption say?	`single`

Escalating from a survey to a close lookts

// First pass: the whole video, level chosen automatically.
const survey = await playhead.watch({ url });

// Something happens at the first cut. Look at three seconds of it properly.
const cut = survey.technical?.scene_cuts?.[0] ?? 0;
const close = await playhead.watch({
  url,
  detail: "motion",
  start: Math.max(0, cut - 1),
  end: Math.max(0, cut - 1) + 3,
});

Questions

Why does a higher detail level not return a bigger image?: Because models downscale anything past 1568 px on the long edge, so a larger sheet costs more tokens and reads no better. Looking closer therefore has to mean fewer frames on the same-sized sheet — at motion, two frames fill a sheet that holds thirty at standard, so each one is fifteen times the area.
What frame rate does motion actually use?: 30 frames per second, which puts consecutive frames 33 milliseconds apart. That is the interval at which easing curves, dropped frames and one-frame inserts become visible; at 5 fps they are simply absent from the sheet.
Why are the high levels limited to short windows?: A level's cost is frames per second of video, so motion across a minute would be 1,800 frames and 900 sheets. The caps — 30 seconds at detail, 10 at fine, 3 at motion — keep an expensive level from being asked an inexpensive question. An over-long request answers with the call that would work rather than with a refusal.
Which level should I use by default?: None — leave detail unset and auto picks from the window. It chooses standard for anything under three minutes and overview above that, so a first call always covers the whole video.