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": "r90bbd427f71",
  "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.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
consent_video_url
string

Optional direct link to a separate video that contains only the consent statement when it is not spoken at the start of train_video_url.

Required when your flow uses a standalone consent recording alongside train_video_url for likeness-based training from video. See Training from a video and consent statement requirements for exact wording and troubleshooting.

If omitted, the opening of train_video_url must include the consent statement instead (see train_video_url).

Example:

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

​
train_video_url
string

A direct download link such as a presigned S3 URL or other publicly reachable file used for video-based replica training. Do not send train_image_url in the same request.

The file must meet training video requirements.

When you do not send consent_video_url, this training clip must open with the following statement (verbatim), or training will fail:

I, [FULL NAME], am currently speaking and consent Tavus to create an AI clone of me by using the audio and video samples I provide. I understand that this AI clone can be used to create videos that look and sound like me.

See consent statement requirements for formatting tips and troubleshooting.

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. See Training from an image for image training, voice selection, and consent.

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"

​
auto_fix_training_image
boolean

When set to true, Tavus's AI Image Fixer instantly fixes any uploaded image to fit our image requirements, eliminating the need for editing or recapturing photos. Only applies to image-based training (train_image_url).

Example:

true

​
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 used to train the replica. Defaults to phoenix-4; set to phoenix-3 for the older model.

Example:

"phoenix-4"

​
properties
object

Response

​
replica_id
string

A unique identifier for the replica.

Example:

"r90bbd427f71"

​
status
string

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

Example:

"started"