Vision

Video Management

The Vision API provides comprehensive video management capabilities for uploading, retrieving, and organizing your video content.

Upload Videos

Upload videos using either a file upload or a URL:

You can optionally assign an uploaded video to a video group by including the group_id form field. Omit the field—or set it to default—to keep the video in the default pool.

Example with file upload

Bash

curl -X POST https://vision-agent.api.reka.ai/v1/videos/upload \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@video.mp4" \
  -F "video_name=my_video.mp4" \
  -F "index=true" \
  -F "group_id=20f4bc2d-3ebe-4fd2-829f-9d88c79e8a37"

Python

import requests
import json
url = f"{BASE_URL}/v1/videos/upload"
video_path = "/content/demo.mp4" # local video path
# Video indexing request body for a local video
data = {
   "index": True, # boolean value indicating whether the video should be indexed for search/qa/etc
   "enable_thumbnails": False, # boolean value indicating whether to generate thumbnails for video chunks, this will increase the indexing time but will allow for quick thumbnail loading at search time
   "video_name": "vid16", # name of video to store in vision agent system for informative purpose. not ID
   "video_start_absolute_timestamp": "2025-04-12T19:05:45", # (Optional) a absolute timestamp indicating video start time in ISO 8601 format
   "group_id": "20f4bc2d-3ebe-4fd2-829f-9d88c79e8a37", # optional video group assignment
}
headers = {
    "X-Api-Key": REKA_API_KEY
}
# Open the video file and send the request
with open(video_path, "rb") as file:
    files = {"file": (video_path[1:], file, "video/mp4")}  # Send as multipart/form-data
    response = requests.post(url, headers=headers, data=data, files=files)
# Print response
print(response.status_code, response.json())

Example with video url

Bash

curl -X POST https://vision-agent.api.reka.ai/v1/videos/upload \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "video_url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -F "video_name=my_video.mp4" \
  -F "index=true" \
  -F "group_id=default"

Python

import requests
import json
url = f"{BASE_URL}/v1/videos/upload"
video_url = "https://www.youtube.com/watch?v=dQw4w9WgXcQ" # video url
# Video indexing request body for a video url
data = {
   "index": True, 
   "video_name": "vid16", 
   "video_url": video_url,
   "video_start_absolute_timestamp": "2025-04-12T19:05:45",
   "group_id": "default",
}
headers = {
    "X-Api-Key": REKA_API_KEY
}
# Send the request
response = requests.post(url, headers=headers, data=data)
# Print response
print(response.status_code, response.json())

Python Bulk Upload Example

import os
import asyncio
import httpx
import time
import json
async def bulk_upload_videos(video_paths: list[str], api_key: str, caption_mode: str = "tagging_ad_video", max_concurrency: int = 2):
    tasks = []
    semaphore = asyncio.Semaphore(max_concurrency)
    async def limited_send_upload_request(sem: asyncio.Semaphore, video_path: str, *args, **kwargs):
        async with sem:
            response = await send_upload_request(video_path, *args, **kwargs)
            return video_path, response
    for video_path in video_paths:
        task = asyncio.create_task(limited_send_upload_request(semaphore, video_path, api_key, caption_mode))
        tasks.append(task)
    results = await asyncio.gather(*tasks)
    video_map = {}
    for video_path, result in results:
        if result and result.status_code == 200:
            try:
                video_id = result.json().get('video_id')
                if video_id:
                    video_map[video_path] = video_id
            except json.JSONDecodeError:
                print(f"Could not decode JSON from response for {video_path}")
    return video_map

Upload Parameters

  • file (optional): Video file to upload (mutually exclusive with video_url)
  • video_url (optional): URL of the video to upload (mutually exclusive with file)
  • video_name (required): Name for the video
  • video_absolute_start_timestamp (optional): ISO 8601 timestamp
  • index (required): Whether to index the video for search and Q&A
  • group_id (optional): Video group ID to attach the upload to. Defaults to default when omitted, and cannot be changed after upload.

Get Video

Retrieve a specific video by its ID:

Bash

curl -X GET https://vision-agent.api.reka.ai/v1/videos/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-Api-Key: YOUR_API_KEY"

Python

import requests
video_id = "550e8400-e29b-41d4-a716-446655440000"
url = f"{BASE_URL}/v1/videos/{video_id}"
headers = {
    "X-Api-Key": REKA_API_KEY
}
response = requests.get(url, headers=headers)
print(response.status_code, response.json())

List Videos

List all your videos:

Bash

curl -X GET "https://vision-agent.api.reka.ai/v1/videos" \
  -H "X-Api-Key: YOUR_API_KEY"

Python

import requests
url = f"{BASE_URL}/v1/videos"
headers = {
    "X-Api-Key": REKA_API_KEY
}
response = requests.get(url, headers=headers)
print(response.status_code, response.json())

Delete Video

Delete a video by its ID:

Bash

curl -X DELETE https://vision-agent.api.reka.ai/v1/videos/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-Api-Key: YOUR_API_KEY"

Python

import requests
video_id = "550e8400-e29b-41d4-a716-446655440000"
url = f"{BASE_URL}/v1/videos/{video_id}"
headers = {
    "X-Api-Key": REKA_API_KEY
}
response = requests.delete(url, headers=headers)
print(response.status_code, response.json())

Video Response Format

Each video response includes:

  • video_id: Unique identifier
  • url: Presigned S3 URL for access
  • indexing_status: Current indexing status (pending, indexing, indexed, failed)
  • metadata: Video metadata (dimensions, duration, timestamps, etc.)
  • indexing_type: Type of indexing applied
  • group_id: Video group identifier (default when no custom group is set)

Indexing Status

  • pending: Video uploaded, indexing not started
  • indexing: Video is currently being processed
  • indexed: Video has been successfully indexed and is ready for search/Q&A
  • failed: Indexing failed, video may need to be re-uploaded