Skip to main content
POST
/
v2
/
faces
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": "r90bbd427f71",
  "status": "started"
}
For AI agents, use https://docs.tavus.io/openapi.yaml for the full HTTP API contract.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
train_video_url
string

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 training video requirements.

You must have the necessary rights and permissions to use the likeness, voice, and footage you submit. See Platform Policies.

Example:

"https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-video.mp4"

​
train_image_url
string

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 Training from an image and Platform Policies.

Example:

"https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-image.png"

​
voice_name
string

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 voice_name values.

Example:

"anna"

​
auto_fix_training_image
boolean

When set to true, Tavus's AI Image Fixer instantly fixes any uploaded image to fit our image requirements, eliminating the need for editing or recapturing photos. Only applies to image-based training (train_image_url).

Example:

true

​
callback_url
string

A url that will receive a callback on completion of face training or on error.

Example:

"https://yourwebsite.com/webhook"

​
face_name
string

A name for the face.

Example:

"Rio"

​
model_name
string

The Phoenix model version used to train the face. Defaults to phoenix-4; set to phoenix-3 for the older model.

Example:

"phoenix-4"

​
properties
object

Response

​
face_id
string

A unique identifier for the face.

Example:

"r90bbd427f71"

​
status
string

The status of the face. Possible values: started, completed, error.

Example:

"started"