UGC Video - SlideVid API Documentation

Create UGC Video

curl --request POST \
  --url https://api.slidevid.ai/v1/project/create/ugc-video \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data @- <<EOF
{
  "script": "Check out this amazing product! It’s super easy to use and I love the results.",
  "avatarId": "2",
  "voiceId": "confident_voice_id'",
  "caption": {
    "preset": "wrap1",
    "alignment": "bottom",
    "disabled": false
  },
  "aspectRatio": "ratio_9_16",
  "language": "en"
}
EOF

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

POST

project

create

ugc-video

Create UGC Video

curl --request POST \
  --url https://api.slidevid.ai/v1/project/create/ugc-video \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data @- <<EOF
{
  "script": "Check out this amazing product! It’s super easy to use and I love the results.",
  "avatarId": "2",
  "voiceId": "confident_voice_id'",
  "caption": {
    "preset": "wrap1",
    "alignment": "bottom",
    "disabled": false
  },
  "aspectRatio": "ratio_9_16",
  "language": "en"
}
EOF

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

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

POST /v1/project/create/ugc-video

Required Fields

script

string

required

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

avatarId

string

required

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

voiceId

string

required

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

caption

object

required

Caption settings for the video

Show Caption Object

preset

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.

alignment

string

required

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

disabled

boolean

required

Set to true to hide captions on the video

aspectRatio

string

required

Video aspect ratio:

ratio_9_16: Vertical (TikTok, Reels, Shorts) - Recommended
ratio_16_9: Horizontal (YouTube)
ratio_1_1: Square (Instagram)

language

string

required

Language code for the video (max 2 characters). Example: en, es

Optional Fields

name

string

Video name (max 100 characters)

musicId

string

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

webhook

string

HTTPS URL to receive completion notification (max 500 characters). Highly recommended for production use.

metadata

object

Custom metadata object (max 5KB). Store any additional data you need to associate with this video.

{
  "campaignId": "summer2024",
  "customField": "any value"
}

Request Examples

Basic UGC Video

{
  "script": "Check out this amazing product! It’s super easy to use and I love the results.",
  "avatarId": "2",
  "voiceId": "confident_voice_id'",
  "caption": {
    "preset": "wrap1",
    "alignment": "bottom",
    "disabled": false
  },
  "aspectRatio": "ratio_9_16",
  "language": "en"
}

Complete UGC Video

{
  "name": "Welcome Video",
  "script": "Hey there! Thanks for checking out our channel. We create awesome content every week, so make sure to subscribe and hit that notification bell!",
  "avatarId": "2",
  "voiceId": "confident_voice_id'",
  "caption": {
    "preset": "tiktok",
    "alignment": "bottom",
    "disabled": false
  },
  "aspectRatio": "ratio_9_16",
  "language": "en",
  "musicId": "music_upbeat_01",
  "webhook": "https://yoursite.com/webhook",
  "metadata": {
    "channelId": "my-channel",
    "videoType": "welcome"
  }
}

Response

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

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",
      "channelId": "my-channel"
    }
  },
  "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
`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

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

Error	Description	Solution
`script: Script must be at least 1 character`	Missing or empty script	Add the `script` field with your 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://`
`Not enough credits`	Insufficient credits	Top up your account credits

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

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 Video created successfully

success

boolean

data

object

Show child attributes

message

string

UGC Ads Retrieve Video Details

​Overview

​Endpoint

​Required Fields

​Optional Fields

​Request Examples

​Basic UGC Video

​Complete UGC Video

​Response

​Webhook Notification

​Caption Presets

​Best Practices

Write Naturally

Keep It Concise

Match Voice to Avatar

Use Webhooks

​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 Video

Complete UGC Video

Response

Webhook Notification

Caption Presets

Best Practices

Error Handling

Next Steps