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

# UGC Ads

> Create authentic user-generated content style ads with AI avatars

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

## Overview

UGC Ads videos are perfect for creating authentic-looking user-generated content style advertisements. This format is ideal for:

* Social media advertising (TikTok, Instagram Reels, Facebook)
* Product reviews and testimonials
* Influencer-style marketing content
* Authentic brand storytelling

<Info>
  UGC Ads use AI avatars with voice synthesis to create realistic spokesperson videos that feel natural and engaging.
</Info>

***

## Endpoint

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

***

## Required Fields

<ParamField body="script" type="string" required>
  The script for the avatar to speak (1-10,000 characters). Write naturally as if a real person is speaking.
</ParamField>

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

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

<ParamField body="media" type="array" required>
  B-roll media IDs (min 1, max 50). Array of media ID strings. At least one media item is required. The media must already be uploaded to your account.
</ParamField>

***

## Optional Fields

<ParamField body="name" type="string">
  Video name (max 100 characters)
</ParamField>

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

  * `base`: Standard quality, faster processing
  * `pro`: Higher quality, more accurate synchronization
</ParamField>

<ParamField body="adSettings" type="object">
  Ad-specific settings for B-roll behavior

  <Expandable title="Ad Settings Object">
    <ParamField body="bRollType" type="string" default="down">
      B-roll display type:

      * `down`: Avatar on top, B-roll on bottom
      * `up`: B-roll on top, avatar on bottom
      * `left`: Avatar on right, B-roll on left
      * `right`: Avatar on left, B-roll on right
      * `rounded-cover`: Rounded avatar overlay on B-roll
      * `full-width`: B-roll covers entire screen, avatar hidden
    </ParamField>

    <ParamField body="removeAvatarBackground" type="boolean" default="false">
      Remove the avatar's background for a cleaner look
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="musicId" type="string">
  Music ID from `/v1/music/list` for background music.
</ParamField>

<ParamField body="aspectRatio" type="string">
  Video aspect ratio:

  * `ratio_9_16`: Vertical (TikTok, Reels, Shorts) - **Recommended for UGC**
  * `ratio_16_9`: Horizontal (YouTube)
  * `ratio_1_1`: Square (Instagram)
</ParamField>

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

  <Expandable title="Caption Object">
    <ParamField body="preset" type="string" default="classic">
      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`. See the Caption Presets section below for details.
    </ParamField>

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

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

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

  <Expandable title="Audio Settings Object">
    <ParamField body="speed" type="number" default="1.0">
      Voice speed multiplier (0.7 to 1.2). Higher values make the voice faster.
    </ParamField>

    <ParamField body="stability" type="number" default="0.7">
      Voice stability (0 to 1). Higher values make the voice more consistent and less variable.
    </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 voice sample.
    </ParamField>

    <ParamField body="style" type="number" default="0">
      Voice style exaggeration (0 to 1). Higher values add more style and emotion to the voice.
    </ParamField>

    <ParamField body="useSpeakerBoost" type="boolean" default="true">
      Enable speaker boost for clearer audio output.
    </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",
    "productSku": "SKU-12345",
    "customField": "any value"
  }
  ```
</ParamField>

***

## Request Examples

### Basic UGC Ad

```json theme={null}
{
  "script": "I've been using this product for a month now and I'm obsessed! Let me show you why it's so amazing.",
  "avatarId": "avatar_influencer_01",
  "voiceId": "enthusiastic_voice_id",
  "media": ["product_demo"]
}
```

### Complete UGC Ad

```json theme={null}
{
  "name": "Brand Campaign Ad",
  "script": "Stop scrolling! I need to tell you about something that literally changed my morning routine. I was skeptical at first, but after trying this for just one week... I'm never going back.",
  "avatarId": "avatar_professional_01",
  "voiceId": "confident_voice_id",
  "lipsyncModel": "pro",
  "adSettings": {
    "bRollType": "down",
    "removeAvatarBackground": false
  },
  "media": ["demo_video", "product_image"],
  "musicId": "trending_music_01",
  "aspectRatio": "ratio_9_16",
  "caption": {
    "preset": "beast",
    "alignment": "bottom",
    "disabled": false
  },
  "webhook": "https://api.yoursite.com/hooks/hooked",
  "metadata": {
    "campaignId": "Q1-2024-ugc",
    "abTestVariant": "B",
    "internalRef": "MKT-5678"
  }
}
```

### UGC Ad with Audio Settings

