Skip to main content
POST
/
v1
/
project
/
create
/
ugc-video
Create UGC Video
curl --request POST \
  --url https://b8e35428b2f8.ngrok-free.app/api/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
​
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.tryhooked.ai/videos/abc123xyz.mp4",
    "shareUrl": "https://cdn.tryhooked.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:
PresetDescription
defaultDefault caption style with bold text and shadow effects
beastBold uppercase style with Komika font
umiYellow glowing text style
tiktokViral & trendy style, perfect for social media
wrap1Wrapped style with red background highlight
wrap2Wrapped style with blue background highlight (uppercase)
arielBold uppercase style with purple highlight
hookedBrand style with purple background
classicClean, simple captions with black background
activeGreen background with bold text
bubbleWhite background bubble style
glassGlassmorphic transparency effect
comicComic Sans font with colorful style
glowPink and orange glow effects
pastelSoft pastel pink background
neonGreen neon glow effect
retroTVRetro TV style with cyan glow
redRed glow effect with white text
markerYellow marker/highlighter style
modernContemporary white background style
blueBlue background style
vividVibrant 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

ErrorDescriptionSolution
script: Script must be at least 1 characterMissing or empty scriptAdd the script field with your content
avatarId: Avatar not foundInvalid avatar IDUse a valid avatar ID from /v1/avatar/list
voiceId: Voice not foundInvalid voice IDUse a valid voice ID from /v1/voice/list
webhook: Must be a valid HTTPS URLInvalid webhook URLEnsure webhook URL starts with https://
Not enough creditsInsufficient creditsTop 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
​
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