UGC Ads

Create UGC Ad Video

curl --request POST \
  --url https://api.slidevid.ai/v1/project/create/ugc-ads \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data @- <<EOF
{
  "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"
  }
}
EOF

import requests

url = "https://api.slidevid.ai/v1/project/create/ugc-ads"

payload = {
    "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"
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}
  })
};

fetch('https://api.slidevid.ai/v1/project/create/ugc-ads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.slidevid.ai/v1/project/create/ugc-ads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.slidevid.ai/v1/project/create/ugc-ads"

	payload := strings.NewReader("{\n  \"name\": \"Product Review Ad\",\n  \"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!\",\n  \"avatarId\": \"avatar_casual_01\",\n  \"voiceId\": \"enthusiastic_voice_id\",\n  \"musicId\": \"music_lofi_01\",\n  \"caption\": {\n    \"preset\": \"wrap1\",\n    \"alignment\": \"bottom\",\n    \"disabled\": false\n  },\n  \"media\": [\n    {\n      \"id\": \"product_video\",\n      \"type\": \"video\",\n      \"title\": \"Product Demo\",\n      \"url\": \"https://example.com/demo.mp4\",\n      \"durationInFrames\": 200,\n      \"isAIGenerated\": true\n    }\n  ],\n  \"adSettings\": {\n    \"bRollType\": \"rounded-cover\",\n    \"removeAvatarBackground\": true\n  },\n  \"aspectRatio\": \"ratio_9_16\",\n  \"language\": \"en\",\n  \"webhook\": \"https://yoursite.com/webhook\",\n  \"metadata\": {\n    \"campaignId\": \"campaign_id\",\n    \"variant\": \"A\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.slidevid.ai/v1/project/create/ugc-ads")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Product Review Ad\",\n  \"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!\",\n  \"avatarId\": \"avatar_casual_01\",\n  \"voiceId\": \"enthusiastic_voice_id\",\n  \"musicId\": \"music_lofi_01\",\n  \"caption\": {\n    \"preset\": \"wrap1\",\n    \"alignment\": \"bottom\",\n    \"disabled\": false\n  },\n  \"media\": [\n    {\n      \"id\": \"product_video\",\n      \"type\": \"video\",\n      \"title\": \"Product Demo\",\n      \"url\": \"https://example.com/demo.mp4\",\n      \"durationInFrames\": 200,\n      \"isAIGenerated\": true\n    }\n  ],\n  \"adSettings\": {\n    \"bRollType\": \"rounded-cover\",\n    \"removeAvatarBackground\": true\n  },\n  \"aspectRatio\": \"ratio_9_16\",\n  \"language\": \"en\",\n  \"webhook\": \"https://yoursite.com/webhook\",\n  \"metadata\": {\n    \"campaignId\": \"campaign_id\",\n    \"variant\": \"A\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.slidevid.ai/v1/project/create/ugc-ads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Product Review Ad\",\n  \"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!\",\n  \"avatarId\": \"avatar_casual_01\",\n  \"voiceId\": \"enthusiastic_voice_id\",\n  \"musicId\": \"music_lofi_01\",\n  \"caption\": {\n    \"preset\": \"wrap1\",\n    \"alignment\": \"bottom\",\n    \"disabled\": false\n  },\n  \"media\": [\n    {\n      \"id\": \"product_video\",\n      \"type\": \"video\",\n      \"title\": \"Product Demo\",\n      \"url\": \"https://example.com/demo.mp4\",\n      \"durationInFrames\": 200,\n      \"isAIGenerated\": true\n    }\n  ],\n  \"adSettings\": {\n    \"bRollType\": \"rounded-cover\",\n    \"removeAvatarBackground\": true\n  },\n  \"aspectRatio\": \"ratio_9_16\",\n  \"language\": \"en\",\n  \"webhook\": \"https://yoursite.com/webhook\",\n  \"metadata\": {\n    \"campaignId\": \"campaign_id\",\n    \"variant\": \"A\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "videoId": "vid_ugc_abc123xyz",
    "projectId": "proj_ugc_abc123xyz",
    "status": "STARTED"
  },
  "message": "UGC ad successfully created"
}

{
  "success": false,
  "message": "script: Script must be at least 1 character"
}

{
  "success": false,
  "message": "avatarId: Avatar \"invalid_id\" not found."
}

POST

project

create

ugc-ads

Create UGC Ad Video

