Sign in

v1

latestOpenAPI 3.0.32026-07-267015229.9 KB
Faces

Create Face

Creates a new face from training video or image URL for use in conversations. See Which training path? for footage requirements and Face overview for rights and permissions.

post/v2/faces

Request body

consent_video_urlstring

Legacy. Optional URL to a separate consent recording used with older video-training flows. New integrations should not send this field. Ensure you have the necessary rights and permissions to use any training footage - see Platform Policies.

train_video_urlstring

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.

train_image_urlstring

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.

voice_namestring

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.

auto_fix_training_imageboolean

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

callback_urlstring

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

face_namestring

A name for the face.

model_namestring

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

Example request

{
  "consent_video_url": "https://my-example-bucket.s3.us-east-1.amazonaws.com/your-consent-video.mp4",
  "train_video_url": "https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-video.mp4",
  "train_image_url": "https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-image.png",
  "voice_name": "anna",
  "auto_fix_training_image": true,
  "callback_url": "https://yourwebsite.com/webhook",
  "face_name": "Rio",
  "model_name": "phoenix-4"
}

Response

face_idstring

A unique identifier for the face.

statusstring

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

Example response

{
  "face_id": "r90bbd427f71",
  "status": "started"
}