Product Ads

Try it out! Use the API playground on the right to test the Product Ads endpoint directly.

Overview

Product Ads combine AI avatars with automatic website scrolling to create engaging product advertisement videos. The avatar presents your product while the website scrolls in the background, showcasing your product page. This format is ideal for:

Product launches and demos
E-commerce advertising
SaaS product showcases
Website feature highlights
Landing page promotions

Product Ads automatically capture your website and create a scrolling video that syncs with the avatar’s narration. The website appears behind the avatar after a customizable intro duration.

Endpoint

POST /v1/project/create/product-ads

Required Fields

script

string

required

The script for the avatar to speak (1-10,000 characters). Write naturally as if presenting your product.

productAdSettings

object

required

Product Ad specific settings

Show Product Ad Settings Object

websiteUrl

string

required

The URL of the website to capture and scroll. Must be a valid HTTPS URL (max 500 characters).Example: https://example.com/product-page

avatarIntroSeconds

number

default:"3"

Number of seconds to show the avatar full-screen before the website appears behind it (alias: showWebsiteAfter).

Minimum: 1 second
Maximum: 30 seconds
Default: 3 seconds

scrollInterval

number

default:"3"

Seconds to pause between scrolls (1-10 seconds, default: 3)

scrollDuration

number

default:"1500"

Duration of scroll animation in milliseconds (500-5000ms, default: 1500)

scrollDelay

number

default:"500"

Delay before scroll animation starts in milliseconds (0-2000ms, default: 500)

scrollMode

string

default:"restart"

Website scrolling behavior:

restart: Scroll down, jump to top when reaching bottom (default)
loop: Ping-pong scroll (down, then up, then down…)
once: Scroll down only, stay at bottom
fixed: No scroll, just capture the initial view

avatarId

string

required

Avatar ID from /v1/avatar/list. Choose an avatar that matches your brand and target audience.

voiceId

string

required

Voice ID from /v1/voice/list. The voice used for the avatar’s speech.

Optional Fields

name

string

Video name (max 100 characters). If not provided, a name will be auto-generated.

lipsyncModel

string

default:"base"

Lipsync quality model for avatar synchronization:

base: Standard lipsync quality (faster, lower cost)
pro: Enhanced lipsync quality (slower, higher quality)

caption

object

Caption settings for the video

Show Caption Object

preset

string

default:"default"

Caption preset style. Available presets: default, beast, umi, tiktok, wrap1, wrap2, ariel, hooked, classic, active, bubble, glass, comic, glow, pastel, neon, retroTV, red, marker, modern, blue, vivid.

alignment

string

default:"middle"

Caption position on the video: top, middle, or bottom

disabled

boolean

default:"false"

Set to true to hide captions on the video

aspectRatio

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)

language

string

default:"en"

Language code for the video (2 characters). Example: en, es

addStickers

boolean

default:"false"

Enable automatic sticker generation for the video. Adds engaging visual elements automatically.

audio

object

Voice audio settings

Show Audio Settings Object

speed

number

default:"1"

Voice speed multiplier (0.5 to 2.0)

stability

number

default:"0.5"

Voice stability (0 to 1). Higher values produce more consistent speech.

similarityBoost

number

default:"0.75"

Voice similarity boost (0 to 1). Higher values make the voice more similar to the original.

style

number

default:"0"

Voice style exaggeration (0 to 1).

useSpeakerBoost

boolean

default:"true"

Enable speaker boost for clearer audio.

webhook

string

HTTPS URL to receive completion notification (max 500 characters). Highly recommended for production use.

metadata

object

Custom metadata object (max 5KB). Store any additional data you need to associate with this video.

{
  "campaignId": "summer2024",
  "productId": "prod_123"
}

Request Examples

Basic Product Ad

const response = await fetch('https://api.tryhooked.ai/v1/project/create/product-ads', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.HOOKED_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    script: 'Introducing our revolutionary product that will change how you work. With cutting-edge features and an intuitive design, it\'s everything you need to boost your productivity.',
    productAdSettings: {
      websiteUrl: 'https://example.com/product'
    },
    avatarId: 'confident_avatar_id',
    voiceId: 'professional_voice_id'
  })
});

const data = await response.json();
console.log('Video ID:', data.data.videoId);
console.log('Project ID:', data.data.projectId);

