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.Authorizations
Body
Base64-encoded image bytes, without a data:image/...;base64, prefix. Leading and trailing whitespace is trimmed.
1 - 29360128"<base64-encoded-image>"
The image's MIME type. Defaults to image/jpeg when omitted.
image/jpeg, image/png, image/webp, image/heic, image/heif "image/jpeg"
Phoenix model to validate the image for. Match the model_name you will send to Create Face.
phoenix-4, phoenix-4.5 "phoenix-4.5"
Response
Validation completed. An unsuitable image returns passed: false with structured checks.
True when every check for the selected model passes.
A human-readable summary of the validation result.
Checks for the selected model. Use entries with passed: false to show rejection reasons.
Show child attributes
Show child attributes
Model-specific observations, including booleans about image quality, pose, framing, and other requirements. Use checks for pass/fail decisions: some detail booleans describe problems, so true does not always mean acceptable.
Show child attributes
Show child attributes

