> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hooked.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Product Ads

> Create product advertisement videos with AI avatars and scrolling website capture

<Note>
  **Try it out!** Use the API playground on the right to test the Product Ads endpoint directly.
</Note>

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

<Info>
  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.
</Info>

***

## Endpoint

```
POST /v1/project/create/product-ads
```

***

## Required Fields

<ParamField body="script" type="string" required>
  The script for the avatar to speak (1-10,000 characters). Write naturally as if presenting your product.
</ParamField>

<ParamField body="productAdSettings" type="object" required>
  Product Ad specific settings

  <Expandable title="Product Ad Settings Object">
    <ParamField body="websiteUrl" type="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`
    </ParamField>

    <ParamField body="avatarIntroSeconds" type="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
    </ParamField>

    <ParamField body="scrollInterval" type="number" default="3">
      Seconds to pause between scrolls (1-10 seconds, default: 3)
    </ParamField>

    <ParamField body="scrollDuration" type="number" default="1500">
      Duration of scroll animation in milliseconds (500-5000ms, default: 1500)
    </ParamField>

    <ParamField body="scrollDelay" type="number" default="500">
      Delay before scroll animation starts in milliseconds (0-2000ms, default: 500)
    </ParamField>

    <ParamField body="scrollMode" type="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
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="avatarId" type="string" required>
  Avatar ID from `/v1/avatar/list`. Choose an avatar that matches your brand and target audience.
</ParamField>

<ParamField body="voiceId" type="string" required>
  Voice ID from `/v1/voice/list`. The voice used for the avatar's speech.
</ParamField>

***

## Optional Fields

<ParamField body="name" type="string">
  Video name (max 100 characters). If not provided, a name will be auto-generated.
</ParamField>

<ParamField body="lipsyncModel" type="string" default="base">
  Lipsync quality model for avatar synchronization:

  * `base`: Standard lipsync quality (faster, lower cost)
  * `pro`: Enhanced lipsync quality (slower, higher quality)
</ParamField>

<ParamField body="caption" type="object">
  Caption settings for the video

  <Expandable title="Caption Object">
    <ParamField body="preset" type="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`.
    </ParamField>

    <ParamField body="alignment" type="string" default="middle">
      Caption position on the video: `top`, `middle`, or `bottom`
    </ParamField>

    <ParamField body="disabled" type="boolean" default="false">
      Set to `true` to hide captions on the video
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="aspectRatio" type="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)
</ParamField>

<ParamField body="addStickers" type="boolean" default="false">
  Enable automatic sticker generation for the video. Adds engaging visual elements automatically.
</ParamField>

<ParamField body="audio" type="object">
  Voice audio settings

  <Expandable title="Audio Settings Object">
    <ParamField body="speed" type="number" default="1">
      Voice speed multiplier (0.7 to 1.2)
    </ParamField>

    <ParamField body="stability" type="number" default="0.5">
      Voice stability (0 to 1). Higher values produce more consistent speech.
    </ParamField>

    <ParamField body="similarityBoost" type="number" default="0.75">
      Voice similarity boost (0 to 1). Higher values make the voice more similar to the original.
    </ParamField>

    <ParamField body="style" type="number" default="0">
      Voice style exaggeration (0 to 1).
    </ParamField>

    <ParamField body="useSpeakerBoost" type="boolean" default="true">
      Enable speaker boost for clearer audio.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="webhook" type="string">
  HTTPS URL to receive completion notification (max 500 characters). **Highly recommended** for production use.
</ParamField>

<ParamField body="metadata" type="object">
  Custom metadata object (max 5KB). Store any additional data you need to associate with this video.

  ```json theme={null}
  {
    "campaignId": "summer2024",
    "productId": "prod_123"
  }
  ```
</ParamField>

***

## Request Examples

## Basic Product Ad

