Create UGC Ad Video
curl --request POST \
--url https://api.hooked.so/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": [
"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"
}
}
EOFimport requests
url = "https://api.hooked.so/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": ["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"
}
}
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: ['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'}
})
};
fetch('https://api.hooked.so/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.hooked.so/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' => [
'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'
]
]),
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.hooked.so/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 \"product_video\",\n \"product_image\"\n ],\n \"adSettings\": {\n \"bRollType\": \"rounded-cover\",\n \"removeAvatarBackground\": true\n },\n \"aspectRatio\": \"ratio_9_16\",\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.hooked.so/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 \"product_video\",\n \"product_image\"\n ],\n \"adSettings\": {\n \"bRollType\": \"rounded-cover\",\n \"removeAvatarBackground\": true\n },\n \"aspectRatio\": \"ratio_9_16\",\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.hooked.so/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 \"product_video\",\n \"product_image\"\n ],\n \"adSettings\": {\n \"bRollType\": \"rounded-cover\",\n \"removeAvatarBackground\": true\n },\n \"aspectRatio\": \"ratio_9_16\",\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."
}
Videos
UGC Ads
Create authentic user-generated content style ads with AI avatars
POST
/
v1
/
project
/
create
/
ugc-ads
Create UGC Ad Video
curl --request POST \
--url https://api.hooked.so/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": [
"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"
}
}
EOFimport requests
url = "https://api.hooked.so/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": ["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"
}
}
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: ['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'}
})
};
fetch('https://api.hooked.so/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.hooked.so/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' => [
'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'
]
]),
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.hooked.so/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 \"product_video\",\n \"product_image\"\n ],\n \"adSettings\": {\n \"bRollType\": \"rounded-cover\",\n \"removeAvatarBackground\": true\n },\n \"aspectRatio\": \"ratio_9_16\",\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.hooked.so/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 \"product_video\",\n \"product_image\"\n ],\n \"adSettings\": {\n \"bRollType\": \"rounded-cover\",\n \"removeAvatarBackground\": true\n },\n \"aspectRatio\": \"ratio_9_16\",\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.hooked.so/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 \"product_video\",\n \"product_image\"\n ],\n \"adSettings\": {\n \"bRollType\": \"rounded-cover\",\n \"removeAvatarBackground\": true\n },\n \"aspectRatio\": \"ratio_9_16\",\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.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.
Optional Fields
string
Video name (max 100 characters)
string
default:"base"
Lipsync model quality:
base: Standard quality, faster processingpro: Higher quality, more accurate synchronization
object
Ad-specific settings for B-roll behavior
Show Ad Settings Object
Show Ad Settings Object
string
default:"down"
B-roll display type:
down: Avatar on top, B-roll on bottomup: B-roll on top, avatar on bottomleft: Avatar on right, B-roll on leftright: Avatar on left, B-roll on rightrounded-cover: Rounded avatar overlay on B-rollfull-width: B-roll covers entire screen, avatar hidden
boolean
default:"false"
Remove the avatar’s background for a cleaner look
string
Music ID from
/v1/music/list for background music.string
Video aspect ratio:
ratio_9_16: Vertical (TikTok, Reels, Shorts) - Recommended for UGCratio_16_9: Horizontal (YouTube)ratio_1_1: Square (Instagram)
object
Caption settings for the video
Show Caption Object
Show Caption Object
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.string
default:"bottom"
Caption position on the video:
top, middle, or bottomboolean
default:"true"
Set to
true to hide captions on the videoobject
Voice audio settings
Show Audio Settings Object
Show Audio Settings Object
number
default:"1.0"
Voice speed multiplier (0.7 to 1.2). Higher values make the voice faster.
number
default:"0.7"
Voice stability (0 to 1). Higher values make the voice more consistent and less variable.
number
default:"0.75"
Voice similarity boost (0 to 1). Higher values make the voice more similar to the original voice sample.
number
default:"0"
Voice style exaggeration (0 to 1). Higher values add more style and emotion to the voice.
boolean
default:"true"
Enable speaker boost for clearer audio output.
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",
"media": ["product_demo"]
}
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",
"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
{
"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
{
"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.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"
}
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 thecaption.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 foradSettings.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
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
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",
"media": [
{
"id": "product_review",
"type": "video",
"url": "https://example.com/review.mp4"
}
],
"caption": {
"preset": "tiktok",
"alignment": "bottom",
"disabled": false
}
}
Testimonials
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",
"media": ["testimonial_broll"],
"caption": {
"preset": "modern",
"alignment": "bottom",
"disabled": false
},
"adSettings": {
"removeAvatarBackground": true
}
}
Unboxing Videos
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": ["unbox_1"],
"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
Body
application/json
The script for the avatar to speak (1-10,000 characters)
Required string length:
1 - 10000Avatar ID from /v1/avatar/list
Maximum string length:
30Voice ID from /v1/voice/list. If not provided, uses avatar's default voice.
Maximum string length:
30B-roll media IDs (min 1, max 50). Array of media ID strings. At least one media item is required.
Required array length:
1 - 50 elementsUnique media ID
Video name (max 100 characters)
Maximum string length:
100Lipsync model
Available options:
base, pro Music ID from /v1/music/list for background music
Maximum string length:
30Show child attributes
Show child attributes
Show child attributes
Show child attributes
Video aspect ratio
Available options:
ratio_9_16, ratio_16_9, ratio_1_1 Show child attributes
Show child attributes
HTTPS URL to receive completion notification
Maximum string length:
500Custom metadata object (max 5KB)