curl --request POST \
--url https://tavusapi.com/v2/faces/image-validation \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"imageBase64": "<base64-encoded-image>",
"mimeType": "image/jpeg",
"model": "phoenix-4.5"
}
'import requests
url = "https://tavusapi.com/v2/faces/image-validation"
payload = {
"imageBase64": "<base64-encoded-image>",
"mimeType": "image/jpeg",
"model": "phoenix-4.5"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
imageBase64: '<base64-encoded-image>',
mimeType: 'image/jpeg',
model: 'phoenix-4.5'
})
};
fetch('https://tavusapi.com/v2/faces/image-validation', 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/image-validation",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'imageBase64' => '<base64-encoded-image>',
'mimeType' => 'image/jpeg',
'model' => 'phoenix-4.5'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://tavusapi.com/v2/faces/image-validation"
payload := strings.NewReader("{\n \"imageBase64\": \"<base64-encoded-image>\",\n \"mimeType\": \"image/jpeg\",\n \"model\": \"phoenix-4.5\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://tavusapi.com/v2/faces/image-validation")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"imageBase64\": \"<base64-encoded-image>\",\n \"mimeType\": \"image/jpeg\",\n \"model\": \"phoenix-4.5\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://tavusapi.com/v2/faces/image-validation")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"imageBase64\": \"<base64-encoded-image>\",\n \"mimeType\": \"image/jpeg\",\n \"model\": \"phoenix-4.5\"\n}"
response = http.request(request)
puts response.read_body{
"passed": false,
"message": "The image is blurry. Use a sharper image with even lighting.",
"checks": [
{
"id": "image_quality_acceptable",
"label": "Image is sharp and well-lit",
"passed": false
},
{
"id": "human_like_subject",
"label": "Subject is a person or human-like character",
"passed": true
},
{
"id": "appears_under_18",
"label": "Subject appears 18 or older",
"passed": true
},
{
"id": "only_one_person_visible",
"label": "Only one person in the photo",
"passed": true
},
{
"id": "person_centered",
"label": "Person is centered in frame",
"passed": true
},
{
"id": "head_fully_in_frame",
"label": "Head is fully visible in the photo",
"passed": true
},
{
"id": "looking_straight_at_camera",
"label": "Looking straight at the camera",
"passed": true
},
{
"id": "pose_suitable_for_replica",
"label": "Pose is natural and upright",
"passed": true
},
{
"id": "face_substantially_obscured",
"label": "Face is clearly visible",
"passed": true
},
{
"id": "chest_up_framing_acceptable",
"label": "Framed as a chest-up portrait",
"passed": true
},
{
"id": "no_nudity",
"label": "Chest is covered",
"passed": true
},
{
"id": "celebrity_or_copyright_character",
"label": "Not a celebrity or copyrighted character",
"passed": true
}
],
"details": {
"scene_description": "A blurry chest-up portrait of an adult facing the camera.",
"image_quality_acceptable": false,
"human_like_subject": true,
"appears_under_18": false,
"only_one_person_visible": true,
"person_centered": true,
"head_fully_in_frame": true,
"looking_straight_at_camera": true,
"pose_suitable_for_face": true,
"face_substantially_obscured": false,
"chest_up_framing_acceptable": true,
"no_nudity": true,
"celebrity_or_copyright_character": false,
"issues": [
"The image is blurry. Use a sharper image with even lighting."
]
}
}{
"message": "<string>",
"error": "<string>",
"code": "<string>"
}{
"message": "<string>",
"error": "<string>",
"code": "<string>"
}{
"message": "<string>",
"error": "<string>",
"code": "<string>"
}{
"message": "<string>",
"error": "<string>",
"code": "<string>"
}{
"message": "<string>",
"error": "<string>",
"code": "<string>"
}{
"message": "<string>",
"error": "<string>",
"code": "<string>"
}{
"message": "<string>",
"error": "<string>",
"code": "<string>"
}Validate Face Image
Check an image before submitting it to Create Face. Returns an overall pass/fail result, structured checks, and diagnostic details without creating a face.
Send the image bytes as base64 in imageBase64, without a data URL prefix, and specify the image’s mimeType. This endpoint takes image data, not a train_image_url.
Set model to the same Phoenix model you will use as model_name when creating the face. Validation defaults to phoenix-4; send "model": "phoenix-4.5" to use Phoenix-4.5 checks. See Phoenix-4 Image Requirements and Phoenix-4.5 Image Requirements.
HTTP 200 means validation completed, not that the image passed. Read passed for the overall result. Each entry in checks has an id, a display label, and its own passed value. Entries with passed: false identify what the user should fix. The checks and details vary by model.
The JSON request body must not exceed 30 MiB. The base64 string is limited to 28 MiB of characters.
Legacy: POST /v2/replicas/image-validation remains supported. Its diagnostic details use pose_suitable_for_replica where this endpoint uses pose_suitable_for_face; check IDs are unchanged.
curl --request POST \
--url https://tavusapi.com/v2/faces/image-validation \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"imageBase64": "<base64-encoded-image>",
"mimeType": "image/jpeg",
"model": "phoenix-4.5"
}
'import requests
url = "https://tavusapi.com/v2/faces/image-validation"
payload = {
"imageBase64": "<base64-encoded-image>",
"mimeType": "image/jpeg",
"model": "phoenix-4.5"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
imageBase64: '<base64-encoded-image>',
mimeType: 'image/jpeg',
model: 'phoenix-4.5'
})
};
fetch('https://tavusapi.com/v2/faces/image-validation', 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/image-validation",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'imageBase64' => '<base64-encoded-image>',
'mimeType' => 'image/jpeg',
'model' => 'phoenix-4.5'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://tavusapi.com/v2/faces/image-validation"
payload := strings.NewReader("{\n \"imageBase64\": \"<base64-encoded-image>\",\n \"mimeType\": \"image/jpeg\",\n \"model\": \"phoenix-4.5\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://tavusapi.com/v2/faces/image-validation")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"imageBase64\": \"<base64-encoded-image>\",\n \"mimeType\": \"image/jpeg\",\n \"model\": \"phoenix-4.5\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://tavusapi.com/v2/faces/image-validation")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"imageBase64\": \"<base64-encoded-image>\",\n \"mimeType\": \"image/jpeg\",\n \"model\": \"phoenix-4.5\"\n}"
response = http.request(request)
puts response.read_body{
"passed": false,
"message": "The image is blurry. Use a sharper image with even lighting.",
"checks": [
{
"id": "image_quality_acceptable",
"label": "Image is sharp and well-lit",
"passed": false
},
{
"id": "human_like_subject",
"label": "Subject is a person or human-like character",
"passed": true
},
{
"id": "appears_under_18",
"label": "Subject appears 18 or older",
"passed": true
},
{
"id": "only_one_person_visible",
"label": "Only one person in the photo",
"passed": true
},
{
"id": "person_centered",
"label": "Person is centered in frame",
"passed": true
},
{
"id": "head_fully_in_frame",
"label": "Head is fully visible in the photo",
"passed": true
},
{
"id": "looking_straight_at_camera",
"label": "Looking straight at the camera",
"passed": true
},
{
"id": "pose_suitable_for_replica",
"label": "Pose is natural and upright",
"passed": true
},
{
"id": "face_substantially_obscured",
"label": "Face is clearly visible",
"passed": true
},
{
"id": "chest_up_framing_acceptable",
"label": "Framed as a chest-up portrait",
"passed": true
},
{
"id": "no_nudity",
"label": "Chest is covered",
"passed": true
},
{
"id": "celebrity_or_copyright_character",
"label": "Not a celebrity or copyrighted character",
"passed": true
}
],
"details": {
"scene_description": "A blurry chest-up portrait of an adult facing the camera.",
"image_quality_acceptable": false,
"human_like_subject": true,
"appears_under_18": false,
"only_one_person_visible": true,
"person_centered": true,
"head_fully_in_frame": true,
"looking_straight_at_camera": true,
"pose_suitable_for_face": true,
"face_substantially_obscured": false,
"chest_up_framing_acceptable": true,
"no_nudity": true,
"celebrity_or_copyright_character": false,
"issues": [
"The image is blurry. Use a sharper image with even lighting."
]
}
}{
"message": "<string>",
"error": "<string>",
"code": "<string>"
}{
"message": "<string>",
"error": "<string>",
"code": "<string>"
}{
"message": "<string>",
"error": "<string>",
"code": "<string>"
}{
"message": "<string>",
"error": "<string>",
"code": "<string>"
}{
"message": "<string>",
"error": "<string>",
"code": "<string>"
}{
"message": "<string>",
"error": "<string>",
"code": "<string>"
}{
"message": "<string>",
"error": "<string>",
"code": "<string>"
}https://docs.tavus.io/openapi.yaml for the full HTTP API contract.Body
Response
Validation completed. An unsuitable image returns passed: false with structured checks.

