Skip to main content

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 guide is for training a replica through the API with video URLs. If you prefer a guided flow with upload checks and inline validation, use the Tavus Developer Portal.

​
Outcome

You will POST /v2/replicas with train_video_url (and consent_video_url when required), then poll GET /v2/replicas/{replica_id} until training finishes.

​
Prerequisites

  • Training and consent videos that meet Training from a video (personal replicas need both; synthetic-only flows may omit consent—see below).
  • 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 replica

Default model is phoenix-4. To request phoenix-3, include "model_name": "phoenix-3" in the JSON body. Personal replica (training video + separate consent video): 
curl --request POST \
  --url https://tavusapi.com/v2/replicas \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $TAVUS_API_KEY" \
  --data '{
    "callback_url": "",
    "replica_name": "my_replica",
    "train_video_url": "https://example.com/training-video.mp4",
    "consent_video_url": "https://example.com/consent-video.mp4"
  }'
Synthetic / non-human (no separate consent video): send train_video_url only; omit consent_video_url. In the Developer Portal, use the Skip option for consent when applicable. 
curl --request POST \
  --url https://tavusapi.com/v2/replicas \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $TAVUS_API_KEY" \
  --data '{
    "callback_url": "",
    "replica_name": "synthetic_replica",
    "train_video_url": "https://example.com/training-video.mp4"
  }'

​
2. Poll replica status

Use Get Replica: 
curl --request GET \
  --url "https://tavusapi.com/v2/replicas/$REPLICA_ID" \
  --header "x-api-key: $TAVUS_API_KEY"
Training usually takes 3–4 hours. Optional: set callback_url to receive status webhooks.

​
3. Start a conversation

Generate a conversation with your replica 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 '
{
  "replica_id": $REPLICA_ID" 
}
'