> ## 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.

# Visual Search Batch

> Find videos by describing visual content using CLIP-based similarity

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

<Warning>
  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](/guides/visual-search) before building against it.
</Warning>

<Note>
  Visual search is in **beta**. It works best for broad visual descriptions. For details and example queries, see the [Visual Search Guide](/guides/visual-search).
</Note>

## Path parameters

<ParamField path="batch_id" type="string" required>
  UUID of the batch to search. Must be completed and have keyframe embeddings — a
  batch with none returns an empty result set.
</ParamField>

## Request body

<ParamField body="query" type="string" required>
  Text description of visual content to find (e.g. `"outdoor establishing shot"`, `"person at desk"`).
</ParamField>

<ParamField body="max_results" type="integer" default={10}>
  Maximum number of results to return (1-50).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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
      }
    ]
  }
  ```
</ResponseExample>

## 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.