> ## 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.
# Quickstart
> Check a video, fix what is wrong with it, and prove it worked — in 5 minutes
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
Sign up at [fastdrop.io/developers](https://fastdrop.io/developers). Free, no credit card, 100 credits a month. Your key looks like `fd_live_...`.
## 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.
```bash theme={null}
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.
```bash theme={null}
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:
```json theme={null}
{
"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:
```bash theme={null}
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"
}'
```
```json theme={null}
{
"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
```bash theme={null}
curl https://api.fastdrop.io/api/v1/fix/9c2f1e40-5f6d-4a1e-9a2b-3f8c7d1e0b42 \
-H "X-API-Key: fd_live_your_key_here"
```
```json theme={null}
{
"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:
```bash theme={null}
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"
}'
```
```json theme={null}
{ "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](/guides/delivery-modes) 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
```bash cURL theme={null}
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"}'
```
```python Python theme={null}
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"]
```
```javascript JavaScript theme={null}
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:
```bash cURL theme={null}
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"
}'
```
```python Python theme={null}
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"]}')
```
```javascript JavaScript theme={null}
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
Classify up to 50 videos in one request.
Search across transcribed videos by keyword or meaning.
Webhooks, long-poll, and when to use which.
Have results pushed to your server the moment they exist.
Connect AI agents to FastDrop for natural language classification.
See all available analysis capabilities and credit costs.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.