Skip to main content
POST
/
v2
/
replicas
curl --request POST \
  --url https://tavusapi.com/v2/replicas \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "callback_url": "https://yourwebsite.com/webhook",
  "replica_name": "Rio",
  "train_video_url": "https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-video.mp4",
  "consent_video_url": "https://my-example-bucket.s3.us-east-1.amazonaws.com/your-consent-video.mp4"
}
'
{
  "replica_id": "rf4e9d9790f0",
  "status": "started"
}

Documentation Index

Fetch the complete documentation index at: https://docs.tavus.io/llms.txt

Use this file to discover all available pages before exploring further.

This endpoint creates a new replica using the latest phoenix-4 model, which can be used in real-time conversations. To ensure high-quality replica creation, follow the steps in the Replica Training guide.
By default, all new replicas are trained using the phoenix-4 model.
To use the older phoenix-3 model, set the model_name parameter to phoenix-3.
Required parameters vary based on how you train the replica:Video training (with separate consent video):
  • train_video_url
  • consent_video_url
    Use when your flow includes a standalone consent recording for likeness-based training from video (see Replica Training).
Video training (no separate consent video, e.g. non-human):
  • train_video_url
Image training:
  • train_image_url
  • voice_name (slug for a stock replica’s voice—see example values)
    Likeness-based replicas can also be created from an image; consent and rights for image training are covered in Replica Training.
You must send either train_video_url or train_image_url, not both.
Make sure training and consent URLs are publicly accessible download links, such as presigned S3 URLs.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
consent_video_url
string

A direct link to a video that contains the consent statement. You may optionally send the consent statement in a separate video from your training video. If you do not provide a consent video, the consent statement must be present at the beginning of the training video. Required when your training flow uses a standalone consent recording alongside train_video_url for likeness-based training from video (see Replica Training).

Example:

"https://my-example-bucket.s3.us-east-1.amazonaws.com/your-consent-video.mp4"

​
train_video_url
string

A direct link to a publicly accessible storage location such as an S3 bucket. This video will be used for replica training. Do not send train_image_url in the same request.

Example:

"https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-video.mp4"

​
train_image_url
string

A direct link to a publicly accessible image used for image-to-replica training. Requires voice_name. Do not send train_video_url in the same request.

Example:

"https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-image.png"

​
voice_name
string

Required when train_image_url is set. Slug that selects the voice from an existing Tavus stock replica (case-insensitive, e.g. anna). If supplied with train_video_url, the name is still validated when present. Use List Voices to discover valid slugs; see also example voice_name values.

Example:

"anna"

​
callback_url
string

A url that will receive a callback on completion of replica training or on error.

Example:

"https://yourwebsite.com/webhook"

​
replica_name
string

A name for the replica.

Example:

"Rio"

​
model_name
string

The phoenix model version that will be used to train the replica. The current default is phoenix-4.

Example:

"phoenix-4"

​
properties
object

Response

​
replica_id
string

A unique identifier for the replica.

Example:

"rf4e9d9790f0"

​
status
string

The status of the replica. Possible values: started, completed, error.

Example:

"started"