Search
Search your media library using natural language or reference images.
Text search
GET /api/v1/media/search?q=<query>Finds clips by describing what you're looking for in plain English. Uses hybrid search (semantic vectors + keyword matching) to return the most relevant results.
Query parameters
| Param | Type | Default | Description |
|---|---|---|---|
q | string | required | Natural language search query |
n | int | 10 | Max results (max 50) |
creator_id | string | — | Filter to a specific creator's clips |
category_id | string | — | Filter to a specific category |
dedupe | float | — | Cosine similarity ceiling (0–1). 0.9 drops near-duplicate chunks of the same event. |
rerank | bool | false | Re-rank top candidates with a vision model for precision. Falls back to embedding order on failure. |
| rerank_candidates | int | 5 | How many candidates to send to the vision model when rerank=1 (max 10) |
Example
bash
# Basic search
curl -H "Authorization: Bearer findclix_..." \
"https://findclix.com/api/v1/media/search?q=dancing+woman&n=3"
# With deduplication + vision-model precision reranking
curl -H "Authorization: Bearer findclix_..." \
"https://findclix.com/api/v1/media/search?q=dancing+woman&dedupe=0.9&rerank=1"Response
json
{
"success": true,
"data": [
{
"id": "78975543-...",
"filename": "preview_video.mp4",
"score": 0.795,
"start": 0,
"end": 8.7,
"url": "https://assets.findclix.com/...",
"thumbnail": "https://assets.findclix.com/thumb__....jpg",
"type": "video",
"created_at": "2026-07-07T15:09:50.978Z"
}
],
"meta": {
"query": "dancing woman"
}
}TIP
The score field is a cosine similarity score (0–1). Higher means more relevant. Results below 0.2 are filtered out automatically. Pure keyword matches (no vector similarity) report 1.0 — a 100% text match, not a visual similarity.
Interactive reference
Image search
POST /api/v1/media/search/imageFind visually similar clips by uploading a reference image. The image is embedded and compared against your vector index.
Multipart form
bash
curl -X POST -H "Authorization: Bearer findclix_..." \
-F "file=@reference.jpg" \
"https://findclix.com/api/v1/media/search/image"JSON body (URL or base64)
bash
# By URL
curl -X POST -H "Authorization: Bearer findclix_..." \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/photo.jpg"}' \
"https://findclix.com/api/v1/media/search/image?n=5"
# By base64
curl -X POST -H "Authorization: Bearer findclix_..." \
-H "Content-Type: application/json" \
-d '{"data": "/9j/4AAQ...base64string...", "filename": "screenshot.png"}' \
"https://findclix.com/api/v1/media/search/image"Parameters
| Param | Type | Default | Description |
|---|---|---|---|
n | int | 10 | Max results (max 50) |
dedupe | float | — | Cosine similarity ceiling (0–1) |
Response
json
{
"success": true,
"data": [
{
"id": "...",
"score": 0.82,
"start": 0,
"end": 10.5,
"url": "https://assets.findclix.com/...",
"filename": "beach_sunset.mp4"
}
]
}Interactive reference
Highlights (Surprise Me)
GET /api/v1/media/highlightsRank the most unusual clips in your library — no query needed. Uses anomaly detection on the embedding space to surface surprising or standout moments.
Query parameters
| Param | Type | Default | Description |
|---|---|---|---|
count | int | 10 | Max results (max 50) |
method | string | knn | Anomaly scoring method: centroid (cheapest), knn (robust), lof (best with distinct sub-clusters) |
neighbors | int | 10 | k for knn/lof |
dedupe | float | 0.9 | Drop results too similar to a higher-ranked pick |
creator_id | string | — | Filter by creator |
category_id | string | — | Filter by category |
Example
bash
curl -H "Authorization: Bearer findclix_..." \
"https://findclix.com/api/v1/media/highlights?count=5&method=knn&dedupe=0.9"Response
json
{
"success": true,
"data": [
{
"id": "...",
"filename": "unusual_clip.mp4",
"score": 0.87,
"start": 2.1,
"end": 15.3,
"url": "https://assets.findclix.com/..."
}
]
}INFO
The score here is an anomaly score (higher = more unusual), not a search similarity score. Don't compare it with text/image search scores.