Skip to main content
POST
Create UGC Ad Video
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
The avatar speaks your script on camera: voice, lip movement and gestures are generated natively by the video model, and your B-roll rides over or next to it. There is no voiceId to pick and no lipsync model.

Endpoint


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.
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)
object
Ad-specific settings for B-roll behavior
string
Music ID from /v1/music/list for background music.
string
Video aspect ratio:
  • ratio_9_16: Vertical (TikTok, Reels, Shorts) - Recommended for UGC
  • ratio_16_9: Horizontal (YouTube)
  • ratio_1_1: Square (Instagram)
object
Caption settings for the video
object
deprecated
Accepted for backwards compatibility and ignored. The avatar’s speech is generated by the video model together with the picture, so there is no separate voice track to tune.
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.

Request Examples

Basic UGC Ad

Complete UGC Ad

UGC Ad with Picture-in-Picture Avatar


Response


Webhook Notification

When your video is ready, we’ll POST to your webhook URL:
Webhook Payload
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:

B-Roll Types

Available B-roll display options for adSettings.bRollType:

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

Create authentic-looking product review videos.
Showcase customer success stories.
Create engaging unboxing content.

Error Handling


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
media
string[]
required

B-roll media IDs (min 1, max 50). Array of media ID strings. At least one media item is required.

Required array length: 1 - 50 elements

Unique media ID

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
caption
object
adSettings
object
aspectRatio
enum<string>
default:ratio_9_16

Video aspect ratio

Available options:
ratio_9_16,
ratio_16_9,
ratio_1_1
audio
object
deprecated

Deprecated. Accepted for backwards compatibility and ignored: the avatar's speech is generated by the video model together with the picture.

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
message
string