Skip to main content
GET
/
v2
/
faces
/
{face_id}
Get Face
curl --request GET \
  --url https://tavusapi.com/v2/faces/{face_id} \
  --header 'x-api-key: <api-key>'
{
  "face_id": "r90bbd427f71",
  "face_name": "My Face",
  "thumbnail_video_url": "<string>",
  "training_progress": "100/100",
  "status": "completed",
  "created_at": "2024-01-24T07:14:03.327Z",
  "updated_at": "2024-01-24T07:14:03.327Z",
  "error_message": "<string>",
  "face_type": "user'",
  "model_name": "phoenix-3"
}
For AI agents, use https://docs.tavus.io/openapi.yaml for the full HTTP API contract.

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
face_id
string
required

A unique identifier for the face.

Query Parameters

​
verbose
boolean

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

Response

​
face_id
string

A unique identifier for the face.

Example:

"r90bbd427f71"

​
face_name
string

The name of the face.

Example:

"My Face"

​
thumbnail_video_url
string

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

​
training_progress
string

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

Example:

"100/100"

​
status
string

Training lifecycle: started, completed, or error. On failure, this is error and error_message is populated.

Example:

"completed"

​
created_at
string

The date and time the face was created.

Example:

"2024-01-24T07:14:03.327Z"

​
updated_at
string

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

Example:

"2024-01-24T07:14:03.327Z"

​
error_message
string | null

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

​
face_type
string

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

Example:

"user'"

​
model_name
string

The Phoenix model the face was trained on (e.g. phoenix-3, phoenix-4).

Example:

"phoenix-3"