Video Management

Videos are the core resource of the Vision API. Uploading a video stores it without processing it. Once the upload finishes, run the video features you need (transcript, captions, embeddings, objects) before searching or chatting with it.

Upload a video

Send a POST /v2/videos request as multipart/form-data, with either a file or a video_url. The endpoint returns 202 Accepted while the upload continues in the background.

Upload a local file

Bash

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

Python

import requests
BASE_URL = "https://vision-agent.api.reka.ai"
headers = {"X-Api-Key": REKA_API_KEY}
data = {
    "video_name": "my_video.mp4",
    "description": "Product demo recording",
    "group_id": "20f4bc2d-3ebe-4fd2-829f-9d88c79e8a37",
}
with open("video.mp4", "rb") as f:
    files = {"file": ("video.mp4", f, "video/mp4")}
    response = requests.post(f"{BASE_URL}/v2/videos", headers=headers, data=data, files=files)
response.raise_for_status()
print(response.json())

Upload from a URL

Bash

curl -X POST https://vision-agent.api.reka.ai/v2/videos \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "video_url=https://example.com/video.mp4" \
  -F "video_name=my_video.mp4"

Python

import requests
data = {
    "video_url": "https://example.com/video.mp4",
    "video_name": "my_video.mp4",
}
response = requests.post(f"{BASE_URL}/v2/videos", headers=headers, data=data)
response.raise_for_status()
print(response.json())

Upload parameters

• file (optional): Video file to upload. Send either file or video_url.
• video_url (optional): URL to download the video from.
• video_name (optional): Display name for the video. Required for file uploads.
• group_id (optional): ID of the video group to associate the video with.
• description (optional): Video description.

Upload response

{
  "video_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "uploading",
  "metadata": null
}

• video_id: Unique identifier for the uploaded video.
• status: Upload status, one of uploading, uploaded, or failed.
• metadata: Video metadata, populated after the upload completes.

Get a video

GET /v2/videos/{video_id} returns the upload status, metadata, and per-feature processing status for one video.

Bash

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

Python

video_id = "550e8400-e29b-41d4-a716-446655440000"
response = requests.get(f"{BASE_URL}/v2/videos/{video_id}", headers=headers)
response.raise_for_status()
video = response.json()
print(video["status"], video["features"])

Video response

{
  "video_id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://s3.amazonaws.com/bucket/video.mp4?presigned=...",
  "status": "uploaded",
  "metadata": {
    "width": 1920,
    "height": 1080,
    "avg_fps": 23.976023976023978,
    "video_name": "my_video.mp4",
    "title": "my_video.mp4",
    "video_start_timestamp_utc_ms": null,
    "duration": 641.939,
    "thumbnail": "https://example.com/thumbnail.jpg",
    "thumbnails": "https://example.com/thumbnails.vtt",
    "description": "Product demo recording",
    "source": "video.mp4"
  },
  "features": {
    "transcript": "ready",
    "embeddings": "processing"
  },
  "group_id": "20f4bc2d-3ebe-4fd2-829f-9d88c79e8a37",
  "error": null
}

• video_id: Unique identifier for the video.
• url: Presigned URL to access the video.
• status: Upload status (uploading, uploaded, failed).
• metadata: Dimensions, frame rate, name, title, start timestamp in milliseconds, duration in seconds, thumbnail URL, storyboard thumbnails URL (typically VTT), description, and source.
• features: Processing status for each feature, one of none, pending, processing, ready, failed, or blocked. See Video Features.
• group_id: ID of the group the video belongs to, if any.
• error: Error message if the upload or download failed.

List videos

GET /v2/videos lists every video you own, across all groups. Pass ids one or more times to return only those videos.

Bash

curl "https://vision-agent.api.reka.ai/v2/videos" \
  -H "X-Api-Key: YOUR_API_KEY"
curl "https://vision-agent.api.reka.ai/v2/videos?ids=550e8400-e29b-41d4-a716-446655440000&ids=2ee0262d-1dc5-4a50-adb3-e40da8893c8d" \
  -H "X-Api-Key: YOUR_API_KEY"

Python

response = requests.get(f"{BASE_URL}/v2/videos", headers=headers)
response.raise_for_status()
for video in response.json()["results"]:
    print(video["video_id"], video["status"])

The response wraps the videos in a results array, each entry shaped like the video response above.

Update a video

PATCH /v2/videos/{video_id} changes a video’s name, title, or description, or moves it to another group. Fields you omit or set to null stay unchanged. The target group must exist and belong to you.

Bash

curl -X PATCH https://vision-agent.api.reka.ai/v2/videos/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product demo (final cut)",
    "description": "Final edit of the product demo",
    "group_id": "20f4bc2d-3ebe-4fd2-829f-9d88c79e8a37"
  }'

Python

payload = {
    "name": "Product demo (final cut)",
    "description": "Final edit of the product demo",
    "group_id": "20f4bc2d-3ebe-4fd2-829f-9d88c79e8a37",
}
response = requests.patch(f"{BASE_URL}/v2/videos/{video_id}", json=payload, headers=headers)
response.raise_for_status()
print(response.json())

Update parameters

• name (optional): Display name shown in listings and search results.
• title (optional): Video title.
• description (optional): Video description.
• group_id (optional): Group to move the video to.

The response is the updated video.

Delete a video

DELETE /v2/videos/{video_id} deletes a single video.

Bash

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

Python

response = requests.delete(f"{BASE_URL}/v2/videos/{video_id}", headers=headers)
response.raise_for_status()
print(response.json())

Delete response

{
  "status": "success",
  "message": "Video deleted successfully"
}