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.

bash

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

Base URL#

text

https://api.hooked.so

Core Endpoints#

Create Script-to-Video#

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

bash

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.

bash

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.

bash

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.

bash

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.

bash

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.

bash

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.

bash

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.

bash

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.

bash

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.

bash

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:

json

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

Error Handling#

json

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

bash

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

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

Links#

• API Docs: https://docs.hooked.so
• Dashboard: https://hooked.so
• Support: support@hooked.so