Image to Face

This guide is for training a face through the API with train_image_url. If you prefer a guided flow with instant feedback on whether your image passes checks, use the PAL Maker.

Outcome

You will POST /v2/faces with train_image_url and a voice, then poll GET /v2/faces/{face_id} until ready. For Phoenix-4.5 preview and tuning status, see Phoenix-4.5 Preview and Status.

Prerequisites

A headshot and composition rules in Phoenix-4.5 Image Requirements or Phoenix-4 Image Requirements.
A voice for the face. See Voices for Image-Based Faces.
A publicly downloadable URL for the image (for example a presigned S3 GET URL). Keep it valid for at least 24 hours after submission.

Validate the image (optional)

Before training, use Validate Face Image to check your image and show users what to fix. Send the image bytes as imageBase64, its mimeType, and model set to the same Phoenix model you will use for training. Validation defaults to phoenix-4, so send "model": "phoenix-4.5" for the example below. A completed check returns HTTP 200 whether the image passes or fails. Read passed for the overall result and show the labels of entries in checks whose passed is false. Validation does not create a face; submit the image URL in the next step when you are ready to train.

1. Create the face

Send "model_name": "phoenix-4.5" for Phoenix-4.5. To use Phoenix-4, include "model_name": "phoenix-4". Image training is not available on Phoenix-3 (legacy). Pick a model and see image requirements in Choose a Model and Training Path. Do not send train_video_url and train_image_url in the same request.

curl --request POST \
  --url https://tavusapi.com/v2/faces \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $TAVUS_API_KEY" \
  --data '{
    "callback_url": "",
    "face_name": "my_image_replica",
    "model_name": "phoenix-4.5",
    "train_image_url": "https://example.com/headshot.png",
    "voice_name": "anna",
    "auto_fix_training_image": true
  }'

Set auto_fix_training_image to true to have Tavus’s AI Image Fixer instantly adjust the uploaded image to fit the Phoenix-4.5 or Phoenix-4 image requirements without manual editing.

2. Poll face status

Use Get Face:

curl --request GET \
  --url "https://tavusapi.com/v2/faces/$FACE_ID" \
  --header "x-api-key: $TAVUS_API_KEY"

Poll until status is completed. On Phoenix-4.5 that is the watermarked preview; check finetune_status for the unwatermarked version. See Phoenix-4.5 Preview and Status.

3. Start a conversation

Generate a conversation with your face using Create Conversation

curl --request POST \
  --url https://tavusapi.com/v2/conversations \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $TAVUS_API_KEY" \
  --data '{
    "face_id": "$FACE_ID"
  }'

Create Face (validation rules for train_image_url)
Phoenix-4.5 Preview and Status
Voices for Image-Based Faces
Phoenix-4.5 Image Requirements
Phoenix-4 Image Requirements
Video to Face if you switch to video-based training

Getting Started

Guides

Build

Deploy

Debug

Teams & SSO

Resources

Image to Face

Outcome

Prerequisites

Validate the image (optional)

1. Create the face

2. Poll face status

3. Start a conversation

​Outcome

​Prerequisites

​Validate the image (optional)

​1. Create the face

​2. Poll face status

​3. Start a conversation

​Related

Outcome

Prerequisites

Validate the image (optional)

1. Create the face

2. Poll face status

3. Start a conversation

Related