curl "https://api.fastdrop.io/api/v1/classify/a1b2c3d4-5678-90ab-cdef-1234567890ab?wait=60" \
-H "X-API-Key: fd_live_your_key_here"
curl https://api.fastdrop.io/api/v1/classify/a1b2c3d4-5678-90ab-cdef-1234567890ab \
-H "X-API-Key: fd_live_your_key_here"
import httpx
data = httpx.get(
f"https://api.fastdrop.io/api/v1/classify/{job_id}",
params={"wait": 60},
headers={"X-API-Key": "fd_live_your_key_here"},
timeout=75, # must exceed `wait`
).json()
{
"job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"status": "completed",
"progress": 100,
"processing_tier": "basic",
"created_at": "2026-03-05T12:00:00Z",
"completed_at": "2026-03-05T12:01:15Z",
"results": {
"role": "A-Roll",
"role_confidence": 0.92,
"classification_method": "heuristic",
"semantic_label": "Interview — talking head with direct eye contact",
"explanation": "Speaker faces camera with consistent framing and sustained speech.",
"suggested_filename": "interview-talking-head-001.mp4",
"suggested_folder": "A-Roll/Interview",
"thumbnails": [
"https://storage.fastdrop.io/thumbs/abc123-t1.jpg",
"https://storage.fastdrop.io/thumbs/abc123-t2.jpg",
"https://storage.fastdrop.io/thumbs/abc123-t3.jpg"
],
"diagnostics": {
"codec": "h264",
"resolution": "1920x1080",
"fps": 30.0,
"is_vfr": false,
"duration_seconds": 47.2,
"health_score": 95,
"container": "mp4"
}
}
}
{
"job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"status": "processing",
"progress": 45,
"processing_tier": "basic",
"created_at": "2026-03-05T12:00:00Z",
"completed_at": null,
"results": null,
"error": null
}
{
"job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"status": "failed",
"progress": 0,
"processing_tier": "basic",
"created_at": "2026-03-05T12:00:00Z",
"completed_at": "2026-03-05T12:00:30Z",
"results": null,
"error": {
"code": "processing_failed",
"message": "Failed to download video: 404 Not Found"
}
}
Classification
Get Job Status
Fetch classification results, optionally waiting for them
GET
/
classify
/
{job_id}
curl "https://api.fastdrop.io/api/v1/classify/a1b2c3d4-5678-90ab-cdef-1234567890ab?wait=60" \
-H "X-API-Key: fd_live_your_key_here"
curl https://api.fastdrop.io/api/v1/classify/a1b2c3d4-5678-90ab-cdef-1234567890ab \
-H "X-API-Key: fd_live_your_key_here"
import httpx
data = httpx.get(
f"https://api.fastdrop.io/api/v1/classify/{job_id}",
params={"wait": 60},
headers={"X-API-Key": "fd_live_your_key_here"},
timeout=75, # must exceed `wait`
).json()
{
"job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"status": "completed",
"progress": 100,
"processing_tier": "basic",
"created_at": "2026-03-05T12:00:00Z",
"completed_at": "2026-03-05T12:01:15Z",
"results": {
"role": "A-Roll",
"role_confidence": 0.92,
"classification_method": "heuristic",
"semantic_label": "Interview — talking head with direct eye contact",
"explanation": "Speaker faces camera with consistent framing and sustained speech.",
"suggested_filename": "interview-talking-head-001.mp4",
"suggested_folder": "A-Roll/Interview",
"thumbnails": [
"https://storage.fastdrop.io/thumbs/abc123-t1.jpg",
"https://storage.fastdrop.io/thumbs/abc123-t2.jpg",
"https://storage.fastdrop.io/thumbs/abc123-t3.jpg"
],
"diagnostics": {
"codec": "h264",
"resolution": "1920x1080",
"fps": 30.0,
"is_vfr": false,
"duration_seconds": 47.2,
"health_score": 95,
"container": "mp4"
}
}
}
{
"job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"status": "processing",
"progress": 45,
"processing_tier": "basic",
"created_at": "2026-03-05T12:00:00Z",
"completed_at": null,
"results": null,
"error": null
}
{
"job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"status": "failed",
"progress": 0,
"processing_tier": "basic",
"created_at": "2026-03-05T12:00:00Z",
"completed_at": "2026-03-05T12:00:30Z",
"results": null,
"error": {
"code": "processing_failed",
"message": "Failed to download video: 404 Not Found"
}
}
Check the status of a classification job. When
status is completed, the results field contains the full classification data.
If your service can receive HTTP callbacks, you do not need this endpoint.
Register a webhook and handle
job.completed — results arrive
the moment they exist and you make no status requests at all.Otherwise pass ?wait=60 below. It returns the finished job in one request
instead of one every few seconds.string
required
The UUID returned by Classify Video.
integer
default:"0"
Seconds to hold the request open waiting for the job to finish.
0 (the default)
returns immediately. Maximum 90.The response is returned as soon as the job reaches a terminal state, or when the
wait elapses — whichever is first. A timed-out wait is not an error: you get
the current state, exactly as wait=0 would return, and can call again.Set your client’s timeout above this value — a 60-second wait with a 30-second
client timeout hangs up on a request that was about to answer.Without
wait, a 30–180 second job checked every 5 seconds costs 6–36 requests.
On the Free tier’s 10 requests/minute that can rate-limit you on a single video.Response (200 OK)
string
Job UUID.
string
Current job status:
queued, downloading, processing, completed, or failed.integer
Percentage complete (0-100).
string
Tier used:
basic, enhanced, or premium.string
ISO 8601 timestamp of job creation.
string
ISO 8601 timestamp of completion.
null if not yet complete.object
Classification results.
null until status is completed.Show Results fields
Show Results fields
string
Assigned role:
Hook, A-Roll, B-Roll, Screen Recording, VO, or Blooper.number
Confidence score from 0.0 to 1.0.
string
Method used:
heuristic, enhanced, or premium.string
Human-readable description of detected content.
string
Why this role was assigned.
string
Editor-friendly filename based on content analysis.
string
Folder path for organizing footage (e.g.,
A-Roll/Interview).string[]
Array of keyframe thumbnail URLs (if
thumbnails capability requested).object
Video technical metadata (if
diagnostics capability requested).
Includes: codec, resolution, fps, is_vfr, duration_seconds, health_score, container.object
Perceptual hash data (if
duplicates capability requested).
Includes: visual_fingerprint.object[]
Clip candidates (if
clips capability requested).
Each includes: start_time, end_time, label, explanation, confidence.object
Error details if
status is failed. Includes code and message.curl "https://api.fastdrop.io/api/v1/classify/a1b2c3d4-5678-90ab-cdef-1234567890ab?wait=60" \
-H "X-API-Key: fd_live_your_key_here"
curl https://api.fastdrop.io/api/v1/classify/a1b2c3d4-5678-90ab-cdef-1234567890ab \
-H "X-API-Key: fd_live_your_key_here"
import httpx
data = httpx.get(
f"https://api.fastdrop.io/api/v1/classify/{job_id}",
params={"wait": 60},
headers={"X-API-Key": "fd_live_your_key_here"},
timeout=75, # must exceed `wait`
).json()
{
"job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"status": "completed",
"progress": 100,
"processing_tier": "basic",
"created_at": "2026-03-05T12:00:00Z",
"completed_at": "2026-03-05T12:01:15Z",
"results": {
"role": "A-Roll",
"role_confidence": 0.92,
"classification_method": "heuristic",
"semantic_label": "Interview — talking head with direct eye contact",
"explanation": "Speaker faces camera with consistent framing and sustained speech.",
"suggested_filename": "interview-talking-head-001.mp4",
"suggested_folder": "A-Roll/Interview",
"thumbnails": [
"https://storage.fastdrop.io/thumbs/abc123-t1.jpg",
"https://storage.fastdrop.io/thumbs/abc123-t2.jpg",
"https://storage.fastdrop.io/thumbs/abc123-t3.jpg"
],
"diagnostics": {
"codec": "h264",
"resolution": "1920x1080",
"fps": 30.0,
"is_vfr": false,
"duration_seconds": 47.2,
"health_score": 95,
"container": "mp4"
}
}
}
{
"job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"status": "processing",
"progress": 45,
"processing_tier": "basic",
"created_at": "2026-03-05T12:00:00Z",
"completed_at": null,
"results": null,
"error": null
}
{
"job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"status": "failed",
"progress": 0,
"processing_tier": "basic",
"created_at": "2026-03-05T12:00:00Z",
"completed_at": "2026-03-05T12:00:30Z",
"results": null,
"error": {
"code": "processing_failed",
"message": "Failed to download video: 404 Not Found"
}
}