--- 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` ## Request - Base URL: `https://api.imentiv.ai` (the document declares no server; this is the origin it was published from) - URL: `https://api.imentiv.ai/v2/videos/{video_id}/annotated_video` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer - OAuth 2 - Authorization code: `https://api.imentiv.ai/oauth/authorize` - Token URL: `https://api.imentiv.ai/oauth/token` scopes: `media.read` 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 an authorized 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. **Download URL Response** (JSON) - When complete: ```json { "video_id": "abc123", "download_url": "https://...", "filename": "My_Video_abc123.mp4", "expires_in_minutes": 60, "expires_at": "2026-01-09T12:00:00Z", "note": "Download URLs are short-lived. Request a new URL if a download fails." } ``` **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; the returned URL is what authorizes the download - Treat `download_url` as short-lived — fetch it promptly and request a new one rather than storing or sharing it - 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 returned URL GET ``` ## 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. Must be an https URL on a publicly reachable host. ## Response `200` Successful Response - union - SignedDownloadUrlResponse: Response containing an authorized URL for downloading an annotated video. Attributes: video_id (str): ID of the video. download_url (str): Authorized URL for downloading the video file. Treat it as short-lived and fetch it promptly; request a new one rather than storing it. filename (str): Suggested filename for the download. expires_in_minutes (int): How long to treat `download_url` as usable before requesting a new one. expires_at (str): ISO 8601 timestamp corresponding to `expires_in_minutes`. note (str): Additional information about the download. disposition (Optional[str]): ``attachment`` when `download_url` itself makes a browser save the file (the header is signed into the URL), so a client can hand it to the browser without reading the bytes. Absent from older servers. - `video_id` string, required - `download_url` string, required - `filename` string, required - `expires_in_minutes` integer, required - `expires_at` string, required - `note` string - `disposition` string, nullable - 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). job_id (Optional[str]): Identity of the generation job this answer describes. A retry after a failure gets a new one; progress and stage always belong to the job named here. stage (Optional[str]): Where the job is: queued, starting, fetching_frames, downloading_source, extracting_audio, rendering, muxing_audio, uploading, finalizing. percentage (Optional[int]): Whole-percent progress of the render, when the job reports it. - `video_id` string, required - `message` string, required - `status` string, required - `job_id` string, nullable - `stage` string, nullable - `percentage` integer, nullable ## Other responses - `422`: Validation Error ## Changes - **2026-10-31** `bd825cd86e8c`: 4 info - added the optional property `anyOf[subschema #1: SignedDownloadUrlResponse]/disposition` to the response with the `200` status - added the optional property `anyOf[subschema #2: AnnotatedVideoResponse]/job_id` to the response with the `200` status - added the optional property `anyOf[subschema #2: AnnotatedVideoResponse]/percentage` to the response with the `200` status - added the optional property `anyOf[subschema #2: AnnotatedVideoResponse]/stage` to the response with the `200` status - **2026-10-01** `72330e2229c7`: 1 info - the `note` response's property default value changed from `Download URL will expire. Request a new URL if expired.` to `Download URLs are short-lived. Request a new URL if a download fails.` for the status `200` - **2026-09-22** `536bf48bb9fb`: 3 info - the endpoint scheme security `ApiKeyAuth` was added to the API - the endpoint scheme security `BearerAuth` was added to the API - the endpoint scheme security `OAuth2Delegated` was added to the API [Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v2/videos/:video_id/annotated_video/get.md) --- [API](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai.md) - [All operations](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/llms.txt) - [OpenAPI document](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/revisions/bc15cec7e794?raw)