Skip to main content
POST
/
v1
/
project
/
create
/
talking-avatar
Create Talking Avatar
curl --request POST \
  --url https://5f6cf291bc31.ngrok-free.app/api/v1/project/create/talking-avatar \
  --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'",
  "lipsyncModel": "base",
  "caption": {
    "preset": "wrap1",
    "alignment": "bottom",
    "disabled": false
  },
  "audio": {
    "speed": 1,
    "stability": 0.5,
    "similarityBoost": 0.75,
    "style": 0,
    "useSpeakerBoost": true
  },
  "webhook": "https://yoursite.com/webhook",
  "metadata": {
    "campaignId": "campaign_id",
    "variant": "A"
  }
}
EOF
{
  "success": true,
  "data": {
    "videoId": "vid_talking_avatar_abc123xyz",
    "projectId": "proj_ugc_abc123xyz",
    "status": "STARTED"
  },
  "message": "Talking avatar successfully created"
}
Try it out! Use the API playground on the right to test the Talking Avatar endpoint directly.

​
Overview

Talking Avatar creates videos with AI avatars that speak naturally using advanced lipsync technology. This format is ideal for:
  • Testimonial-style videos
  • Social media content
  • Personal video messages
  • Quick video updates
  • Product presentations
Talking Avatar uses AI avatars with voice synthesis and lipsync technology to create realistic videos that feel natural and engaging.

​
Endpoint

POST /v1/project/create/talking-avatar

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

​
Optional Fields

​
name
string
Video name (max 100 characters)
​
lipsyncModel
string
default:"base"
Lipsync model quality:
  • base: Standard quality, faster processing
  • pro: Higher quality, more accurate synchronization
​
musicId
string
Music ID from /v1/music/list for background music.
​
caption
object
Caption settings for the video
​
audio
object
Voice audio settings
​
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 Talking Avatar

{
  "script": "Check out this amazing product! It's super easy to use and I love the results.",
  "avatarId": "2",
  "voiceId": "confident_voice_id"
}

​
Complete Talking Avatar

{
  "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",
  "lipsyncModel": "pro",
  "caption": {
    "preset": "tiktok",
    "alignment": "bottom",
    "disabled": false
  },
  "audio": {
    "speed": 1,
    "stability": 0.5,
    "similarityBoost": 0.75,
    "style": 0,
    "useSpeakerBoost": true
  },
  "musicId": "music_upbeat_01",
  "webhook": "https://yoursite.com/webhook",
  "metadata": {
    "channelId": "my-channel",
    "videoType": "welcome"
  }
}

​
Response

{
  "success": true,
  "data": {
    "videoId": "vid_talking_avatar_abc123xyz",
    "projectId": "proj_ugc_abc123xyz",
    "status": "STARTED"
  },
  "message": "Talking avatar successfully created"
}

​
Webhook Notification

When your video is ready, we’ll POST to your webhook URL:
Webhook Payload
{
  "status": "COMPLETED",
  "data": {
    "videoId": "vid_talking_avatar_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.

​
Lipsync Models

ModelDescriptionProcessing TimeBest For
baseStandard lipsync qualityFasterQuick videos, testing, lower priority content
proHigher quality lipsync, more accurate synchronizationSlowerProfessional content, final productions, high-quality output

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

Choose the Right Model

Use base for faster processing, pro for higher quality lipsync synchronization.

Match Voice to Avatar

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

Fine-tune Audio

Adjust audio settings like speed and stability to match your content style.

Keep It Concise

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

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
lipsyncModel: Invalid lipsync modelInvalid lipsync modelUse either base or pro
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
​
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
​
lipsyncModel
enum<string>
default:base

Lipsync model

Available options:
base,
pro
​
caption
object
​
audio
object

Voice audio settings

​
webhook
string

HTTPS URL to receive completion notification

Maximum string length: 500
​
metadata
object

Custom metadata object (max 5KB)

Response

Talking Avatar created successfully

​
success
boolean
​
data
object
​
message
string