> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slidevid.ai/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="caption" type="object" required>
  Caption settings for the video

  <Expandable title="Caption Object">
    <ParamField body="preset" type="string" required>
      Caption preset style. Available presets: `default`, `beast`, `umi`, `tiktok`, `wrap1`, `wrap2`, `ariel`, `slidevid`, `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" required>
      Caption position on the video: `top`, `middle`, or `bottom`
    </ParamField>

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

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

  <Expandable title="Ad Settings Object">
    <ParamField body="bRollType" type="string" required>
      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" required>
      Remove the avatar's background for a cleaner look
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="aspectRatio" type="string" required>
  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="language" type="string" required>
  Language code for the video (max 2 characters).
</ParamField>

<ParamField body="media" type="array" required>
  B-roll media items (min 1, max 50). At least one media item is required. These are images or videos that will be shown during the ad.

  <Expandable title="Media Object">
    <ParamField body="id" type="string" required>
      Unique media ID (max 30 characters)
    </ParamField>

    <ParamField body="type" type="string" required>
      Media type: `video` or `image`
    </ParamField>

    <ParamField body="url" type="string" required>
      Public URL to the media file. Must be HTTPS.
    </ParamField>

    <ParamField body="title" type="string">
      Optional title/name for the media
    </ParamField>

    <ParamField body="durationInFrames" type="number">
      Duration in frames (25 frames = 1 second at 25fps)
    </ParamField>

    <ParamField body="isAIGenerated" type="boolean" default="false">
      Flag to indicate if media was AI-generated
    </ParamField>
  </Expandable>
</ParamField>

***

## Optional Fields

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

<ParamField body="musicId" type="string">
  Music ID from `/v1/music/list` for background music.
</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",
  "caption": {
    "preset": "wrap1",
    "alignment": "top",
    "disabled": false
  },
  "media": [
    {
      "id": "demo_video",
      "type": "video",
      "title": "Product Demo",
      "url": "https://your-cdn.com/demo.mp4",
      "durationInFrames": 200,
      "isAIGenerated": true
    }
  ],
  "adSettings": {
    "bRollType": "rounded-cover",
    "removeAvatarBackground": true
  },
  "aspectRatio": "ratio_9_16",
  "language": "en",
  "webhook": "https://yoursite.com/webhooks/video-complete"
}
```

### 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",
  "musicId": "trending_music_01",
  "caption": {
    "preset": "beast",
    "alignment": "bottom",
    "disabled": false
  },
  "media": [
    {
      "id": "demo_video",
      "type": "video",
      "title": "Product Demo",
      "url": "https://your-cdn.com/demo.mp4",
      "durationInFrames": 200,
      "isAIGenerated": true
    }
  ],
  "adSettings": {
    "bRollType": "down",
    "removeAvatarBackground": false
  },
  "aspectRatio": "ratio_9_16",
  "language": "en",
  "webhook": "https://api.yoursite.com/hooks/slidevid",
  "metadata": {
    "campaignId": "Q1-2024-ugc",
    "abTestVariant": "B",
    "internalRef": "MKT-5678"
  }
}
```

***

## 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.slidevid.ai/videos/abc123xyz.mp4",
    "shareUrl": "https://cdn.slidevid.ai/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               |
| `slidevid` | 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`          | Avatar on top half, B-roll on bottom half (Default) |
| `up`            | B-roll on top half, avatar on bottom half           |
| `left`          | Avatar on right, B-roll on left - balanced layout   |
| `right`         | Avatar on left, B-roll on right - balanced layout   |
| `rounded-cover` | Rounded avatar overlay on B-roll background         |
| `full-width`    | 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",
      "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",
      "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": [
        {
          "id": "unbox_1",
          "type": "video",
          "url": "https://example.com/unboxing.mp4",
          "durationInFrames": 200
        }
      ],
      "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: SlideVid API
  version: 1.0.0
  description: AI Video Generation API
servers:
  - url: https://api.slidevid.ai
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
                - caption
                - aspectRatio
                - language
                - adSettings
                - 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
                musicId:
                  type: string
                  description: Music ID from /v1/music/list for background music
                  maxLength: 30
                caption:
                  type: object
                  required:
                    - preset
                    - alignment
                    - disabled
                  properties:
                    preset:
                      type: string
                      enum:
                        - default
                        - beast
                        - umi
                        - tiktok
                        - wrap1
                        - wrap2
                        - ariel
                        - slidevid
                        - classic
                        - active
                        - bubble
                        - glass
                        - comic
                        - glow
                        - pastel
                        - neon
                        - retroTV
                        - red
                        - marker
                        - modern
                        - blue
                        - vivid
                      description: Caption preset style
                    alignment:
                      type: string
                      enum:
                        - top
                        - middle
                        - bottom
                      description: Caption position on video
                    disabled:
                      type: boolean
                      description: Set to false to show captions on the video
                media:
                  type: array
                  description: >-
                    B-roll media items (min 1, max 50). At least one media item
                    is required.
                  minItems: 1
                  maxItems: 50
                  items:
                    type: object
                    required:
                      - id
                      - type
                      - url
                    properties:
                      id:
                        type: string
                        description: Unique media ID
                      type:
                        type: string
                        enum:
                          - video
                          - image
                        description: Media type
                      title:
                        type: string
                        description: Media title/name
                      url:
                        type: string
                        description: Public URL to media file (HTTPS)
                      durationInFrames:
                        type: number
                        description: Duration in frames (25 fps)
                      isAIGenerated:
                        type: boolean
                        description: Flag for AI-generated media
                        default: false
                adSettings:
                  type: object
                  required:
                    - bRollType
                    - removeAvatarBackground
                  properties:
                    bRollType:
                      type: string
                      enum:
                        - down
                        - up
                        - left
                        - right
                        - rounded-cover
                        - full-width
                      description: B-roll display type
                    removeAvatarBackground:
                      type: boolean
                      description: Remove the avatar's background
                aspectRatio:
                  type: string
                  enum:
                    - ratio_9_16
                    - ratio_16_9
                    - ratio_1_1
                  description: Video aspect ratio
                language:
                  type: string
                  enum:
                    - en
                    - es
                  description: Language code (max 2 characters)
                  maxLength: 2
                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:
                - id: product_video
                  type: video
                  title: Product Demo
                  url: https://example.com/demo.mp4
                  durationInFrames: 200
                  isAIGenerated: true
              adSettings:
                bRollType: rounded-cover
                removeAvatarBackground: true
              aspectRatio: ratio_9_16
              language: en
              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

````