Skip to main content
POST
Create Hook + Demo Video
Try it out! Use the API playground on the right to test the Hook + Demo endpoint directly. The schema is pre-configured for hook_demo type.

Overview

Hook + Demo videos are perfect for creating attention-grabbing content with text hooks displayed over demo media (images or videos). This format is ideal for:
  • Product demonstrations with compelling hooks
  • Social media content with text overlays
  • Marketing videos with call-to-action text
  • Quick promotional clips
Hook + Demo videos are generated in real-time, making them one of the fastest video types to create.

Endpoint

The endpoint is the same for all video types. Set type: "hook_demo" to create a Hook + Demo video.

Required Fields

string
required
Avatar template ID from /v1/avatar/list. This is the avatar that will appear in your Hook + Demo video.
string
required
The hook text to display on the video (1-5,000 characters). This is the main text that will appear as an overlay on your media.

Optional Fields

string
Video name (max 100 characters)
array
Background media IDs (max 50). Array of media ID strings. These are the images or videos that will play behind your text hook.
string
Music template ID from /v1/music/list or custom music ID.
object
Text display settings for the hook overlay
string
default:"ratio_9_16"
Video aspect ratio:
  • ratio_9_16: Vertical (TikTok, Reels, Shorts) - Recommended
  • ratio_16_9: Horizontal (YouTube)
  • ratio_1_1: Square (Instagram)
string
HTTPS URL to receive completion notification (max 500 characters). Highly recommended for production use.
object
Custom metadata object (max 5KB). Store any additional data you need to associate with this video.

Request Examples

Basic Hook + Demo

With Background Media

With Custom Colors and Metadata


Response


Webhook Notification

When your video is ready, we’ll POST to your webhook URL:
Webhook Payload
Your webhook endpoint must return a 200 status code. We’ll retry up to 3 times if the request fails.

Text Presets

Available text presets for the textSettings.preset field:
You can override the preset colors using textColor and backgroundColor while keeping the preset’s font styling and animations.

Best Practices

Keep Hooks Short

Effective hooks are 5-15 words. Get attention quickly.

Use High-Quality Media

Upload media at least 1080p for best results. MP4 for videos, JPG/PNG for images.

Match Aspect Ratio

Ensure your media matches your target aspect ratio to avoid cropping.

Use Webhooks

Always use webhooks in production instead of polling for video status.

Common Use Cases

Create attention-grabbing hooks for TikTok, Instagram Reels, or YouTube Shorts.
Showcase products with compelling text overlays.
Highlight customer quotes or testimonials.

Error Handling


Next Steps

List Videos

View all your created videos

Get Video Details

Check video status and download URL

Webhooks Guide

Learn how to handle webhook notifications

Best Practices

Tips for creating effective videos

Authorizations

x-api-key
string
header
required

Body

application/json
avatarId
string
required

Avatar template ID from /v1/avatar/list

text
string
required

The hook text to display on the video (1-5,000 characters)

Required string length: 1 - 5000
name
string

Video name (max 100 characters)

Maximum string length: 100
textSettings
object

Text settings object

media
string[]

Background media items (max 50)

Maximum array length: 50

Unique media ID

aspectRatio
enum<string>
default:ratio_9_16

Video aspect ratio

Available options:
ratio_9_16,
ratio_16_9,
ratio_1_1
musicId
string

Music template ID from /v1/music/list or custom music ID.

webhook
string

HTTPS URL to receive completion notification

Maximum string length: 500
metadata
object

Custom metadata object (max 5KB)

Response

Hook Demo created successfully

success
boolean
projectId
string
data
object
message
string