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.

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 photo rules 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 photo rules - no editing or recapturing photos required.

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

1. Create the face

2. Poll face status

3. Start a conversation

​Outcome

​Prerequisites

​1. Create the face

​2. Poll face status

​3. Start a conversation

​Related

Outcome

Prerequisites

1. Create the face

2. Poll face status

3. Start a conversation

Related