> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavus.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Validate Face Image
> Check an image before submitting it to [Create Face](/api-reference/faces/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](/sections/faces/phoenix-4-image-requirements) and [Phoenix-4.5 Image Requirements](/sections/faces/phoenix-45-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.
For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract.
## OpenAPI
````yaml post /v2/faces/image-validation
openapi: 3.0.3
info:
title: Tavus Developer API Collection
version: 1.0.0
contact: {}
servers:
- url: https://tavusapi.com
security:
- apiKey: []
tags:
- name: Videos
- name: Faces
- name: Voices
- name: Conversations
- name: Deployments
- name: PALs
- name: Tools
- name: PAL Tools
- name: Connectors
- name: Pronunciation Dictionaries
- name: Replacements
- name: Transcriptions
- name: Documents
- name: Memory Stores
paths:
/v2/faces/image-validation:
post:
tags:
- Faces
summary: Validate Face Image
description: >
Check an image before submitting it to [Create
Face](/api-reference/faces/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](/sections/faces/phoenix-4-image-requirements) and
[Phoenix-4.5 Image
Requirements](/sections/faces/phoenix-45-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.
operationId: validateFaceImage
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- imageBase64
properties:
imageBase64:
type: string
minLength: 1
maxLength: 29360128
description: >-
Base64-encoded image bytes, without a
`data:image/...;base64,` prefix. Leading and trailing
whitespace is trimmed.
example:
mimeType:
type: string
enum:
- image/jpeg
- image/png
- image/webp
- image/heic
- image/heif
default: image/jpeg
description: >-
The image's MIME type. Defaults to `image/jpeg` when
omitted.
example: image/jpeg
model:
type: string
enum:
- phoenix-4
- phoenix-4.5
default: phoenix-4
description: >-
Phoenix model to validate the image for. Match the
`model_name` you will send to Create Face.
example: phoenix-4.5
example:
imageBase64:
mimeType: image/jpeg
model: phoenix-4.5
responses:
'200':
description: >-
Validation completed. An unsuitable image returns `passed: false`
with structured checks.
content:
application/json:
schema:
type: object
required:
- passed
- message
- checks
- details
properties:
passed:
type: boolean
description: True when every check for the selected model passes.
message:
type: string
description: A human-readable summary of the validation result.
checks:
type: array
description: >-
Checks for the selected model. Use entries with `passed:
false` to show rejection reasons.
items:
type: object
required:
- id
- label
- passed
properties:
id:
type: string
description: >-
Identifier for the check, such as
`image_quality_acceptable` or
`chest_up_framing_acceptable`. The set of checks
depends on the selected model.
label:
type: string
description: >-
Human-readable description of the condition being
checked.
passed:
type: boolean
description: True when the image satisfies this check.
details:
type: object
description: >-
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.
additionalProperties: true
properties:
scene_description:
type: string
description: Description of the image.
issues:
type: array
description: Human-readable issues identified in the image.
items:
type: string
example:
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.
'400':
description: >-
Invalid JSON or request fields, including a missing image,
unsupported MIME type or model, or unknown fields.
content:
application/json:
schema:
$ref: '#/components/schemas/face_image_validation_error'
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/face_image_validation_error'
'413':
description: The JSON request body exceeds the 30 MiB limit.
content:
application/json:
schema:
$ref: '#/components/schemas/face_image_validation_error'
'422':
description: >-
The validation provider blocked the image under its safety policy.
Returns `code: validation_policy_blocked` and a `message`, rather
than a completed set of checks.
content:
application/json:
schema:
$ref: '#/components/schemas/face_image_validation_error'
'429':
description: The upstream AI request rate limit was reached.
content:
application/json:
schema:
$ref: '#/components/schemas/face_image_validation_error'
'502':
description: >-
Validation failed because the upstream service or provider could not
complete the request.
content:
application/json:
schema:
$ref: '#/components/schemas/face_image_validation_error'
'504':
description: >-
The validation provider timed out. Returns `code: provider_timeout`
and a `message`.
content:
application/json:
schema:
$ref: '#/components/schemas/face_image_validation_error'
security:
- apiKey: []
components:
schemas:
face_image_validation_error:
type: object
description: >-
Error details. Depending on the failure, the explanation is returned in
`message` or `error`. Provider safety blocks and timeouts also return a
`code`.
properties:
message:
type: string
description: >-
Explanation of the failure, when returned by authentication or the
validation service.
error:
type: string
description: >-
Explanation of the failure, when returned by request handling or
rate limiting.
code:
type: string
description: >-
`validation_policy_blocked` for HTTP 422, or `provider_timeout` for
HTTP 504.
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.