Vision

Video Search

Video Search

The Vision API provides powerful video search capabilities through the /videos/search endpoint, which allows you to search through your uploaded videos using semantic queries.

Search Videos

Search through your videos using natural language queries:

$curl -X POST https://vision-agent.api.reka.ai/videos/search \
>  -H "X-Api-Key: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "query": "person walking on beach",
>    "limit": 10,
>    "threshold": 0.2
>  }'

Search Parameters

  • query (required): Natural language search query
  • limit (optional): Maximum number of results to return
  • threshold (optional): Confidence threshold level from 0 (lowest) to 1 (highest). Different queries may need different thresholds based on their specificity and the nature of your search.

Search Response

The search endpoint returns relevant video chunks with confidence scores relative to your search query:

1{
2  "results": [
3    {
4      "video_chunk_id": "123e4567-e89b-12d3-a456-426614174000",
5      "video_id": "550e8400-e29b-41d4-a716-446655440000",
6      "score": 0.95,
7      "start_timestamp": 10.5,
8      "end_timestamp": 25.3,
9      "s3_presigned_url": "https://s3.amazonaws.com/bucket/video.mp4?presigned=..."
10    }
11  ],
12  "total_results": 1
13}

Note: Confidence scores (0.0 to 1.0) are relative to your specific search query. A score of 0.95 for “person walking on beach” indicates high relevance to that particular query, not an absolute measure of query matching. Thresholds may vary significantly for each query and will require experimentation - one query might have a highest score of 0.8 while another query has 0.2 as the highest score, depending on the specificity and content of your videos.

Response Fields

  • video_chunk_id: Unique identifier for the specific video chunk
  • video_id: ID of the parent video
  • score: Confidence score (0.0 to 1.0) relative to your search query
  • start_timestamp: Start time of the chunk in seconds
  • end_timestamp: End time of the chunk in seconds
  • s3_presigned_url: Direct access URL for the video chunk

Search Examples

Basic Content Search

$# Search for videos containing people
>curl -X POST https://vision-agent.api.reka.ai/videos/search \
>  -H "X-Api-Key: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "query": "people walking",
>  }'

Search with Threshold and Limit

$# Find only highly relevant videos
>curl -X POST https://vision-agent.api.reka.ai/videos/search \
>  -H "X-Api-Key: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "query": "outdoor activities",
>    "limit": 10,
>    "threshold": 0.3
>  }'

Search with no threshold

$# Get more results with lower relevance requirements
>curl -X POST https://vision-agent.api.reka.ai/videos/search \
>  -H "X-Api-Key: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "query": "children playing",
>    "limit": 10
>  }'

Best Practices

  1. Use descriptive queries for better search results
  2. Set appropriate thresholds based on your query type and needs:
    • Specific queries (e.g., “red car driving on highway”): Use higher thresholds (0.7-0.9) for precise matches
    • General queries (e.g., “people”): Use lower thresholds (0.2-0.5) to capture more results
    • Exploratory searches: Use very low thresholds (0.1-0.3) to discover content
    • Production applications: Start with moderate thresholds (0.4-0.6) and adjust based on results
  3. Understand confidence scores are relative to your query, not absolute video quality
  4. Set reasonable limits to manage response size
  5. Experiment with different thresholds for the same query to find optimal results
  6. Consider query complexity: Simple queries may need lower thresholds, complex queries may need higher thresholds
  7. Remember threshold variability: Each query may have different score ranges - one query’s highest score might be 0.8 while another’s is 0.2, requiring different threshold strategies

Search Tips

  • Be specific: “person walking on beach” is better than “walking”
  • Use natural language: The search understands conversational queries
  • Adjust threshold based on query type:
    • Specific objects/actions: Higher thresholds (0.7+)
    • General concepts: Lower thresholds (0.3-0.6)
    • Broad categories: Very low thresholds (0.1-0.3)
  • Consider your use case: Use lower thresholds for exploratory searches, higher for precise filtering
  • Monitor confidence scores: Higher scores indicate better matches for your specific query
  • Remember relativity: A 0.9 score for one query might be different than 0.9 for another query
  • Test different thresholds: The same query may work better with different thresholds depending on your video content