> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fastdrop.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Why check footage before you process it

> Spend 1 credit to find out whether the rest are worth spending

Video pipelines fail late. You upload a clip, dispatch a transcode, wait for a transcription run, and discover at the end that the frame rate was variable and the timings are wrong — after paying for all of it.

The failure was knowable at the start. Almost everything that makes footage unusable is visible in the file's header, which costs a fraction of a second to read. What was missing was somewhere to ask.

## 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](/api-reference/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.

<Tip>
  Not sure what your own footage looks like? `GET /api/v1/usage` reports `footage_health` — how many of the videos you have already processed carried a defect, and which ones. It is measured from your account rather than claimed about video in general.
</Tip>

## Three verdicts

| `action` | What it means | What you do |
| - | - | - |
| `proceed` | Nothing found that blocks this use | Go ahead |
| `fix_first` | Something is wrong **and can be fixed** | Fix it yourself, or have us do it |
| `reject` | The footage cannot serve this purpose, and no transformation helps | Do not spend the rest |

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:

```json theme={null}
{
  "operation": "transcode",
  "to": { "frame_rate_mode": "constant", "fps": 30.0 },
  "reason": "Constant frame rate keeps audio and video aligned."
}
```

Or hand it back and let us run it. [POST /fix](/api-reference/fix-video) executes exactly that instruction and then **re-runs this same check on the result** before returning it. A file comes back only if the original failure is confirmed gone and the output still matches the source in duration, audio and orientation. If that cannot be shown, you get the reason and are charged nothing.

Which to choose is a question about your infrastructure rather than your footage. If you already run an encoder, the instruction is enough and you keep the media on your own machines. If you do not, standing one up to conform a frame rate is a lot of work for a problem someone else has already solved.

When the verdict is `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:

| Context | Verdict | Why |
| - | - | - |
| `nle_editing` | `fix_first` | Conformed to a timeline, VFR drifts against the audio. Transcode to constant frame rate first. |
| `motion_analysis` | `reject` | 24fps is below the 30 this context needs, and no transcode adds frames that were never captured. The VFR would have been fixable; the missing frames are not. |
| `social_playback` | `proceed` | Every player resamples on decode. The timebase never has to be exact. |
| `archival` | `proceed`, with a note | An archive keeps what it was given and records what is notable about it. |

Nothing about the file changes between those four calls. Only the question does.

<Note>
  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.
</Note>

```bash theme={null}
curl -X POST https://api.fastdrop.io/api/v1/readiness \
  -H "X-API-Key: fd_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/take_04.mp4",
    "context": "social_playback"
  }'
```

<Tip>
  `GET /api/v1/samples` lists two videos that are broken on purpose. Checking and fixing them costs no credits, so the whole flow can be run before you spend anything.
</Tip>

## 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.

Rules are versioned. Ask for `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 for `include_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](/api-reference/check-readiness) — full parameter and response reference
* [Fix Video](/api-reference/fix-video) — having us execute the fix, and what verification means
* [Capabilities](/guides/capabilities) — what else you can ask about a video
* [Get Job Status](/api-reference/get-job-status) — for the rare video too high-bitrate to assess inline


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.