hooked-video-api

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