Product Ad with Custom Settings

const createProductAd = async () => {
  const response = await fetch('https://api.tryhooked.ai/v1/project/create/product-ads', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.HOOKED_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Product Launch Video',
      script: 'Discover the future of productivity with our latest SaaS platform. Experience seamless workflow management, real-time collaboration, and intelligent automation - all in one powerful tool.',
      productAdSettings: {
        websiteUrl: 'https://saas-product.com/features',
        avatarIntroSeconds: 5,
        scrollMode: 'loop'
      },
      avatarId: 'enthusiastic_avatar_id',
      voiceId: 'confident_voice_id',
      lipsyncModel: 'pro',
      aspectRatio: 'ratio_9_16',
      caption: {
        preset: 'modern',
        alignment: 'bottom',
        disabled: false
      },
      addStickers: true,
      audio: {
        speed: 1,
        stability: 0.5,
        similarityBoost: 0.75,
        style: 0,
        useSpeakerBoost: true
      },
      language: 'en',
      webhook: 'https://yoursite.com/webhook',
      metadata: {
        campaignId: 'summer2024',
        productId: 'prod_123',
        category: 'saas'
      }
    })
  });

  return await response.json();
};

Response

{
  "success": true,
  "data": {
    "videoId": "vid_pa_abc123xyz",
    "projectId": "proj_pa_abc123xyz",
    "status": "STARTED"
  },
  "message": "Product Ads project successfully created"
}

Webhook Notification

When your video is ready, we’ll POST to your webhook URL:

Webhook Payload

{
  "status": "COMPLETED",
  "data": {
    "videoId": "vid_pa_abc123xyz",
    "status": "COMPLETED",
    "url": "https://cdn.tryhooked.ai/videos/abc123xyz.mp4",
    "shareUrl": "https://cdn.tryhooked.ai/shared/abc123xyz.mp4",
    "metadata": {
      "projectId": "proj_pa_abc123xyz",
      "campaignId": "summer2024"
    }
  },
  "message": "Video completed"
}

Your webhook endpoint must return a 200 status code. We’ll retry up to 3 times if the request fails.

Scroll Modes

Available scroll modes for website behavior:

Mode	Description	Use Case
`restart`	Scroll down, jump to top when reaching bottom	Product listings, feature pages
`loop`	Ping-pong scroll (down then up, then down…)	Landing pages, hero sections
`once`	Scroll down only, stay at bottom	Long-form content, testimonials
`fixed`	No scroll, just capture initial view	Static pages, splash screens

Lipsync Models

Model	Quality	Speed	Cost	Best For
`base`	Standard	Faster	Lower	Quick content, social media
`pro`	Enhanced	Slower	Higher	Professional ads, brand content

Caption Presets

Available caption presets for the caption.preset field:

Preset	Description
`default`	Default caption style with bold text and shadow effects
`beast`	Bold uppercase style with Komika font
`umi`	Yellow glowing text style
`tiktok`	Viral & trendy style, perfect for social media
`wrap1`	Wrapped style with red background highlight
`wrap2`	Wrapped style with blue background highlight (uppercase)
`ariel`	Bold uppercase style with purple highlight
`hooked`	Brand style with purple background
`classic`	Clean, simple captions with black background
`active`	Green background with bold text
`bubble`	White background bubble style
`glass`	Glassmorphic transparency effect
`comic`	Comic Sans font with colorful style
`glow`	Pink and orange glow effects
`pastel`	Soft pastel pink background
`neon`	Green neon glow effect
`retroTV`	Retro TV style with cyan glow
`red`	Red glow effect with white text
`marker`	Yellow marker/highlighter style
`modern`	Contemporary white background style
`blue`	Blue background style
`vivid`	Vibrant pink background with uppercase text

Best Practices

Choose the Right Avatar

Select an avatar that matches your brand personality and target audience demographics.

Optimize Website URL

Use a clean, focused landing page that highlights your product’s key features.

Set Intro Duration

Use 2-5 seconds for the avatar intro to grab attention before showing the website.

Select Scroll Mode

Use restart for product listings, loop for hero sections, once for long content.

Use Pro Lipsync

Choose pro lipsync model for professional ads and brand content.

Add Background Music

Enhance engagement with subtle background music that complements the narration.

Website URL Guidelines

