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

Overview

Talking Avatar creates videos of an AI avatar speaking your script. The voice, lip movement and gestures are generated natively by the video model: you pick the avatar and write the script, nothing else. This format is ideal for:
  • Testimonial-style videos
  • Social media content
  • Personal video messages
  • Quick video updates
  • Product presentations
The script is split into short clips and each clip is generated with the avatar speaking on camera. There is no voiceId and no lipsync model to choose: the avatar comes with its voice.

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.

Optional Fields

string
Video name (max 100 characters)
string
Music ID from /v1/music/list for background music.
object
Caption settings for the video
object
deprecated
Accepted for backwards compatibility and ignored. The avatar’s speech is generated by the video model together with the picture, so there is no separate voice track to tune.
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 Talking Avatar

Complete Talking Avatar


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.

Put the Tone in the Script

The avatar reads what you write, the way you write it. Exclamation marks, pauses and short sentences shape the delivery.

Pick the Avatar for the Audience

Voice and look come together with the avatar, so choose the one that matches who the video is for.

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


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
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
caption
object
audio
object
deprecated

Deprecated. Accepted for backwards compatibility and ignored: the avatar's speech is generated by the video model together with the picture.

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