curl -X GET "https://api.hooked.so/v1/video/vid_abc123" \
-H "x-api-key: your_api_key_here"
const videoId = 'vid_abc123';
const response = await fetch(`https://api.hooked.so/v1/video/${videoId}`, {
headers: { 'x-api-key': 'your_api_key_here' }
});
const data = await response.json();
console.log(`Video status: ${data.data.status}`);
console.log(`Duration: ${data.data.durationInSeconds}s`);
import requests
video_id = 'vid_abc123'
response = requests.get(
f'https://api.hooked.so/v1/video/{video_id}',
headers={'x-api-key': 'your_api_key_here'}
)
data = response.json()['data']
print(f"Video status: {data['status']}")
print(f"Duration: {data['durationInSeconds']}s")
{
"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.hooked.so/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
}
}
Videos
Get Video Details
Get detailed information about a specific video
GET
/
v1
/
video
/
{videoId}
curl -X GET "https://api.hooked.so/v1/video/vid_abc123" \
-H "x-api-key: your_api_key_here"
const videoId = 'vid_abc123';
const response = await fetch(`https://api.hooked.so/v1/video/${videoId}`, {
headers: { 'x-api-key': 'your_api_key_here' }
});
const data = await response.json();
console.log(`Video status: ${data.data.status}`);
console.log(`Duration: ${data.data.durationInSeconds}s`);
import requests
video_id = 'vid_abc123'
response = requests.get(
f'https://api.hooked.so/v1/video/{video_id}',
headers={'x-api-key': 'your_api_key_here'}
)
data = response.json()['data']
print(f"Video status: {data['status']}")
print(f"Duration: {data['durationInSeconds']}s")
{
"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.hooked.so/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
string
required
The unique identifier of the video to retrieve
curl -X GET "https://api.hooked.so/v1/video/vid_abc123" \
-H "x-api-key: your_api_key_here"
const videoId = 'vid_abc123';
const response = await fetch(`https://api.hooked.so/v1/video/${videoId}`, {
headers: { 'x-api-key': 'your_api_key_here' }
});
const data = await response.json();
console.log(`Video status: ${data.data.status}`);
console.log(`Duration: ${data.data.durationInSeconds}s`);
import requests
video_id = 'vid_abc123'
response = requests.get(
f'https://api.hooked.so/v1/video/{video_id}',
headers={'x-api-key': 'your_api_key_here'}
)
data = response.json()['data']
print(f"Video status: {data['status']}")
print(f"Duration: {data['durationInSeconds']}s")
{
"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.hooked.so/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
boolean
Indicates if the request was successful
string
Status message
object
Show Video Object
Show Video Object
string
Unique video identifier
string
Video name/title
string
Video type (class, ugc_ads, ugc_video, script_to_video, prompt_to_video, hook_demo, scenes, add_captions, extend_video, remove_background, tiktok_slideshow)
string
Current video status:
STARTED, COMPLETED, or FAILEDstring
Signed S3 URL to download the video (only available when status is COMPLETED)
string
URL to the video thumbnail image
number
Processing progress percentage (0-100)
string
Current status message
number
Video duration in frames (at 25 FPS)
number
Video duration in seconds
string
ID of the avatar used in the video
string
ID of the voice used for narration
string
ID of the background music track
object
Video configuration including aspect ratio and caption settings
string
The narration script used in the video
string
Associated project ID (if created from a project)
string
ISO 8601 timestamp of creation
string
ISO 8601 timestamp of last update
number
Number of credits consumed by this video
string
Webhook URL for status notifications (if configured)
Error Responses
{
"success": false,
"message": "Video not found"
}
{
"success": false,
"message": "Video does not belong to the user"
}
{
"success": false,
"message": "Not authenticated"
}
Status Codes
| Status | Code | Description |
|---|---|---|
| Success | 200 | Video found and details returned |
| Not Found | 404 | Video doesn’t exist |
| Forbidden | 403 | Video belongs to another team |
| Unauthorized | 403 | Invalid or missing API key |
| Server Error | 500 | Internal server error |
Video Status States
STARTED
STARTED
Video is currently being processed. The
progress field shows the current percentage.COMPLETED
COMPLETED
Video processing finished successfully. The
url field contains a signed URL to download the video. URL is valid for 24 hours.FAILED
FAILED
Video processing failed. Check the
message field for details about what went wrong.Downloading Videos
Once a video has statusCOMPLETED, the url field provides a signed S3 URL:
Download Example
async function downloadVideo(videoId) {
const response = await fetch(`https://api.hooked.so/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.so/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
Related Endpoints
List Videos
View all videos
Create Video
Create a new video
Video Webhook
Handle video completion notifications
Authorizations
Path Parameters
Video ID
Response
Video details retrieved successfully
Unique video identifier
Video name/title
Current video processing status
Available options:
STARTED, COMPLETED, FAILED Signed URL to download the video (only available when status is COMPLETED)
Duration of the video in frames (at 25fps)
Duration of the video in seconds (calculated from durationInFrames)
Associated project ID if video belongs to a project
Team ID that owns this video
URL to video thumbnail image
Video file size in bytes
Processing progress percentage (0-100)
Required range:
0 <= x <= 100Status message or error details
Video creation timestamp
Last update timestamp