# Getting Started With a Video Search API: A Developer Guide

Integrating video search into an application. RESTful endpoints, four search modalities, authentication, and a walkthrough of the upload-process-search workflow.

- Published: 2026-03-30
- Author: FrameQuery Team
- Category: Workflows
- Canonical: https://www.framequery.com/blog/video-search-api-getting-started

A video search API gives an application endpoints to upload footage, run AI analysis on it and query the resulting index. This guide covers how the FrameQuery API works: media management platforms, e-learning tools, compliance review and internal knowledge bases are the usual callers.

## What a video search API provides

The workflow has three stages: upload a file or a URL, process it, and search the index for timestamped results.

A transcription API or an object detection API covers one modality. A video search API combines several in one index and returns one ranked result list.

## Four search modalities

The API runs four analysis passes per video and the search endpoint queries all of them.

**Transcript search.** Full-text search across everything spoken in the video. Each segment returns with its own start and end time. Supports exact phrase matching and speaker filtering.

**Object search.** Search for objects detected in the video frames: vehicles, laptops, whiteboards, animals, signage. Each detection is timestamped to the frame where it appears.

**Scene search.** Natural-language search against AI-generated scene descriptions. Query with phrases like "two people shaking hands in a lobby" and get matching moments.

**Face search.** Search by person across your indexed library. Once faces are clustered and optionally named, you can find every appearance of a specific individual.

Query one modality or all of them at once.

## Authentication

The API uses key-based authentication. Include your key in the `Authorization` header: `Bearer fq_your_api_key_here`. Rate limits depend on your plan tier. Processing requests are limited by your monthly processing quota. Search requests have a higher limit because they run against a built index.

## The upload-process-search workflow

Example requests for each stage.

**Upload.** Send a file or URL to the upload endpoint. The API returns a `video_id` for subsequent requests.

```bash
curl -X POST https://api.framequery.com/v1/videos \
  -H "Authorization: Bearer fq_your_api_key_here" \
  -F "file=@interview-march-14.mp4"
```

**Process.** Trigger analysis on the uploaded video. Choose which modalities to run. Transcript-only and scene-only processing each cost 50% of the full rate.

```bash
curl -X POST https://api.framequery.com/v1/videos/vid_abc123/process \
  -H "Authorization: Bearer fq_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"modalities": ["transcript", "objects", "scenes", "faces"]}'
```

Indexing takes about five minutes per hour of video. Poll the status endpoint to check progress, or register a webhook callback URL for production integrations.

**Search.** Once processing completes, query the indexed content. Omit `video_id` to search across your entire library.

```bash
curl "https://api.framequery.com/v1/search?q=budget+projections&video_id=vid_abc123" \
  -H "Authorization: Bearer fq_your_api_key_here"
```

Results include timestamps, the matching modality, the matched text, a relevance score, and speaker attribution where applicable. You can filter by modality, speaker, date range, or video ID.

```json
{
  "results": [
    {
      "video_id": "vid_abc123",
      "timestamp_start": 1232.4,
      "timestamp_end": 1238.1,
      "modality": "transcript",
      "text": "The budget projections for Q3 need to be revised.",
      "speaker": "Speaker 1",
      "score": 0.94
    }
  ]
}
```

## Searching across your entire library

Omit the `video_id` parameter to search every video you have processed. Results come from all indexed videos, ranked by relevance.

## When to use an API vs the desktop app

**Use the desktop app** when a person or a small team wants to search their own footage through an interface.

**Use the API** when you are building video search into your own product, automating processing pipelines, or integrating with existing systems. Both use the same processing pipeline and search engine.

## Response format and pagination

Search responses are paginated with a default page size of 20 results. Use `offset` and `limit` parameters for pagination. Results are sorted by relevance score by default, with options to sort by timestamp or date.

[Download FrameQuery](/welcome) to get API access.