Skip to main content
GET
/
v1
/
video
/
{videoId}
curl -X GET "https://api.hooked.ai/v1/video/vid_abc123" \
  -H "x-api-key: your_api_key_here"
{
  "success": true,
  "message": "Video details fetched successfully",
  "data": {
    "id": "vid_abc123",
    "name": "Product Tutorial",
    "type": "class",
    "status": "COMPLETED",
    "url": "https://s3.amazonaws.com/hooked-videos/vid_abc123.mp4",
    "thumbnail": "https://cdn.tryhooked.ai/thumbnails/abc123.jpg",
    "progress": 100,
    "message": "Video completed successfully",
    "durationInFrames": 7500,
    "durationInSeconds": 300,
    "avatarId": "avatar_sarah_01",
    "voiceId": "tzX5paJ07p5hyWFcU3uG",
    "musicId": "1",
    "videoSettings": {
      "aspectRatio": "ratio_9_16",
      "caption": {
        "disabled": false,
        "preset": "classic"
      }
    },
    "script": "Hello! Welcome to this tutorial...",
    "projectId": "proj_abc123",
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:05:00Z",
    "usedCredits": 5,
    "webhook": null
  }
}

Overview

This endpoint retrieves comprehensive details about a specific video, including status, URL, duration, and metadata. Use this to monitor individual video progress or retrieve video information for display.
This endpoint requires authentication and only returns videos that belong to your team.

Path Parameters

videoId
string
required
The unique identifier of the video to retrieve
curl -X GET "https://api.hooked.ai/v1/video/vid_abc123" \
  -H "x-api-key: your_api_key_here"
{
  "success": true,
  "message": "Video details fetched successfully",
  "data": {
    "id": "vid_abc123",
    "name": "Product Tutorial",
    "type": "class",
    "status": "COMPLETED",
    "url": "https://s3.amazonaws.com/hooked-videos/vid_abc123.mp4",
    "thumbnail": "https://cdn.tryhooked.ai/thumbnails/abc123.jpg",
    "progress": 100,
    "message": "Video completed successfully",
    "durationInFrames": 7500,
    "durationInSeconds": 300,
    "avatarId": "avatar_sarah_01",
    "voiceId": "tzX5paJ07p5hyWFcU3uG",
    "musicId": "1",
    "videoSettings": {
      "aspectRatio": "ratio_9_16",
      "caption": {
        "disabled": false,
        "preset": "classic"
      }
    },
    "script": "Hello! Welcome to this tutorial...",
    "projectId": "proj_abc123",
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:05:00Z",
    "usedCredits": 5,
    "webhook": null
  }
}

Response Fields

success
boolean
Indicates if the request was successful
message
string
Status message
data
object

Error Responses

{
  "success": false,
  "message": "Video not found"
}

Status Codes

StatusCodeDescription
Success200Video found and details returned
Not Found404Video doesn’t exist
Forbidden403Video belongs to another team
Unauthorized403Invalid or missing API key
Server Error500Internal server error

Video Status States

Video is currently being processed. The progress field shows the current percentage.
Video processing finished successfully. The url field contains a signed URL to download the video. URL is valid for 24 hours.
Video processing failed. Check the message field for details about what went wrong.

Downloading Videos

Once a video has status COMPLETED, the url field provides a signed S3 URL:
Download Example
async function downloadVideo(videoId) {
  const response = await fetch(`https://api.hooked.ai/v1/video/${videoId}`, {
    headers: { 'x-api-key': API_KEY }
  });

  const video = await response.json();

  if (video.data.status === 'COMPLETED') {
    // URL is pre-signed and ready to download
    window.location.href = video.data.url;
  }
}

Polling for Completion

To monitor video progress, you can poll this endpoint:
Polling Example
async function waitForVideoCompletion(videoId, maxWait = 300000) {
  const startTime = Date.now();
  const pollInterval = 5000; // Check every 5 seconds

  while (Date.now() - startTime < maxWait) {
    const response = await fetch(`https://api.hooked.ai/v1/video/${videoId}`, {
      headers: { 'x-api-key': API_KEY }
    });

    const data = await response.json();
    const { status, progress } = data.data;

    console.log(`Progress: ${progress}%`);

    if (status === 'COMPLETED') {
      return data.data;
    } else if (status === 'FAILED') {
      throw new Error(`Video failed: ${data.data.message}`);
    }

    await new Promise(resolve => setTimeout(resolve, pollInterval));
  }

  throw new Error('Video rendering timeout');
}
Better approach: Use webhooks instead of polling. See Video Webhook for details.

Use Cases

Progress Tracking

Monitor video rendering progress

Download Management

Get download URLs for completed videos

Status Display

Show video status in your dashboard

Error Handling

Detect and handle rendering failures

Authorizations

x-api-key
string
header
required

Path Parameters

videoId
string
required

Video ID

Response

Video details retrieved successfully

id
string

Unique video identifier

name
string

Video name/title

status
enum<string>

Current video processing status

Available options:
STARTED,
COMPLETED,
FAILED
url
string

Signed URL to download the video (only available when status is COMPLETED)

durationInFrames
integer

Duration of the video in frames (at 25fps)

durationInSeconds
number

Duration of the video in seconds (calculated from durationInFrames)

projectId
string | null

Associated project ID if video belongs to a project

teamId
string

Team ID that owns this video

thumbnail
string | null

URL to video thumbnail image

size
integer

Video file size in bytes

progress
integer

Processing progress percentage (0-100)

Required range: 0 <= x <= 100
message
string | null

Status message or error details

createdAt
string<date-time>

Video creation timestamp

updatedAt
string<date-time>

Last update timestamp