Image to Face

This guide is for training a face through the API with train_image_url and voice_name. 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 voice_name, then poll GET /v2/faces/{face_id} until training finishes.

Prerequisites

A headshot and composition rules in Training from an image.
A valid voice_name slug (stock voice). See example voice_name values on that page.
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

Default model is phoenix-4. 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",
    "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 our requirements - no editing or recapturing photos required.

2. Poll face status

Use Get Face:

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

Training usually takes 3–4 hours. Optional: set callback_url to receive status webhooks.

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": $REPLICA_ID" 
}
'

Create Face (validation rules for train_image_url / voice_name)
Video to Face if you switch to video-based training

Getting started

Build

Deploy

Debug

Guides

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