Skip to navigation
Vision APIsVision

Video Search

For chat over text, images and short videos, use the OpenAI-compatible Chat Completions API.

POST /v2/search finds moments across your videos. It supports two strategies:

  • semantic (default): Embedding similarity against a natural language query. Videos need the embeddings feature to be ready.
  • text: Literal substring match against transcripts, captions, or both. Videos need the matching transcript or captions feature.

Search videos

Bash

curl -X POST https://vision-agent.api.reka.ai/v2/search \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "person giving a presentation with charts",
    "threshold": "medium",
    "page_limit": 10
  }'

Python

import requests
BASE_URL = "https://vision-agent.api.reka.ai"
headers = {"X-Api-Key": REKA_API_KEY}
payload = {
    "query": "person giving a presentation with charts",
    "threshold": "medium",
    "page_limit": 10,
}
response = requests.post(f"{BASE_URL}/v2/search", json=payload, headers=headers)
response.raise_for_status()
for result in response.json()["data"]:
    print(result["rank"], result["video_id"], result["start"], result["end"], result["score"])

Search parameters

General parameters:

  • query (required): Natural language for semantic, literal text for text.
  • strategy (optional): semantic (default) or text.
  • fields (optional): For text only, which data to search: transcript, captions, or both (the default). Ignored for semantic.
  • video_ids (optional): Search only these videos.
  • group_ids (optional): Search only videos in these groups.
  • threshold (optional): Named confidence filter, one of high, medium, low (default), or none. Only affects semantic.
  • rerank (optional): Apply embedding-based reranking. semantic only, slightly slower. Defaults to false.
  • include_report (optional): Generate an LLM summary of the results. semantic only. Defaults to false.

Filtering parameters:

  • filter (optional): Metadata filters. duration (seconds), width and height (pixels) each take a range with optional gte and lte bounds. id filters to specific video IDs, the same as video_ids.
  • datetime_from, datetime_to (optional): An explicit UTC datetime range for semantic search, in ISO 8601 format.
  • timestamp_from, timestamp_to (optional): An in-video timestamp range in seconds.

Pagination parameters:

  • page_limit (optional): Results per page, up to 50. Defaults to 10.
  • page_token (optional): The next_page_token from a previous response.

Search response

{
  "data": [
    {
      "video_id": "550e8400-e29b-41d4-a716-446655440000",
      "video_name": "Quarterly review",
      "start": 10.5,
      "end": 25.3,
      "score": 0.82,
      "rank": 1,
      "caption": "A presenter points at a bar chart on a projected slide.",
      "transcript": "As you can see, revenue grew in every region this quarter.",
      "thumbnail_url": null,
      "video_url": "https://s3.amazonaws.com/bucket/video.mp4?presigned=..."
    }
  ],
  "next_page_token": "NEXT_PAGE_TOKEN",
  "report": null,
  "search_pool": {
    "video_count": 12,
    "total_duration": 5421.7
  }
}

Result fields

  • video_id: Video this moment is from.
  • video_name: Video display name.
  • start, end: Start and end of the moment, in seconds.
  • score: Relevance score between 0 and 1. Text matches are binary, and always score 1.0.
  • rank: Position in the results, where 1 is the most relevant.
  • caption: AI description of the visual content.
  • transcript: Spoken words in this segment.
  • thumbnail_url: Preview frame URL. Not yet available.
  • video_url: Presigned URL to the parent video.

Top-level fields

  • data: The matching moments.
  • next_page_token: Pass as page_token to fetch the next page. null on the last page.
  • report: LLM-generated summary, when include_report is true.
  • search_pool: The number of videos searched (video_count) and their total duration in seconds (total_duration).

Search examples

Text search over transcripts

curl -X POST https://vision-agent.api.reka.ai/v2/search \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly revenue",
    "strategy": "text",
    "fields": ["transcript"]
  }'

Scope to a group and filter by duration

curl -X POST https://vision-agent.api.reka.ai/v2/search \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "people walking on a beach",
    "group_ids": ["20f4bc2d-3ebe-4fd2-829f-9d88c79e8a37"],
    "filter": {"duration": {"gte": 60, "lte": 600}},
    "threshold": "low"
  }'

Page through every result

payload = {"query": "red car driving on a highway", "threshold": "none", "page_limit": 50}
results = []
while True:
    page = requests.post(f"{BASE_URL}/v2/search", json=payload, headers=headers).json()
    results.extend(page["data"])
    if not page.get("next_page_token"):
        break
    payload["page_token"] = page["next_page_token"]
print(len(results))

Search tips

  • Be specific: “person walking on a beach” works better than “walking”.
  • Tune threshold per query: Start with low, raise it to medium or high for precise filtering, or use none to see every candidate.
  • Use text for exact phrases: Names, product codes, or quotes match more reliably with literal search over transcripts.
  • Feed results into chat: Each result’s video_id, start, and end can go straight into the context of a video chat request.