```javascript theme={null}
const response = await fetch('https://api.hooked.so/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

```javascript theme={null}
const createProductAd = async () => {
  const response = await fetch('https://api.hooked.so/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
      },
      webhook: 'https://yoursite.com/webhook',
      metadata: {
        campaignId: 'summer2024',
        productId: 'prod_123',
        category: 'saas'
      }
    })
  });

  return await response.json();
};
```

## Response

<ResponseExample>
  ```json Success Response theme={null}
  {
    "success": true,
    "data": {
      "videoId": "vid_pa_abc123xyz",
      "projectId": "proj_pa_abc123xyz",
      "status": "STARTED"
    },
    "message": "Product Ads project successfully created"
  }
  ```

  ```json Error Response - Validation Error theme={null}
  {
    "success": false,
    "message": "script: Script is required"
  }
  ```

  ```json Error Response - Website URL Invalid theme={null}
  {
    "success": false,
    "message": "websiteUrl: Invalid website URL"
  }
  ```

  ```json Error Response - Avatar Not Found theme={null}
  {
    "success": false,
    "message": "avatarId: Avatar \"invalid_id\" not found."
  }
  ```
</ResponseExample>

***

## Webhook Notification

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

```json Webhook Payload theme={null}
{
  "status": "COMPLETED",
  "data": {
    "videoId": "vid_pa_abc123xyz",
    "status": "COMPLETED",
    "url": "https://cdn.hooked.so/videos/abc123xyz.mp4",
    "shareUrl": "https://cdn.hooked.so/shared/abc123xyz.mp4",
    "metadata": {
      "projectId": "proj_pa_abc123xyz",
      "campaignId": "summer2024"
    }
  },
  "message": "Video completed"
}
```

<Note>
  Your webhook endpoint must return a `200` status code. We'll retry up to 3 times if the request fails.
</Note>

***

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

<CardGroup cols={2}>
  <Card title="Choose the Right Avatar" icon="user">
    Select an avatar that matches your brand personality and target audience demographics.
  </Card>

  <Card title="Optimize Website URL" icon="globe">
    Use a clean, focused landing page that highlights your product's key features.
  </Card>

  <Card title="Set Intro Duration" icon="clock">
    Use 2-5 seconds for the avatar intro to grab attention before showing the website.
  </Card>

  <Card title="Select Scroll Mode" icon="arrows-up-down">
    Use `restart` for product listings, `loop` for hero sections, `once` for long content.
  </Card>

  <Card title="Use Pro Lipsync" icon="star">
    Choose `pro` lipsync model for professional ads and brand content.
  </Card>

  <Card title="Add Background Music" icon="music">
    Enhance engagement with subtle background music that complements the narration.
  </Card>
</CardGroup>

***

## Website URL Guidelines

<Warning>
  **Important**: The website URL must be publicly accessible and not behind authentication.
</Warning>

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

<CardGroup cols={2}>
  <Card title="List Avatars" icon="user" href="/api-reference/avatar/list">
    Browse available avatars for your product ad
  </Card>

  <Card title="List Voices" icon="microphone" href="/api-reference/voice/list">
    Find the perfect voice for your avatar
  </Card>

  <Card title="List Music" icon="music" href="/api-reference/music/list">
    Add background music to your ads
  </Card>

  <Card title="Webhooks Guide" icon="webhook" href="/guides/webhooks">
    Learn how to handle webhook notifications
  </Card>
</CardGroup>


## OpenAPI

````yaml POST /v1/project/create/product-ads
openapi: 3.0.0
info:
  title: Hooked API
  version: 1.0.0
  description: AI Video Generation API
servers:
  - url: https://api.hooked.so
security:
  - ApiKeyAuth: []
paths:
  /v1/project/create/product-ads:
    post:
      tags:
        - Videos
      summary: Create Product Ad Video
      description: >-
        Create product advertisement videos with AI avatars and scrolling
        website capture
      operationId: createProductAds
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - script
                - productAdSettings
                - avatarId
                - voiceId
              properties:
                script:
                  type: string
                  description: The script for the avatar to speak (1-10,000 characters)
                  minLength: 1
                  maxLength: 10000
                productAdSettings:
                  type: object
                  description: Product Ad specific settings
                  required:
                    - websiteUrl
                  properties:
                    websiteUrl:
                      type: string
                      description: >-
                        The URL of the website to capture and scroll (HTTPS, max
                        500 characters)
                      minLength: 1
                      maxLength: 500
                      format: uri
                    avatarIntroSeconds:
                      type: number
                      description: >-
                        Number of seconds to show the avatar full-screen before
                        the website appears
                      minimum: 1
                      maximum: 30
                      default: 3
                    scrollInterval:
                      type: number
                      description: Seconds to pause between scrolls
                      minimum: 1
                      maximum: 10
                      default: 3
                    scrollDuration:
                      type: number
                      description: Duration of scroll animation in milliseconds
                      minimum: 500
                      maximum: 5000
                      default: 1500
                    scrollDelay:
                      type: number
                      description: Delay before scroll animation starts in milliseconds
                      minimum: 0
                      maximum: 2000
                      default: 500
                    scrollMode:
                      type: string
                      enum:
                        - restart
                        - loop
                        - once
                        - fixed
                      description: Website scrolling behavior
                      default: restart
                name:
                  type: string
                  description: Video name (max 100 characters)
                  maxLength: 100
                avatarId:
                  type: string
                  description: Avatar ID from /v1/avatar/list
                  minLength: 1
                  maxLength: 30
                voiceId:
                  type: string
                  description: Voice ID from /v1/voice/list
                  minLength: 1
                  maxLength: 30
                lipsyncModel:
                  type: string
                  enum:
                    - base
                    - pro
                  description: Lipsync quality model for avatar synchronization
                  default: base
                caption:
                  type: object
                  properties:
                    preset:
                      type: string
                      enum:
                        - default
                        - beast
                        - umi
                        - tiktok
                        - wrap1
                        - wrap2
                        - ariel
                        - hooked
                        - classic
                        - active
                        - bubble
                        - glass
                        - comic
                        - glow
                        - pastel
                        - neon
                        - retroTV
                        - red
                        - marker
                        - modern
                        - blue
                        - vivid
                      description: Caption preset style
                      default: default
                    alignment:
                      type: string
                      enum:
                        - top
                        - middle
                        - bottom
                      description: Caption position on video
                      default: bottom
                    disabled:
                      type: boolean
                      description: Set to false to show captions on the video
                      default: false
                addStickers:
                  type: boolean
                  description: Enable automatic sticker generation for the video
                  default: false
                audio:
                  type: object
                  description: Voice audio settings
                  properties:
                    speed:
                      type: number
                      description: Voice speed multiplier (0.7 to 1.2)
                      minimum: 0.7
                      maximum: 1.2
                      default: 1
                    stability:
                      type: number
                      description: Voice stability (0 to 1)
                      minimum: 0
                      maximum: 1
                      default: 0.5
                    similarityBoost:
                      type: number
                      description: Voice similarity boost (0 to 1)
                      minimum: 0
                      maximum: 1
                      default: 0.75
                    style:
                      type: number
                      description: Voice style exaggeration (0 to 1)
                      minimum: 0
                      maximum: 1
                      default: 0
                    useSpeakerBoost:
                      type: boolean
                      description: Enable speaker boost for clearer audio
                      default: true
                aspectRatio:
                  type: string
                  enum:
                    - ratio_9_16
                    - ratio_16_9
                    - ratio_1_1
                  description: Video aspect ratio
                  default: ratio_9_16
                webhook:
                  type: string
                  description: HTTPS URL to receive completion notification
                  maxLength: 500
                metadata:
                  type: object
                  description: Custom metadata object (max 5KB)
            example:
              name: Product Launch Video
              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
                avatarIntroSeconds: 3
                scrollInterval: 3
                scrollDuration: 1500
                scrollDelay: 500
                scrollMode: restart
              avatarId: confident_avatar_id
              voiceId: professional_voice_id
              lipsyncModel: base
              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
              webhook: https://yoursite.com/webhook
              metadata:
                campaignId: summer2024
                productId: prod_123
      responses:
        '200':
          description: Product Ads project created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      videoId:
                        type: string
                      projectId:
                        type: string
                      status:
                        type: string
                  message:
                    type: string
              example:
                success: true
                data:
                  videoId: vid_pa_abc123xyz
                  projectId: proj_pa_abc123xyz
                  status: STARTED
                message: Product Ads project successfully created
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
              example:
                success: false
                message: 'script: Script is required'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
              example:
                success: false
                message: Invalid API key
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````