```json theme={null}
{
  "name": "Product Review with Custom Audio",
  "script": "I've been testing this product for weeks and I'm blown away by the results. Let me show you exactly what makes it special.",
  "avatarId": "avatar_influencer_01",
  "voiceId": "enthusiastic_voice_id",
  "lipsyncModel": "pro",
  "adSettings": {
    "bRollType": "rounded-cover",
    "removeAvatarBackground": true
  },
  "media": ["product_demo", "unboxing_video"],
  "musicId": "trending_music_01",
  "aspectRatio": "ratio_9_16",
  "caption": {
    "preset": "tiktok",
    "alignment": "bottom",
    "disabled": false
  },
  "audio": {
    "speed": 1.1,
    "stability": 0.7,
    "similarityBoost": 0.8,
    "style": 0.3,
    "useSpeakerBoost": true
  },
  "webhook": "https://api.yoursite.com/hooks/hooked",
  "metadata": {
    "campaignId": "product-review-2024",
    "productId": "PROD-12345"
  }
}
```

***

## Response

<ResponseExample>
  ```json Success Response theme={null}
  {
    "success": true,
    "data": {
      "videoId": "vid_ugc_abc123xyz",
      "projectId": "proj_ugc_abc123xyz",
      "status": "STARTED"
    },
    "message": "UGC ad successfully created"
  }
  ```

  ```json Error Response - Validation Error theme={null}
  {
    "success": false,
    "message": "script: Script must be at least 1 character"
  }
  ```

  ```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_ugc_abc123xyz",
    "status": "COMPLETED",
    "url": "https://cdn.hooked.so/videos/abc123xyz.mp4",
    "shareUrl": "https://cdn.hooked.so/shared/abc123xyz.mp4",
    "metadata": {
      "projectId": "proj_ugc_abc123xyz",
      "campaignId": "Q1-2024-ugc",
      "abTestVariant": "B"
    }
  },
  "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>

***

## 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 (Default)   |
| `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              |

***

## B-Roll Types

Available B-roll display options for `adSettings.bRollType`:

| Type            | Description                                                             |
| --------------- | ----------------------------------------------------------------------- |
| `down`          | Split screen down - Avatar on top half, B-roll on bottom half (Default) |
| `up`            | Split screen up - B-roll on top half, avatar on bottom half             |
| `left`          | Split screen left - Avatar on right, B-roll on left - balanced layout   |
| `right`         | Split screen right - Avatar on left, B-roll on right - balanced layout  |
| `rounded-cover` | Rounded - Rounded avatar overlay on B-roll background                   |
| `full-width`    | Full screen - B-roll covers entire screen, avatar hidden                |

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Write Naturally" icon="pen">
    Scripts should sound conversational. Use contractions, pauses, and natural speech patterns.
  </Card>

  <Card title="Hook First" icon="bolt">
    Start with an attention-grabbing hook in the first 2-3 seconds to stop scrolling.
  </Card>

  <Card title="Keep It Short" icon="clock">
    15-60 seconds is ideal for social media ads. Get to the point quickly.
  </Card>

  <Card title="Use B-Roll" icon="images">
    Add product shots or demos to keep viewers engaged and showcase your product.
  </Card>
</CardGroup>

***

## Common Use Cases

<AccordionGroup>
  <Accordion title="Product Reviews" icon="star">
    Create authentic-looking product review videos.

    ```json theme={null}
    {
      "name": "5-Star Review",
      "script": "I bought this not expecting much, but WOW! This exceeded all my expectations. The build quality is amazing and it works exactly as advertised. 10/10 would recommend!",
      "avatarId": "avatar_casual_01",
      "voiceId": "enthusiastic_voice_id",
      "media": [
        {
          "id": "product_review",
          "type": "video",
          "url": "https://example.com/review.mp4"
        }
      ],
      "caption": {
        "preset": "tiktok",
        "alignment": "bottom",
        "disabled": false
      }
    }
    ```
  </Accordion>

  <Accordion title="Testimonials" icon="quote-left">
    Showcase customer success stories.

    ```json theme={null}
    {
      "name": "Customer Testimonial",
      "script": "Before I found this product, I was struggling every day. Now? My life is completely different. I can't imagine going back to how things were before.",
      "avatarId": "avatar_professional_01",
      "voiceId": "enthusiastic_voice_id",
      "media": ["testimonial_broll"],
      "caption": {
        "preset": "modern",
        "alignment": "bottom",
        "disabled": false
      },
      "adSettings": {
        "removeAvatarBackground": true
      }
    }
    ```
  </Accordion>

  <Accordion title="Unboxing Videos" icon="box-open">
    Create engaging unboxing content.

    ```json theme={null}
    {
      "name": "Unboxing Experience",
      "script": "Okay so my package just arrived and I'm SO excited to open this with you! Let's see what's inside... Oh my gosh, look at this packaging! They really went all out!",
      "avatarId": "avatar_enthusiastic_01",
      "voiceId": "enthusiastic_voice_id",
      "caption": {
        "preset": "modern",
        "alignment": "bottom",
        "disabled": false
      },
      "media": ["unbox_1"],
      "adSettings": {
        "bRollType": "down"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Error Handling

| Error                                         | Description             | Solution                                     |
| --------------------------------------------- | ----------------------- | -------------------------------------------- |
| `script: Script must be at least 1 character` | Missing or empty script | Add the `script` field with your ad content  |
| `avatarId: Avatar not found`                  | Invalid avatar ID       | Use a valid avatar ID from `/v1/avatar/list` |
| `voiceId: Voice not found`                    | Invalid voice ID        | Use a valid voice ID from `/v1/voice/list`   |
| `webhook: Must be a valid HTTPS URL`          | Invalid webhook URL     | Ensure webhook URL starts with `https://`    |
| `media: Cannot have more than 50 media items` | Too many media items    | Reduce media array to 50 items or fewer      |
| `Not enough credits`                          | Insufficient credits    | Top up your account credits                  |

