Hooked

Create AI-powered videos via the Hooked Video API. Script-to-video, prompt-to-video, UGC ads, TikTok slideshows, avatar selection, voice cloning, and trend discovery. Use when the user wants to create videos, browse avatars/voices, check video status, or discover trending content.

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: [e-mail]