curl --request POST \
  --url https://api.slidevid.ai/v1/project/create/ugc-ads \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data @- <<EOF
{
  "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"
  }
}
EOF

import requests

url = "https://api.slidevid.ai/v1/project/create/ugc-ads"

payload = {
    "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"
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}
  })
};

fetch('https://api.slidevid.ai/v1/project/create/ugc-ads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.slidevid.ai/v1/project/create/ugc-ads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.slidevid.ai/v1/project/create/ugc-ads"

	payload := strings.NewReader("{\n  \"name\": \"Product Review Ad\",\n  \"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!\",\n  \"avatarId\": \"avatar_casual_01\",\n  \"voiceId\": \"enthusiastic_voice_id\",\n  \"musicId\": \"music_lofi_01\",\n  \"caption\": {\n    \"preset\": \"wrap1\",\n    \"alignment\": \"bottom\",\n    \"disabled\": false\n  },\n  \"media\": [\n    {\n      \"id\": \"product_video\",\n      \"type\": \"video\",\n      \"title\": \"Product Demo\",\n      \"url\": \"https://example.com/demo.mp4\",\n      \"durationInFrames\": 200,\n      \"isAIGenerated\": true\n    }\n  ],\n  \"adSettings\": {\n    \"bRollType\": \"rounded-cover\",\n    \"removeAvatarBackground\": true\n  },\n  \"aspectRatio\": \"ratio_9_16\",\n  \"language\": \"en\",\n  \"webhook\": \"https://yoursite.com/webhook\",\n  \"metadata\": {\n    \"campaignId\": \"campaign_id\",\n    \"variant\": \"A\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.slidevid.ai/v1/project/create/ugc-ads")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Product Review Ad\",\n  \"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!\",\n  \"avatarId\": \"avatar_casual_01\",\n  \"voiceId\": \"enthusiastic_voice_id\",\n  \"musicId\": \"music_lofi_01\",\n  \"caption\": {\n    \"preset\": \"wrap1\",\n    \"alignment\": \"bottom\",\n    \"disabled\": false\n  },\n  \"media\": [\n    {\n      \"id\": \"product_video\",\n      \"type\": \"video\",\n      \"title\": \"Product Demo\",\n      \"url\": \"https://example.com/demo.mp4\",\n      \"durationInFrames\": 200,\n      \"isAIGenerated\": true\n    }\n  ],\n  \"adSettings\": {\n    \"bRollType\": \"rounded-cover\",\n    \"removeAvatarBackground\": true\n  },\n  \"aspectRatio\": \"ratio_9_16\",\n  \"language\": \"en\",\n  \"webhook\": \"https://yoursite.com/webhook\",\n  \"metadata\": {\n    \"campaignId\": \"campaign_id\",\n    \"variant\": \"A\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.slidevid.ai/v1/project/create/ugc-ads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Product Review Ad\",\n  \"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!\",\n  \"avatarId\": \"avatar_casual_01\",\n  \"voiceId\": \"enthusiastic_voice_id\",\n  \"musicId\": \"music_lofi_01\",\n  \"caption\": {\n    \"preset\": \"wrap1\",\n    \"alignment\": \"bottom\",\n    \"disabled\": false\n  },\n  \"media\": [\n    {\n      \"id\": \"product_video\",\n      \"type\": \"video\",\n      \"title\": \"Product Demo\",\n      \"url\": \"https://example.com/demo.mp4\",\n      \"durationInFrames\": 200,\n      \"isAIGenerated\": true\n    }\n  ],\n  \"adSettings\": {\n    \"bRollType\": \"rounded-cover\",\n    \"removeAvatarBackground\": true\n  },\n  \"aspectRatio\": \"ratio_9_16\",\n  \"language\": \"en\",\n  \"webhook\": \"https://yoursite.com/webhook\",\n  \"metadata\": {\n    \"campaignId\": \"campaign_id\",\n    \"variant\": \"A\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "videoId": "vid_ugc_abc123xyz",
    "projectId": "proj_ugc_abc123xyz",
    "status": "STARTED"
  },
  "message": "UGC ad successfully created"
}

{
  "success": false,
  "message": "script: Script must be at least 1 character"
}

{
  "success": false,
  "message": "avatarId: Avatar \"invalid_id\" not found."
}

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

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

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

Endpoint

POST /v1/project/create/ugc-ads

Required Fields

string

required

The script for the avatar to speak (1-10,000 characters). Write naturally as if a real person is speaking.

