Quickstart

Three calls, in the order the work actually happens: find out whether the footage is usable, fix it if it is not, and confirm the fix took.

1. Get an API key

2. Check the footage

Ask whether the video suits what you are about to do with it. This answers in the same request — a verdict you have to poll for arrives after the decision was needed. You need a video with something wrong with it, and we host two so you do not have to go looking. Checking and fixing them costs no credits, so this whole page runs before you spend anything.

curl https://api.fastdrop.io/api/v1/samples

No API key needed for that one. Take video_url from the variable-frame-rate entry — a clip captured in bursts, so the gaps between its frames are uneven. It plays fine and drifts against audio the moment anything measures it.

curl -X POST https://api.fastdrop.io/api/v1/readiness \
  -H "Content-Type: application/json" \
  -H "X-API-Key: fd_live_your_key_here" \
  -d '{
    "video_url": "PASTE_THE_SAMPLE_URL",
    "context": "motion_analysis"
  }'

A clip shot on a phone commonly comes back like this:

{
  "verdict": {
    "action": "fix_first",
    "context": "motion_analysis@v1",
    "reasons": [
      {
        "check": "vfr",
        "severity": "blocker",
        "detail": "Variable frame rate: the gaps between frames are uneven, so playback time and frame count disagree.",
        "fix": {
          "operation": "transcode",
          "to": { "frame_rate_mode": "constant", "fps": 30.0 },
          "reason": "Constant frame rate keeps audio and video aligned."
        }
      }
    ],
    "checks_failed": ["vfr"]
  },
  "credits_charged": 1
}

Three verdicts are possible. proceed means nothing found that blocks this use. fix_first means something is wrong and can be fixed — the fix says how. reject means no transformation helps, and carries no fix, because an instruction we know cannot work is worse than no instruction. That distinction is the whole point of checking first: 24fps footage is fine for an edit and unusable for motion tracking, and you would rather know now than after the run.

3. Fix it

fix_first came back, so execute it:

curl -X POST https://api.fastdrop.io/api/v1/fix \
  -H "Content-Type: application/json" \
  -H "X-API-Key: fd_live_your_key_here" \
  -H "Idempotency-Key: my-first-fix-001" \
  -d '{
    "video_url": "PASTE_THE_SAMPLE_URL",
    "context": "motion_analysis"
  }'

{
  "fix_job_id": "9c2f1e40-5f6d-4a1e-9a2b-3f8c7d1e0b42",
  "status": "queued",
  "reason_id": "vfr",
  "quote": { "credits": 2, "resolution_tier": "hd", "billed_minutes": 1 },
  "credits_charged": 2
}

You did not have to pass the fix instruction back to us, and you did not have to call step 2 first — a fix runs the same check itself and does not bill for it twice. Step 2 exists for when you want the verdict without committing to the work. The Idempotency-Key header makes the retry safe. Replay the same request and you get this job back rather than a second charge and a second transcode.

4. Confirm it worked

curl https://api.fastdrop.io/api/v1/fix/9c2f1e40-5f6d-4a1e-9a2b-3f8c7d1e0b42 \
  -H "X-API-Key: fd_live_your_key_here"

{
  "status": "succeeded",
  "terminal": true,
  "result_url": "https://...",
  "verification": {
    "passed": true,
    "checks": [
      { "name": "original_failure_cleared", "passed": true, "detail": "'vfr' no longer fails for motion_analysis@v1." },
      { "name": "duration_preserved", "passed": true, "detail": "20.000s -> 20.033s (delta 0.033s, tolerance 0.033s = one frame)" },
      { "name": "audio_preserved", "passed": true, "detail": "Audio present (aac)." }
    ]
  },
  "credits_charged": 2
}

That verification block is the part worth reading. We re-ran the same check on the file that came back, under the same context, and it now passes. The file is not merely transcoded — the original failure is confirmed gone, and the output still matches the source in duration, audio and orientation. If it had not passed, status would be verification_failed, the report would name the check that failed and what was measured, and credits_charged would be 0.

Failed fixes cost nothing. All three ways one can fail — the transcode failing, never finishing, or finishing without passing verification — are free. Poll until terminal is true.

The verification you just read is real. Sample fixes skip the transcode — their output is pre-baked, which is how they stay free at any volume — but the result is measured and checked exactly like any other, so that report describes the file you can download rather than a canned response.

Classifying footage

Once the footage is usable, classification is the next call. Unlike the readiness check, this returns a job to poll:

