curl -X POST https://api.fastdrop.io/api/v1/batch/a1b2c3d4-5678-90ab-cdef-1234567890ab/visual-search \
-H "Content-Type: application/json" \
-H "X-API-Key: fd_live_your_key_here" \
-d '{
"query": "outdoor establishing shot with trees",
"max_results": 5
}'
import httpx
response = httpx.post(
"https://api.fastdrop.io/api/v1/batch/a1b2c3d4-.../visual-search",
headers={"X-API-Key": "fd_live_your_key_here"},
json={
"query": "outdoor establishing shot with trees",
"max_results": 5,
},
)
print(response.json())
const response = await fetch(
"https://api.fastdrop.io/api/v1/batch/a1b2c3d4-.../visual-search",
{
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "fd_live_your_key_here",
},
body: JSON.stringify({
query: "outdoor establishing shot with trees",
max_results: 5,
}),
}
);
const data = await response.json();
{
"query": "outdoor establishing shot with trees",
"total_results": 3,
"results": [
{
"video_id": "f8e7d6c5-4321-ba09-fedc-ba0987654321",
"filename": "DJI_0042.MP4",
"role": "B-Roll",
"similarity_score": 0.7234,
"matching_frame_index": 2,
"thumbnail_url": "https://storage.fastdrop.io/thumbs/abc123-t2.jpg",
"duration_seconds": 15.4
},
{
"video_id": "b2c3d4e5-...",
"filename": "GH010099.MP4",
"role": null,
"similarity_score": 0.6891,
"matching_frame_index": 0,
"thumbnail_url": "https://storage.fastdrop.io/thumbs/def456-t1.jpg",
"duration_seconds": 42.1
}
]
}
Batch Processing
Visual Search Batch
Find videos by describing visual content using CLIP-based similarity
POST
/
batch
/
{batch_id}
/
visual-search
curl -X POST https://api.fastdrop.io/api/v1/batch/a1b2c3d4-5678-90ab-cdef-1234567890ab/visual-search \
-H "Content-Type: application/json" \
-H "X-API-Key: fd_live_your_key_here" \
-d '{
"query": "outdoor establishing shot with trees",
"max_results": 5
}'
import httpx
response = httpx.post(
"https://api.fastdrop.io/api/v1/batch/a1b2c3d4-.../visual-search",
headers={"X-API-Key": "fd_live_your_key_here"},
json={
"query": "outdoor establishing shot with trees",
"max_results": 5,
},
)
print(response.json())
const response = await fetch(
"https://api.fastdrop.io/api/v1/batch/a1b2c3d4-.../visual-search",
{
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "fd_live_your_key_here",
},
body: JSON.stringify({
query: "outdoor establishing shot with trees",
max_results: 5,
}),
}
);
const data = await response.json();
{
"query": "outdoor establishing shot with trees",
"total_results": 3,
"results": [
{
"video_id": "f8e7d6c5-4321-ba09-fedc-ba0987654321",
"filename": "DJI_0042.MP4",
"role": "B-Roll",
"similarity_score": 0.7234,
"matching_frame_index": 2,
"thumbnail_url": "https://storage.fastdrop.io/thumbs/abc123-t2.jpg",
"duration_seconds": 15.4
},
{
"video_id": "b2c3d4e5-...",
"filename": "GH010099.MP4",
"role": null,
"similarity_score": 0.6891,
"matching_frame_index": 0,
"thumbnail_url": "https://storage.fastdrop.io/thumbs/def456-t1.jpg",
"duration_seconds": 42.1
}
]
}
Search across keyframe thumbnails in a batch by describing what you’re looking for. Uses CLIP text-to-image similarity to match your description against extracted video frames.
Cost: 0 credits per query
Batches created with
POST /v1/batch are not keyframe-indexed yet, so this
endpoint returns total_results: 0 for them rather than an error. See the
Visual Search Guide before building against it.Visual search is in beta. It works best for broad visual descriptions. For details and example queries, see the Visual Search Guide.
Path parameters
string
required
UUID of the batch to search. Must be completed and have keyframe embeddings — a
batch with none returns an empty result set.
Request body
string
required
Text description of visual content to find (e.g.
"outdoor establishing shot", "person at desk").integer
default:10
Maximum number of results to return (1-50).
curl -X POST https://api.fastdrop.io/api/v1/batch/a1b2c3d4-5678-90ab-cdef-1234567890ab/visual-search \
-H "Content-Type: application/json" \
-H "X-API-Key: fd_live_your_key_here" \
-d '{
"query": "outdoor establishing shot with trees",
"max_results": 5
}'
import httpx
response = httpx.post(
"https://api.fastdrop.io/api/v1/batch/a1b2c3d4-.../visual-search",
headers={"X-API-Key": "fd_live_your_key_here"},
json={
"query": "outdoor establishing shot with trees",
"max_results": 5,
},
)
print(response.json())
const response = await fetch(
"https://api.fastdrop.io/api/v1/batch/a1b2c3d4-.../visual-search",
{
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "fd_live_your_key_here",
},
body: JSON.stringify({
query: "outdoor establishing shot with trees",
max_results: 5,
}),
}
);
const data = await response.json();
{
"query": "outdoor establishing shot with trees",
"total_results": 3,
"results": [
{
"video_id": "f8e7d6c5-4321-ba09-fedc-ba0987654321",
"filename": "DJI_0042.MP4",
"role": "B-Roll",
"similarity_score": 0.7234,
"matching_frame_index": 2,
"thumbnail_url": "https://storage.fastdrop.io/thumbs/abc123-t2.jpg",
"duration_seconds": 15.4
},
{
"video_id": "b2c3d4e5-...",
"filename": "GH010099.MP4",
"role": null,
"similarity_score": 0.6891,
"matching_frame_index": 0,
"thumbnail_url": "https://storage.fastdrop.io/thumbs/def456-t1.jpg",
"duration_seconds": 42.1
}
]
}
Result fields
| Field | Type | Description |
|---|---|---|
video_id | string | UUID of the matched video |
filename | string | Original filename |
role | string | null | Classification role, if classified. Null otherwise. |
similarity_score | float | 0.0 to 1.0 CLIP cosine similarity |
matching_frame_index | int | Index of the best-matching keyframe thumbnail |
thumbnail_url | string | null | URL of the matching thumbnail |
duration_seconds | float | null | Video duration in seconds |
Error responses
| Status | Meaning |
|---|---|
| 404 | Batch not found or not owned by this API key |
| 409 | Batch processing not yet complete |