> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slidevid.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# UGC Video
> Create user-generated content style videos with AI avatars
**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
The script for the avatar to speak (1-10,000 characters). Write naturally as if a real person is speaking.
Avatar ID from `/v1/avatar/list`. Choose an avatar that matches your target audience.
Voice ID from `/v1/voice/list`. The voice used for the avatar's speech.
Caption settings for the video
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`.
Caption position on the video: `top`, `middle`, or `bottom`
Set to `true` to hide captions on the video
Video aspect ratio:
* `ratio_9_16`: Vertical (TikTok, Reels, Shorts) - **Recommended**
* `ratio_16_9`: Horizontal (YouTube)
* `ratio_1_1`: Square (Instagram)
Language code for the video (max 2 characters). Example: `en`, `es`
***
## Optional Fields
Video name (max 100 characters)
Music ID from `/v1/music/list` for background music.
HTTPS URL to receive completion notification (max 500 characters). **Highly recommended** for production use.
Custom metadata object (max 5KB). Store any additional data you need to associate with this video.
```json theme={null}
{
"campaignId": "summer2024",
"customField": "any value"
}
```
***
## Request Examples
### Basic UGC Video
```json theme={null}
{
"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
```json theme={null}
{
"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
```json Success Response theme={null}
{
"success": true,
"data": {
"videoId": "vid_ugc_abc123xyz",
"projectId": "proj_ugc_abc123xyz",
"status": "STARTED"
},
"message": "UGC video successfully created"
}
```
```json Error Response - Validation Error theme={null}
{
"success": false,
"message": "script: Script must be at least 1 character"
}
```
```json Error Response - Avatar Not Found theme={null}
{
"success": false,
"message": "avatarId: Avatar \"invalid_id\" not found."
}
```
***
## Webhook Notification
When your video is ready, we'll POST to your webhook URL:
```json Webhook Payload theme={null}
{
"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
Scripts should sound conversational. Use contractions, pauses, and natural speech patterns.
Shorter videos (15-60 seconds) tend to perform better on social media.
Choose a voice that matches the avatar's appearance for authenticity.
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
Browse available avatars
Find the perfect voice
View all your created videos
Learn how to handle webhook notifications
## OpenAPI
````yaml POST /v1/project/create/ugc-video
openapi: 3.0.0
info:
title: SlideVid API
version: 1.0.0
description: AI Video Generation API
servers:
- url: https://api.slidevid.ai
security:
- ApiKeyAuth: []
paths:
/v1/project/create/ugc-video:
post:
tags:
- Videos
summary: Create UGC Video
description: Create user-generated content style videos with AI avatars
operationId: createUGCVideo
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- script
- avatarId
- voiceId
- caption
- aspectRatio
- language
properties:
script:
type: string
description: The script for the avatar to speak (1-10,000 characters)
minLength: 1
maxLength: 10000
name:
type: string
description: Video name (max 100 characters)
maxLength: 100
avatarId:
type: string
description: Avatar ID from /v1/avatar/list
maxLength: 30
voiceId:
type: string
description: Voice ID from /v1/voice/list
maxLength: 30
musicId:
type: string
description: Music ID from /v1/music/list for background music
maxLength: 30
caption:
type: object
required:
- preset
- alignment
- disabled
properties:
preset:
type: string
enum:
- default
- beast
- umi
- tiktok
- wrap1
- wrap2
- ariel
- slidevid
- classic
- active
- bubble
- glass
- comic
- glow
- pastel
- neon
- retroTV
- red
- marker
- modern
- blue
- vivid
description: Caption preset style
default: classic
alignment:
type: string
enum:
- top
- middle
- bottom
description: Caption position on video
default: bottom
disabled:
type: boolean
description: Set to false to show captions on the video
default: false
aspectRatio:
type: string
enum:
- ratio_9_16
- ratio_16_9
- ratio_1_1
description: Video aspect ratio
language:
type: string
enum:
- en
- es
description: Language code (max 2 characters)
maxLength: 2
webhook:
type: string
description: HTTPS URL to receive completion notification
maxLength: 500
metadata:
type: object
description: Custom metadata object (max 5KB)
example:
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
responses:
'200':
description: UGC Video created successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
videoId:
type: string
projectId:
type: string
status:
type: string
message:
type: string
example:
success: true
data:
videoId: vid_ugc_abc123xyz
projectId: proj_ugc_abc123xyz
status: STARTED
message: UGC video successfully created
'400':
description: Validation error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
success: false
message: 'script: Script must be at least 1 character'
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
success: false
message: Invalid API key
security:
- ApiKeyAuth: []
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````