Skip to main content
POST
Create UGC Video
Try it out! Use the API playground on the right to test the UGC Video endpoint directly.

Overview

UGC Video creates authentic-looking user-generated content videos with AI avatars. This format is ideal for:
  • Testimonial-style videos
  • Social media content
  • Personal video messages
  • Quick video updates
UGC Video uses AI avatars with voice synthesis to create realistic videos that feel natural and engaging.

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.
string
required
Voice ID from /v1/voice/list. The voice used for the avatar’s speech.
object
required
Caption settings for the video
string
required
Video aspect ratio:
  • ratio_9_16: Vertical (TikTok, Reels, Shorts) - Recommended
  • ratio_16_9: Horizontal (YouTube)
  • ratio_1_1: Square (Instagram)
string
required
Language code for the video (max 2 characters). Example: en, es

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.

Request Examples

Basic UGC Video

Complete UGC Video


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:

Best Practices

Write Naturally

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

Keep It Concise

Shorter videos (15-60 seconds) tend to perform better on social media.

Match Voice to Avatar

Choose a voice that matches the avatar’s appearance for authenticity.

Use Webhooks

Always use webhooks in production instead of polling for video status.

Error Handling


Next Steps

List Avatars

Browse available avatars

List Voices

Find the perfect voice

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

Maximum string length: 30
caption
object
required
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 Video created successfully

success
boolean
data
object
message
string