---
title: "Get Annotated Video"
method: GET
path: "/v2/videos/{video_id}/annotated_video"
tags: ["Video Emotion API"]
---

# Get Annotated Video

`GET /v2/videos/{video_id}/annotated_video`

Get annotated video with emotion labels and bounding boxes overlaid on each frame.

**How It Works:**
- First request initiates video generation and returns a status response
- Poll this endpoint to check generation progress
- When ready, returns a secure signed URL for downloading the video

**Response Types:**

1. **Status Response** (JSON) - While generating:
   ```json
   {
     "video_id": "abc123",
     "message": "Annotated video is currently being generated...",
     "status": "pending"
   }
   ```

2. **Signed URL Response** (JSON) - When complete:
   ```json
   {
     "video_id": "abc123",
     "download_url": "https://storage.googleapis.com/...",
     "filename": "My_Video_abc123.mp4",
     "expires_in_minutes": 60,
     "expires_at": "2026-01-09T12:00:00Z",
     "note": "Download URL will expire. Request a new URL if expired."
   }
   ```

**Parameters:**
- `video_id`: Video identifier
- `callback_url`: Optional webhook URL to receive notification when generation completes

**Prerequisites:**
Video analysis must be complete before requesting annotated video.

**Security:**
- New videos are stored privately and require signed URLs for access
- Signed URLs expire after 60 minutes for security
- Old videos may use public URLs (backward compatibility)

**Example Workflow:**

```python
# 1. Request annotated video (with optional callback URL)
GET /v2/videos/abc123/annotated_video?callback_url=https://example.com/webhook
Response: {"status": "pending", "message": "..."}

# 2. Check status (poll until ready)
GET /v2/videos/abc123/annotated_video
Response: {"status": "in progress", "message": "..."}

# 3. Get download URL when ready
GET /v2/videos/abc123/annotated_video
Response: {"video_id": "abc123", "download_url": "https://...", ...}

# 4. Download video from the signed URL
GET <download_url>
```

## Path parameters

- `video_id` string, required — The unique video ID of the video

## Query parameters

- `callback_url` string — Optional callback URL to notify when annotated video generation is complete

## Response `200`

Successful Response

- union
  - SignedDownloadUrlResponse — Response containing a signed URL for downloading annotated video. Attributes: video_id (str): ID of the video. download_url (str): Signed URL for downloading the video file. filename (str): Suggested filename for the download. expires_in_minutes (int): Number of minutes until the URL expires. expires_at (str): ISO 8601 formatted expiration timestamp. note (str): Additional information about the download.
    - `video_id` string, required
    - `download_url` string, required
    - `filename` string, required
    - `expires_in_minutes` integer, required
    - `expires_at` string, required
    - `note` string
  - AnnotatedVideoResponse — Response for annotated video generation status. Attributes: video_id (str): ID of the video. message (str): Status message. status (str): Current status of annotated video generation (pending, in progress, completed).
    - `video_id` string, required
    - `message` string, required
    - `status` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/imentiv/apis/welcome-to-imentiv-ai.md) · [All operations](https://skmtc.net/imentiv/apis/welcome-to-imentiv-ai/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/imentiv/welcome-to-imentiv-ai/revisions/350e9cbcb623/schema)