Video to Face

This guide is for training a face through the API with video URLs. If you prefer a guided flow with upload checks and inline validation, use the PAL Maker.

Outcome

You will POST /v2/faces with train_video_url, 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

Publicly downloadable URLs for each asset you send (for example presigned S3 GET URLs). Keep them 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 for full-body framing, include "model_name": "phoenix-4". Phoenix-3 is legacy ("model_name": "phoenix-3") and only for edge cases. See Choose a Model and Training Path. Personal face (training video):

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_replica",
    "model_name": "phoenix-4.5",
    "train_video_url": "https://example.com/training-video.mp4"
  }'

Stylized or cartoon human: send train_video_url. Cartoon, anime, and Pixar-style humans are fine. Animals, mascots, and other non-human figures are not.

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": "synthetic_replica",
    "train_video_url": "https://example.com/training-video.mp4"
  }'

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 (full parameter reference)
Phoenix-4.5 Preview and Status
Phoenix-4.5 Video Requirements
Phoenix-4 Video Requirements
Image to Face if you switch to headshot-based training

Getting Started

Guides

Build

Deploy

Debug

Teams & SSO

Resources

Video 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