Whether this is for you
Skip it if you store bytes and play them back untouched. A file that is only ever uploaded and streamed does not need inspecting, and we would rather say so than sell you a check you have no use for. The moment you generate a thumbnail, transcode for streaming, run analysis, or let users trim — you have started measuring the video rather than moving it. Measuring footage you have not inspected is where the surprises come from, and they surface at the end of the run rather than the start.The arithmetic
A classify-and-transcribe pipeline costs 10 credits for one video, and running every capability at the premium tier costs 19. Check Readiness costs 1. So the check pays for itself whenever it catches a bad clip more than once in every ten. In practice the rate is far higher, because footage arriving from phones, third parties and user uploads is exactly the footage most likely to carry a defect — and the clips that fail are, by definition, the ones that would have burned the full run before failing. It also answers in the same request. Every other capability hands you a job to poll, which is right for work measured in minutes and wrong for a decision you need before you start: a verdict you have to wait for arrives after the moment you needed it.Three verdicts
The line between
fix_first and reject is recoverability, not severity. Variable frame rate can be transcoded away, so it is a fix_first. Frames that were never captured cannot be added, so 12fps footage is a reject for motion analysis rather than being sent to a transcode that cannot help.
A fix is attached to every reason that has one and to no reason that does not, so “is there a fix” is answerable without reading the prose. An instruction we know cannot work is worse than no instruction.
What to do with fix_first
The fix is machine-readable, so you can execute it yourself:
fix_first, the response carries a fix_quote — what having us do it would cost — so the choice comes with a number attached rather than requiring one to be worked out.
The same clip, four purposes
This is the part that surprises people: readiness is not a quality score. The same file is fit for one job and unfit for another, so there is no single answer to return. Take one variable-frame-rate clip from a phone, shot at 24fps:
Nothing about the file changes between those four calls. Only the question does.
The
reject there comes from the frame rate being too low, not from the VFR.
Variable frame rate is recoverable — a transcode conforms it — so on its own it
is a fix_first even for motion analysis, where it is rated a blocker. Shoot
the same VFR clip at 60fps and motion analysis returns fix_first with a
transcode instruction. That is the fix_first/reject line doing its job:
severity says how much it matters, recoverability decides which verdict you get.Picking a context
nle_editing— cutting in Premiere Pro, DaVinci Resolve or Final Cut Pro. Cares about frame-rate stability and decode cost.motion_analysis— tracking, optical flow, pose estimation. The strictest context, because these pipelines integrate over the timebase and a wrong one is invisible rather than obvious.social_playback— delivery to a feed or any web playback target. Cares about codec compatibility and orientation; tolerant of everything that only matters to an editor.archival— long-term storage. Rejects almost nothing, because an archive’s job is to keep the original. Instead it records what is notable: variable frame rate, an unusual codec, missing provenance.
nle_editing and you get the current rules; ask for nle_editing@v1 and you get those rules permanently. The response always reports which ran.
Each context declares its own thresholds, and you can override them per call — {"min_fps": 24} to accept cinema frame rates for motion analysis, {"allowed_aspect_ratios": ["9:16"]} for a vertical-only feed. An override naming a threshold the context does not define is rejected rather than ignored, so a typo surfaces instead of silently doing nothing.
A note on vertical video
Phones record vertical footage as a landscape frame plus a rotation flag, so a 9:16 clip is commonly stored as 1920x1080. Anything reading width and height directly concludes the clip is landscape and is wrong about the one property a feed cares about most. Two things follow. Ask forinclude_data: ["orientation"] rather than ["resolution"] — it reports the aspect_ratio and the dimensions a viewer actually sees. And expect rotation_metadata in a motion_analysis verdict: frame-extraction pipelines routinely decode without applying the flag, and a model handed a sideways frame returns a confident wrong answer rather than an error. It is a fix_first, and baking the rotation into the pixels is one of the fixes we execute.
Where to go next
- Check Readiness — full parameter and response reference
- Fix Video — having us execute the fix, and what verification means
- Capabilities — what else you can ask about a video
- Get Job Status — for the rare video too high-bitrate to assess inline