Skip to main content
GET
/
v1
/
video
/
{videoId}
curl -X GET "https://api.tryhooked.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.tryhooked.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.tryhooked.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.tryhooked.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

List Videos

View all videos

Create Video

Create a new video

Video Webhook

Handle video completion notifications

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
videoId
string
required

Video ID

Response

Video details fetched successfully

​
success
boolean
​
message
string
​
data
object