TAtavus
Faces

Get Face

Changed on

This endpoint returns a single Face by its unique identifier.

get/v2/faces/{face_id}

Request

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

Path parameters

face_idstring required

A unique identifier for the face.

Query parameters

verboseboolean

If set to true, the response will include additional face data such as face_type.

Response

face_idstring

A unique identifier for the face.

face_namestring

The name of the face.

default_voice_idstring nullable

The Voice this face speaks with when a PAL sets no voice of its own. Null if the face has none.

original_voice_idstring nullable

The voice this face was created with, read-only. Training a face from a video creates a voice from that video's audio, and this is that voice. Set default_voice_id back to this id to revert a face to its original voice.

thumbnail_video_urlstring

A direct link to the video that will be used as the thumbnail for the face.

training_progressstring

Training progress as a string (for example 100/100).

statusstring

Whether the face is usable: started, completed, or error. On failure, this is error and error_message is populated. On Phoenix-4.5, completed means the zero-shot preview is ready, not that tuning is done. See Phoenix-4.5 Preview and Status.

finetune_statusstring nullable

Phoenix-4.5 background tuning: null until fine-tuning starts, then training, completed, or error. Unused on Phoenix-4 and Phoenix-3. See Phoenix-4.5 Preview and Status.

created_atstring

The date and time the face was created.

updated_atstring

The date and time of when the face was last updated.

error_messagestring nullable

When status is error, contains details about the training failure; otherwise typically null.

face_typestring

If verbose query paramter is set to true. The type of face. Possible values: user, system. User faces are faces that have been created by users. System faces are stock Tavus faces that anyone may use

model_namestring

The Phoenix model the face was trained on (phoenix-4.5, phoenix-4, or phoenix-3 legacy).

Example response

{
  "face_id": "rc9cff32ceba",
  "face_name": "My Face",
  "default_voice_id": "v0a1b2c3d4e5f",
  "original_voice_id": "v0a1b2c3d4e5f",
  "training_progress": "100/100",
  "status": "completed",
  "finetune_status": "training",
  "created_at": "2024-01-24T07:14:03.327Z",
  "updated_at": "2024-01-24T07:14:03.327Z",
  "face_type": "user'",
  "model_name": "phoenix-4.5"
}

Changes

  • 932c24e63be2Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status