Important: The website URL must be publicly accessible and not behind authentication.

Best Practices

Use HTTPS URLs only
Ensure the website loads quickly
Use mobile-responsive pages
Avoid pages with heavy animations or popups
Test the URL in an incognito browser window

Recommended Page Types

Product landing pages
Feature highlight pages
Pricing pages
Homepage hero sections
Demo pages

Error Handling

Error	Description	Solution
`script: Script is required`	Missing or empty script	Add the `script` field with your narration
`script: Script cannot exceed 10000 characters`	Script too long	Shorten your script to under 10,000 characters
`productAdSettings.websiteUrl: Website URL is required`	Missing website URL	Add the `websiteUrl` field in `productAdSettings`
`productAdSettings.websiteUrl: Invalid website URL`	Invalid URL format	Ensure URL starts with `https://` and is valid
`avatarId: Avatar "xxx" not found`	Invalid avatar ID	Use a valid avatar ID from `/v1/avatar/list`
`voiceId: Voice "xxx" not found`	Invalid voice ID	Use a valid voice ID from `/v1/voice/list`
`productAdSettings.avatarIntroSeconds: Number must be between 1 and 30`	Invalid intro duration	Use a value between 1 and 30 seconds in `productAdSettings.avatarIntroSeconds`
`Not enough credits`	Insufficient credits	Top up your account credits

Next Steps

List Avatars

Browse available avatars for your product ad

List Voices

Find the perfect voice for your avatar

List Music

Add background music to your ads

Webhooks Guide

Learn how to handle webhook notifications

Authorizations

x-api-key

string

header

required

Body

application/json

script

string

required

The script for the avatar to speak (1-10,000 characters)

Required string length: 1 - 10000

productAdSettings

object

required

Product Ad specific settings

Show child attributes

avatarId

string

required

Avatar ID from /v1/avatar/list

Required string length: 1 - 30

voiceId

string

required

Voice ID from /v1/voice/list

Required string length: 1 - 30

name

string

Video name (max 100 characters)

Maximum string length: 100

lipsyncModel

enum<string>

default:base

Lipsync quality model for avatar synchronization

Available options:

base,

pro

caption

object

Show child attributes

addStickers

boolean

default:false

Enable automatic sticker generation for the video

audio

object

Voice audio settings

Show child attributes

aspectRatio

enum<string>

default:ratio_9_16

Video aspect ratio

Available options:

ratio_9_16,

ratio_16_9,

ratio_1_1

language

string

default:en

Language code (2 characters)

Required string length: 2

webhook

string

HTTPS URL to receive completion notification

Maximum string length: 500

metadata

object

Custom metadata object (max 5KB)

Response

Product Ads project created successfully

success

boolean

data

object

Show child attributes

message

string

Getting Started

Resources

Videos

Templates

Overview

Endpoint

Required Fields

Optional Fields

Request Examples

Basic Product Ad

Product Ad with Custom Settings

Response

Webhook Notification

Scroll Modes

Lipsync Models

Caption Presets

Best Practices

Choose the Right Avatar

Optimize Website URL

Set Intro Duration

Select Scroll Mode

Use Pro Lipsync

Add Background Music

Website URL Guidelines

Best Practices

Recommended Page Types

Error Handling

Next Steps

List Avatars

List Voices

List Music

Webhooks Guide

Authorizations

Body

Response

Getting Started

Resources

Videos

Templates

​Overview

​Endpoint

​Required Fields

​Optional Fields

​Request Examples

​Basic Product Ad

​Product Ad with Custom Settings

​Response

​Webhook Notification

​Scroll Modes

​Lipsync Models

​Caption Presets

​Best Practices

Choose the Right Avatar

Optimize Website URL

Set Intro Duration

Select Scroll Mode

Use Pro Lipsync

Add Background Music

​Website URL Guidelines

​Best Practices

​Recommended Page Types

​Error Handling

​Next Steps

List Avatars

List Voices

List Music

Webhooks Guide

Authorizations

Body

Response

Overview

Endpoint

Required Fields

Optional Fields

Request Examples

Basic Product Ad

Product Ad with Custom Settings

Response

Webhook Notification

Scroll Modes

Lipsync Models

Caption Presets

Best Practices

Website URL Guidelines

Best Practices

Recommended Page Types

Error Handling

Next Steps