TAtavus
Faces

Create Face

Changed on

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.

post/v2/faces

Request

  • Base URL
    https://tavusapi.com
  • URL
    https://tavusapi.com/v2/faces
  • Auth
    API key in header x-api-key

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

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 Phoenix-4.5 Image Requirements, Phoenix-4 Image Requirements, 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 stock voices. Alternative to default_voice_id; send one, not both.

default_voice_idstring

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.

auto_fix_training_imageboolean

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 without manual editing. 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. Accepted values: phoenix-4.5, phoenix-4, and phoenix-3 (legacy). Current default: phoenix-4.5.

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",
  "default_voice_id": "v0a1b2c3d4e5f",
  "auto_fix_training_image": true,
  "callback_url": "https://yourwebsite.com/webhook",
  "face_name": "Rio",
  "model_name": "phoenix-4.5"
}

Response

face_idstring

A unique identifier for the face.

statusstring

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

Example response

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

Changes