string

required

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

string

required

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

object

required

Caption settings for the video

Show Caption Object

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.

string

required

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

boolean

required

Set to true to hide captions on the video

object

required

Ad-specific settings for B-roll behavior

Show Ad Settings Object

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

boolean

required

Remove the avatar’s background for a cleaner look

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)

string

required

Language code for the video (max 2 characters).

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.

Show Media Object

string

required

Unique media ID (max 30 characters)

string

required

Media type: video or image

string

required

Public URL to the media file. Must be HTTPS.

string

Optional title/name for the media

number

Duration in frames (25 frames = 1 second at 25fps)

boolean

default:"false"

Flag to indicate if media was AI-generated

Optional Fields

string

Video name (max 100 characters)

string

Music ID from /v1/music/list for background music.

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.

{
  "campaignId": "summer2024",
  "productSku": "SKU-12345",
  "customField": "any value"
}

Request Examples

Basic UGC Ad

{
  "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

{
  "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

{
  "success": true,
  "data": {
    "videoId": "vid_ugc_abc123xyz",
    "projectId": "proj_ugc_abc123xyz",
    "status": "STARTED"
  },
  "message": "UGC ad successfully created"
}

{
  "success": false,
  "message": "script: Script must be at least 1 character"
}

{
  "success": false,
  "message": "avatarId: Avatar \"invalid_id\" not found."
}

Webhook Notification

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

Webhook Payload

{
  "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"
}

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

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

Write Naturally

Scripts should sound conversational. Use contractions, pauses, and natural speech patterns.

Hook First

Start with an attention-grabbing hook in the first 2-3 seconds to stop scrolling.

Keep It Short

15-60 seconds is ideal for social media ads. Get to the point quickly.

Use B-Roll

Add product shots or demos to keep viewers engaged and showcase your product.

Common Use Cases

Product Reviews

Create authentic-looking product review videos.

{
  "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
  }
}

Testimonials

Showcase customer success stories.

{
  "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
  }
}

Unboxing Videos

Create engaging unboxing content.

{
  "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"
  }
}

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

List Avatars

Browse available avatars for your ads

List Voices

Find the perfect voice for your content

List Videos

View all your created videos

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

avatarId

string

required

Avatar ID from /v1/avatar/list

Maximum string length: 30

voiceId

string

required

Voice ID from /v1/voice/list. If not provided, uses avatar's default voice.

Maximum string length: 30

caption

object

required

Show child attributes

media

object[]

required

B-roll media items (min 1, max 50). At least one media item is required.

Required array length: 1 - 50 elements

Show child attributes

adSettings

object

required

Show child attributes

aspectRatio

enum<string>

required

Video aspect ratio

Available options:

ratio_9_16,

ratio_16_9,

ratio_1_1

language

enum<string>

required

Language code (max 2 characters)

Available options:

en,

es

Maximum string length: 2

name

string

Video name (max 100 characters)

Maximum string length: 100

musicId

string

Music ID from /v1/music/list for background music

Maximum string length: 30

webhook

string

HTTPS URL to receive completion notification

Maximum string length: 500

metadata

object

Custom metadata object (max 5KB)

Response

UGC Ad created successfully

success

boolean

data

object

Show child attributes

message

string

TikTok Slideshow UGC Video

Getting Started

Resources

Videos

Templates

Overview

Endpoint

Required Fields

Optional Fields

Request Examples

Basic UGC Ad

Complete UGC Ad

Response

Webhook Notification

Caption Presets

B-Roll Types

Best Practices

Write Naturally

Hook First

Keep It Short

Use B-Roll

Common Use Cases

Error Handling

Next Steps

List Avatars

List Voices

List Videos

Webhooks Guide

Authorizations

Body

Response

​Overview

​Endpoint

​Required Fields

​Optional Fields

​Request Examples

​Basic UGC Ad

​Complete UGC Ad

​Response

​Webhook Notification

​Caption Presets

​B-Roll Types

​Best Practices

Write Naturally

Hook First

Keep It Short

Use B-Roll

​Common Use Cases

​Error Handling

​Next Steps

List Avatars

List Voices

List Videos

Webhooks Guide

Authorizations

Body

Response

Overview

Endpoint

Required Fields

Optional Fields

Request Examples

Basic UGC Ad

Complete UGC Ad

Response

Webhook Notification

Caption Presets

B-Roll Types

Best Practices

Common Use Cases

Error Handling

Next Steps