List Faces
curl --request GET \
--url https://tavusapi.com/v2/faces \
--header 'x-api-key: <api-key>'import requests
url = "https://tavusapi.com/v2/faces"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://tavusapi.com/v2/faces', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://tavusapi.com/v2/faces",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://tavusapi.com/v2/faces"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://tavusapi.com/v2/faces")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://tavusapi.com/v2/faces")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"data": [
{
"face_id": "r90bbd427f71",
"face_name": "My Face",
"default_voice_id": "v0a1b2c3d4e5f",
"original_voice_id": "v0a1b2c3d4e5f",
"thumbnail_video_url": "<string>",
"training_progress": "100/100",
"status": "completed",
"created_at": "<string>",
"face_type": "user'",
"model_name": "phoenix-3"
}
],
"total_count": 42
}{
"message": "Invalid access token"
}Face
List Faces
Returns all faces (photorealistic likenesses trained with Phoenix) created by the account associated with the API key.
Legacy: /v2/replicas and replica_id / replica_ids remain supported as aliases.
GET
/
v2
/
faces
List Faces
curl --request GET \
--url https://tavusapi.com/v2/faces \
--header 'x-api-key: <api-key>'import requests
url = "https://tavusapi.com/v2/faces"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://tavusapi.com/v2/faces', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://tavusapi.com/v2/faces",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://tavusapi.com/v2/faces"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://tavusapi.com/v2/faces")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://tavusapi.com/v2/faces")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"data": [
{
"face_id": "r90bbd427f71",
"face_name": "My Face",
"default_voice_id": "v0a1b2c3d4e5f",
"original_voice_id": "v0a1b2c3d4e5f",
"thumbnail_video_url": "<string>",
"training_progress": "100/100",
"status": "completed",
"created_at": "<string>",
"face_type": "user'",
"model_name": "phoenix-3"
}
],
"total_count": 42
}{
"message": "Invalid access token"
}For AI agents, use
https://docs.tavus.io/openapi.yaml for the full HTTP API contract.Authorizations
Query Parameters
The number of faces to return per page.
The page number to return
If set to true, the response will include additional face data such as the face type.
If set to user, the response will only include user faces. If set to system, the response will only include stock faces.
Available options:
user, system A comma separated list of face ids to filter the response by. Example: face_ids=r90bbd427f71
Filter the list to faces trained on a specific Phoenix model (e.g. phoenix-3, phoenix-4).