***

## Next Steps

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

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

  <Card title="List Videos" icon="list" href="/api-reference/video/list">
    View all your created videos
  </Card>

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


## OpenAPI

````yaml POST /v1/project/create/ugc-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/ugc-ads:
    post:
      tags:
        - Videos
      summary: Create UGC Ad Video
      description: Create authentic user-generated content style ads with AI avatars
      operationId: createUGCAd
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - script
                - avatarId
                - voiceId
                - media
              properties:
                script:
                  type: string
                  description: The script for the avatar to speak (1-10,000 characters)
                  minLength: 1
                  maxLength: 10000
                name:
                  type: string
                  description: Video name (max 100 characters)
                  maxLength: 100
                avatarId:
                  type: string
                  description: Avatar ID from /v1/avatar/list
                  maxLength: 30
                voiceId:
                  type: string
                  description: >-
                    Voice ID from /v1/voice/list. If not provided, uses avatar's
                    default voice.
                  maxLength: 30
                lipsyncModel:
                  type: string
                  enum:
                    - base
                    - pro
                  description: Lipsync model
                  default: base
                musicId:
                  type: string
                  description: Music ID from /v1/music/list for background music
                  maxLength: 30
                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: classic
                    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: true
                media:
                  type: array
                  description: >-
                    B-roll media IDs (min 1, max 50). Array of media ID strings.
                    At least one media item is required.
                  minItems: 1
                  maxItems: 50
                  items:
                    type: string
                    description: Unique media ID
                adSettings:
                  type: object
                  properties:
                    bRollType:
                      type: string
                      enum:
                        - down
                        - up
                        - left
                        - right
                        - rounded-cover
                        - full-width
                      description: B-roll display type
                      default: down
                    removeAvatarBackground:
                      type: boolean
                      description: Remove the avatar's background
                      default: false
                aspectRatio:
                  type: string
                  enum:
                    - ratio_9_16
                    - ratio_16_9
                    - ratio_1_1
                  description: Video aspect ratio
                  default: ratio_9_16
                audio:
                  type: object
                  properties:
                    speed:
                      type: number
                      description: Speed of the audio (0.5-2.0)
                      default: 1
                    stability:
                      type: number
                      description: Stability of the audio (0-1)
                      default: 0.5
                    similarityBoost:
                      type: number
                      description: Similarity boost of the audio (0-1)
                      default: 0.75
                    style:
                      type: number
                      description: Style of the audio (0-1)
                      default: 0
                    useSpeakerBoost:
                      type: boolean
                      description: Use speaker boost for the audio
                      default: true
                webhook:
                  type: string
                  description: HTTPS URL to receive completion notification
                  maxLength: 500
                metadata:
                  type: object
                  description: Custom metadata object (max 5KB)
            example:
              name: Product Review Ad
              script: >-
                Hey everyone! I just got this amazing product and I had to
                share. The quality is incredible and it's so easy to use!
              avatarId: avatar_casual_01
              voiceId: enthusiastic_voice_id
              musicId: music_lofi_01
              caption:
                preset: wrap1
                alignment: bottom
                disabled: false
              media:
                - product_video
                - product_image
              adSettings:
                bRollType: rounded-cover
                removeAvatarBackground: true
              aspectRatio: ratio_9_16
              webhook: https://yoursite.com/webhook
              metadata:
                campaignId: campaign_id
                variant: A
      responses:
        '200':
          description: UGC Ad 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_ugc_abc123xyz
                  projectId: proj_ugc_abc123xyz
                  status: STARTED
                message: UGC ad 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 must be at least 1 character'
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````