Hooked Video API

Create professional AI videos programmatically. Works with TikTok, Instagram, YouTube, and more.

Authentication

All requests require an x-api-key header with your Hooked API key.

# Get your API key at https://hooked.so/settings/api
export HOOKED_API_KEY="your_api_key_here"

Base URL

https://api.hooked.so

Core Endpoints

Create Script-to-Video

Create a video from a script with an AI avatar that lip-syncs.

POST /v1/project/create/script-to-video

{
  "script": "Hey everyone! Today I'm going to show you...",
  "avatarId": "avatar_sophia_casual",
  "voiceId": "voice_en_sarah",         # optional
  "musicId": "music_upbeat_01",         # optional
  "captionStyle": "karaoke",            # optional: karaoke, word-by-word, none
  "webhook": "https://your.webhook/url" # optional
}

# Response
{
  "videoId": "vid_abc123",
  "status": "processing",
  "estimatedSeconds": 45
}

Create Prompt-to-Video

Let AI generate the script, visuals, and narration from a simple prompt.

POST /v1/project/create/prompt-to-video

{
  "prompt": "Create a 30-second product video for a fitness app targeting young professionals",
  "avatarId": "avatar_marcus_professional", # optional, AI picks if not specified
  "voiceId": "voice_en_james",              # optional
  "webhook": "https://your.webhook/url"     # optional
}

Create TikTok Slideshow

Create viral TikTok-style slideshow content.

POST /v1/project/create/tiktok-slideshow

{
  "title": "5 Productivity Tips for Remote Workers",
  "slides": [
    { "text": "Tip 1: Start your day with deep work", "imageUrl": "https://..." },
    { "text": "Tip 2: Batch your meetings", "imageUrl": "https://..." },
    { "text": "Tip 3: Take walking breaks", "imageUrl": "https://..." }
  ],
  "voiceId": "voice_en_sarah", # optional
  "musicId": "music_chill_01", # optional
  "webhook": "https://..."     # optional
}

Create UGC Ad

Create authentic UGC-style product ads.

POST /v1/project/create/ugc-ads

{
  "script": "Okay so I've been using this app for 2 weeks and...",
  "avatarId": "avatar_emma_casual",
  "productUrl": "https://mystore.com/product", # optional, extracts visuals
  "hook": "Stop scrolling! You need to see this", # optional
  "cta": "Link in bio",                          # optional
  "webhook": "https://..."                        # optional
}

Resource Endpoints

List Avatars

Browse available AI avatars.

GET /v1/avatar/list

# Response
{
  "avatars": [
    {
      "id": "avatar_sophia_casual",
      "name": "Sophia",
      "gender": "female",
      "style": "casual",
      "previewUrl": "https://...",
      "tags": ["young", "energetic", "lifestyle"]
    },
    ...
  ]
}

List Voices

Browse available AI voices.

GET /v1/voice/list

# Response
{
  "voices": [
    {
      "id": "voice_en_sarah",
      "name": "Sarah",
      "language": "en",
      "accent": "american",
      "style": "conversational",
      "previewUrl": "https://..."
    },
    ...
  ]
}

List Music

Browse background music tracks.

GET /v1/music/list

# Response
{
  "tracks": [
    {
      "id": "music_upbeat_01",
      "name": "Upbeat Energy",
      "mood": "energetic",
      "duration": 60,
      "previewUrl": "https://..."
    },
    ...
  ]
}

Video Management

Get Video Status

Check video rendering progress and get download URL.

GET /v1/video/{videoId}

# Response
{
  "videoId": "vid_abc123",
  "status": "completed", # processing, completed, failed
  "progress": 100,
  "downloadUrl": "https://...",
  "duration": 32,
  "createdAt": "2024-01-15T10:30:00Z"
}

List Videos

List recent videos created by your team.

GET /v1/video/list?limit=20

# Response
{
  "videos": [
    {
      "videoId": "vid_abc123",
      "status": "completed",
      "title": "Product Demo",
      "duration": 32,
      "createdAt": "2024-01-15T10:30:00Z"
    },
    ...
  ]
}

Trend Discovery

Get Trending Videos

Discover what's trending for content inspiration.

GET /v1/trends/videos?platform=tiktok&niche=fitness

# Response
{
  "trends": [
    {
      "title": "30-day ab challenge",
      "platform": "tiktok",
      "views": 2300000,
      "engagement": "high",
      "hook": "Day 1 vs Day 30 results...",
      "tags": ["fitness", "transformation", "challenge"]
    },
    ...
  ]
}

Query parameters:

platform: tiktok, youtube, instagram (optional)
niche: fitness, tech, beauty, food, etc. (optional)

Webhooks

All creation endpoints accept a webhook URL. When the video is ready, we'll POST:

{
  "event": "video.completed",
  "videoId": "vid_abc123",
  "status": "completed",
  "downloadUrl": "https://...",
  "duration": 32
}

Error Handling

{
  "error": {
    "code": "INVALID_AVATAR",
    "message": "Avatar 'avatar_xyz' not found. Use GET /v1/avatar/list to see available avatars."
  }
}

Common error codes:

INVALID_API_KEY: Check your x-api-key header
INVALID_AVATAR: Avatar ID not found
INVALID_VOICE: Voice ID not found
SCRIPT_TOO_LONG: Script exceeds maximum length (5000 chars)
RATE_LIMITED: Too many requests, wait and retry

Pricing

Pro: $39/month — 150 credits (~30 videos)
Premium: $79/month — 350 credits (~70 videos)
Ultra: $149/month — 750 credits (~150 videos)

The skill itself is free and open source. You only pay for video generation.

Rate Limits

60 requests per minute

Example: Full Workflow

# 1. List avatars to find a good fit
curl -X GET "https://api.hooked.so/v1/avatar/list" \
  -H "x-api-key: $HOOKED_API_KEY"

# 2. Create a video
curl -X POST "https://api.hooked.so/v1/project/create/script-to-video" \
  -H "x-api-key: $HOOKED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "Hey! In this video I am going to show you 3 productivity hacks...",
    "avatarId": "avatar_sophia_casual",
    "captionStyle": "karaoke"
  }'

# 3. Check status (poll until completed)
curl -X GET "https://api.hooked.so/v1/video/vid_abc123" \
  -H "x-api-key: $HOOKED_API_KEY"

# 4. Download when ready
# Use the downloadUrl from the response

Tips for Agents

Always list avatars first if the user doesn't specify one
Use prompt-to-video for vague requests — it handles script generation
Check video status and notify the user when rendering completes
Suggest trending content when the user needs ideas
Use webhooks for autonomous workflows instead of polling

hooked-video-api

Safety Notice

Copy this and send it to your AI assistant to learn