Skip to main content

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 an authorized URL for downloading the video

Response Types:

  1. Status Response (JSON) - While generating:

    \{
      "video_id": "abc123",
      "message": "Annotated video is currently being generated...",
      "status": "pending"
    \}

  2. Download URL Response (JSON) - When complete:

    \{
      "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:

# 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 <download_url>

Request​

Responses​

Successful Response