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 a secure signed 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. Signed URL Response (JSON) - When complete:

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

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

Request​

Responses​

Successful Response