​
Replica Creation with API Overview

Follow this guide to successfully create and retrieve a replica using our API endpoints. Before continuing, ensure that you have recorded training footage by following the instructions in our Training Guide. Verify that:

  • Training footage consists of 1 minute of talking, followed by 1 minute of silence in the same video
  • You have 2 separate videos for your consent footage and training footage
  • Alternatively, you have 1 combined video that starts with consent statement

​
Step 0: Ensure you have an API Key

You cannot send us API requests without a valid key. If your organization does not have an API key, read Getting an API Key to set this up.

​
Step 1: Upload Training Footage to S3

In order for us to access your training footage, you need to upload it onto S3 and provide us with a public download link (e.g. pre-signed S3 url). Make sure that your url is valid for at least 24 hours.

​
Step 2: Send Training Footage to Tavus

You are now ready to submit your footage for training! Reference our Create Replica API Reference to build out your request body. Once ready, include your API Key as a header and fire off your request to our endpoint.

By default, all new replicas will be trained using the phoenix-3 model. You can optionally create phoenix-2 replicas by setting the model_name parameter to phoenix-2 in the request body.

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": "",
  "train_video_url": ""
}'

If successful, you should receive this response from Tavus:

200 OK
{
  "replica_id": "r783537ef5",
  "status": "training"
}

​
Step 4: Check Replica Status

Upon submission, your replica will immediately start training in the background. After 4-6 hours, your replica will be ready for use. You will recieve an update through your callback URL or through our Get Replica endpoint.

​
Callback URL

The Callback URL in your Create Replica request body will receive a callback when your replica is done training. Errors in training will also be communicated through callbacks on the same URL. Learn more about API callbacks here.

{
  "replica_id": "rxxxxxxxxx",
  "status": "ready",
}

​
Get Replica API

You can also poll our Get Replica endpoint to get real-time updates on your replica’s status. Include the replica_id as a parameter.

curl --request GET \
  --url https://tavusapi.com/v2/replicas/{replica_id} \
  --header 'x-api-key: <api-key>'

If successful, you should get a response from us with information about your replica. Refer to "status" to check your replica’s training progress.

200 OK
{
  "replica_id": "r783537ef5",
  "replica_name": "My Replica",
  "thumbnail_video_url": "<string>",
  "training_progress": "100/100",
  "status": "completed",
  "created_at": "2024-01-24T07:14:03.327Z",
  "updated_at": "2024-01-24T07:14:03.327Z",
  "error_message": "<string>",
  "replica_type": "user'"
}

​
Step 5: Receive replica

At this point, you should have recieved your replica! Now you can try generating videos or starting conversations, either through our API endpoints or on the Developer Portal.

If you are struggling with this process or are unhappy about your replica, be sure to refer to API Errors and Status Details or reach out to our team. We are dedicated to giving you the best replica possible 🚀