Prerequisites

Before starting, ensure you have:
  • Pre-recorded training and consent videos that meet the requirements outlined in Replica Training.
  • Publicly accessible S3 URLs for:
    • Your training video
    • Your consent video
Ensure both URLs remain valid for at least 24 hours.

Create a Replica

1

Step 1: Create Your Replica

Use the following request to create the replica:
By default, replicas are trained using the phoenix-3 model. To use an older version, set "model_name": "phoenix-2" in your request body. However, we strongly recommend using the latest phoenix-3 model for improved quality and performance.
cURL
curl --request POST \
  --url https://tavusapi.com/v2/replicas \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "callback_url": "",
    "replica_name": "<your_replica_name>",
    "train_video_url": "<prerecorded_video_s3_url>",
    "consent_video_url": "<prerecorded_consent_video_s3_url>"
  }'
  • Replace <api_key> with your actual API key. You can generate one in the Developer Portal.
  • Replace <prerecorded_video_s3_url> with the downloadable URL of your training video.
  • Replace <prerecorded_consent_video_s3_url> with the downloadable URL of your consent video.
Once submitted, your replica will begin training in the background.
This process typically takes 4–6 hours.
2

Step 2: Check Replica Status

You can monitor the training status using the Get Replica endpoint:
cURL
curl --request GET \
  --url https://tavusapi.com/v2/replicas/{replica_id} \
  --header 'x-api-key: <api-key>'

Replace <api_key> with your actual API key.
3

Step 3: Start Using Your Replica

Once training is complete, you can use your non-human replica for:

Non-human Replica

To create a non-human replica, you do not need a consent video:
If you’re using the Developer Portal, select the Skip tab in the consent video window.
cURL
curl --request POST \
  --url https://tavusapi.com/v2/replicas \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "callback_url": "",
    "replica_name": "<replica_name>",
    "train_video_url": "<prerecorded_video_s3_url>"
  }'
  • Replace <api_key> with your actual API key. You can generate one in the Developer Portal.
  • Replace <your_replica_name> with the name for your non-human replica.
  • Replace <prerecorded_video_s3_url> with the downloadable URL of your training video.