> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.reka.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.reka.ai/_mcp/server.

# Video Management

> Upload, retrieve, list, update, and delete videos

> **Info**
>
> For chat over text, images and short videos, use the OpenAI-compatible [Chat Completions API](/chat/overview).

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](/vision/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

```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

```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

```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

```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](/vision/video-group-management) to associate the video with.
* **`description`** (optional): Video description.

### Upload response

```json
{
  "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

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

#### Python

```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

```json
{
  "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](/vision/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

```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

```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](#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

```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

```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](#video-response).

## Delete a video

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

#### Bash

```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

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

### Delete response

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