curl -X POST https://api.fastdrop.io/api/v1/classify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: fd_live_your_key_here" \
  -d '{
    "video_url": "https://example.com/my-video.mp4",
    "capabilities": ["classify", "thumbnails", "diagnostics"],
    "processing_tier": "basic"
  }'

{ "job_id": "3f7a...", "status": "queued", "credits_charged": 4 }

Then poll GET /api/v1/classify/{job_id}, or have the result pushed to you — see Getting your results for webhooks and long-poll, which are both better than a poll loop.

What’s in the results

Field	Description
`role`	One of: Hook, A-Roll, B-Roll, Screen Recording, VO, Blooper
`role_confidence`	0.0 to 1.0 confidence score
`classification_method`	`heuristic`, `enhanced`, or `premium`
`semantic_label`	Human-readable description of what was detected
`explanation`	Why this role was assigned
`suggested_filename`	Editor-friendly filename based on content
`suggested_folder`	Folder path for organizing footage
`thumbnails`	Array of keyframe thumbnail URLs
`diagnostics`	Video technical metadata

Alternative: Make videos searchable

FastDrop isn’t just for classification. You can transcribe videos and search them by content — useful for interviews, lectures, podcasts, legal recordings, or any video library.

1. Transcribe a video

curl -X POST https://api.fastdrop.io/api/v1/transcribe \
  -H "Content-Type: application/json" \
  -H "X-API-Key: fd_live_your_key_here" \
  -d '{"video_url": "https://example.com/interview.mp4"}'

import httpx

response = httpx.post(
    "https://api.fastdrop.io/api/v1/transcribe",
    headers={"X-API-Key": "fd_live_your_key_here"},
    json={"video_url": "https://example.com/interview.mp4"},
)
job_id = response.json()["job_id"]

const response = await fetch("https://api.fastdrop.io/api/v1/transcribe", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "fd_live_your_key_here",
  },
  body: JSON.stringify({ video_url: "https://example.com/interview.mp4" }),
});
const { job_id } = await response.json();

2. Wait for completion

Same pattern as classification — GET /v1/classify/{job_id}?wait=90. Transcription takes 45s or more, so use a longer wait than you would for classification.

3. Search

Once the batch is complete, search across all transcribed content:

curl -X POST https://api.fastdrop.io/api/v1/batch/BATCH_ID/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: fd_live_your_key_here" \
  -d '{
    "query": "when did they discuss the budget",
    "mode": "semantic"
  }'

response = httpx.post(
    f"https://api.fastdrop.io/api/v1/batch/{batch_id}/search",
    headers={"X-API-Key": "fd_live_your_key_here"},
    json={"query": "when did they discuss the budget", "mode": "semantic"},
)
for result in response.json()["results"]:
    print(f'{result["filename"]} at {result["start_time"]}s: {result["text"]}')

const searchResponse = await fetch(
  `https://api.fastdrop.io/api/v1/batch/${batchId}/search`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": "fd_live_your_key_here",
    },
    body: JSON.stringify({
      query: "when did they discuss the budget",
      mode: "semantic",
    }),
  }
);
const { results } = await searchResponse.json();

Search costs 0 credits per query — you only pay for the initial transcription.

Next steps

Batch Processing

Classify up to 50 videos in one request.

Transcript Search

Search across transcribed videos by keyword or meaning.

Getting your results

Webhooks, long-poll, and when to use which.

Webhooks

Have results pushed to your server the moment they exist.

MCP Setup

Connect AI agents to FastDrop for natural language classification.

All Capabilities

See all available analysis capabilities and credit costs.

Get Started

Understanding video defects

Guides

1. Get an API key

2. Check the footage

3. Fix it

4. Confirm it worked

Classifying footage

What’s in the results

Alternative: Make videos searchable

1. Transcribe a video

2. Wait for completion

3. Search

Next steps

Batch Processing

Transcript Search

Getting your results

Webhooks

MCP Setup

All Capabilities

​1. Get an API key

​2. Check the footage

​3. Fix it

​4. Confirm it worked

​Classifying footage

​What’s in the results

​Alternative: Make videos searchable

​1. Transcribe a video

​2. Wait for completion

​3. Search

​Next steps

Batch Processing

Transcript Search

Getting your results

Webhooks

MCP Setup

All Capabilities

1. Get an API key

2. Check the footage

3. Fix it

4. Confirm it worked

Classifying footage

What’s in the results

Alternative: Make videos searchable

1. Transcribe a video

2. Wait for completion

3. Search

Next steps