curl --request POST \
--url https://tavusapi.com/v2/faces \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"callback_url": "https://yourwebsite.com/webhook",
"face_name": "Rio",
"train_video_url": "https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-video.mp4"
}
'{
"face_id": "rc9cff32ceba",
"status": "started"
}{
"error": "Either train_video_url or train_image_url must be provided."
}{
"message": "Invalid access token"
}Create Face
Creates a new face from training video or image URL for use in conversations. See Choose a Model and Training Path for model and footage requirements and Face overview for rights and permissions.
curl --request POST \
--url https://tavusapi.com/v2/faces \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"callback_url": "https://yourwebsite.com/webhook",
"face_name": "Rio",
"train_video_url": "https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-video.mp4"
}
'{
"face_id": "rc9cff32ceba",
"status": "started"
}{
"error": "Either train_video_url or train_image_url must be provided."
}{
"message": "Invalid access token"
}https://docs.tavus.io/openapi.yaml for the full HTTP API contract.Authorizations
Body
A direct download link such as a presigned S3 URL or other publicly reachable file used for video-based face training. Do not send train_image_url in the same request.
The file must meet the video requirements for your model: Phoenix-4.5, Phoenix-4, or Phoenix-3 (legacy).
You must have the necessary rights and permissions to use the likeness, voice, and footage you submit. See Platform Policies.
"https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-video.mp4"
A direct link to a publicly accessible image used for image-to-face training. Requires voice_name. Do not send train_video_url in the same request. You must have the necessary rights and permissions to use the likeness and image. See Phoenix-4.5 Image Requirements, Phoenix-4 Image Requirements, and Platform Policies.
"https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-image.png"
Required when train_image_url is set. Slug that selects the voice from an existing Tavus stock face (case-insensitive, e.g. anna). If supplied with train_video_url, the name is still validated when present. Use List Voices to discover valid slugs; see also example stock voices. Alternative to default_voice_id; send one, not both.
"anna"
A Tavus Voice to use as this face's default, e.g. v0a1b2c3d4e5f. A PAL that names this face then needs no TTS configuration at all. Image-to-face only, and an alternative to voice_name, send one, not both. Video-to-face does not take this field: a voice is created from the training video's own audio and set as the default. Change it afterwards with Update Face.
"v0a1b2c3d4e5f"
When set to true, Tavus's AI Image Fixer instantly fixes any uploaded image to fit our Phoenix-4.5 or Phoenix-4 image requirements, eliminating the need for editing or recapturing photos. Only applies to image-based training (train_image_url).
true
A url that will receive a callback on completion of face training or on error.
"https://yourwebsite.com/webhook"
A name for the face.
"Rio"
The Phoenix model version used to train the face. Accepted values: phoenix-4.5, phoenix-4, and phoenix-3 (legacy). Current default: phoenix-4.5.
"phoenix-4.5"
Show child attributes
Show child attributes