Getting Started With a Video Search API: A Developer Guide

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.

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.

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.

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.

{
  "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 to get API access.