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.

Tavus Video Generation is the same async, file-output product described in Video overview: you call the Video API and poll until a downloadable video is ready. It is not the Conversational Video Interface (CVI)—there is no live room, Daily room, or persona-driven real-time session here.

​
Prerequisites

Before starting, ensure you have:
  • A replica_id for the video. Fastest path: pick a stock replica ID from Stock replicas (each card lists the UUID). For your own likeness, see Replica overview and training docs.
  • Script in text form, or audio as .mp3 or .wav (hosted at a URL you can pass for the audio path).
At a glance
  • Create: POST https://tavusapi.com/v2/videos with replica_id plus either script (text) or audio_url (and optional callback_url).
  • Status: GET https://tavusapi.com/v2/videos/{video_id} — Get Video.
  • While generating: status is generating; when ready, download_url / hosted_url populate.

​
Generate a video

1

Step 1: Generate Your Video

Use the following request to generate a video:
You can also customize the video background to suit your needs. See the Background Customizations article for more details.
curl --request POST \
  --url https://tavusapi.com/v2/videos \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "replica_id": "<replica_id>",
  "script": "<text_script>",
  "callback_url": ""
}'
2

Step 2: Check Video Generation Status

You can monitor generation using the Get Video endpoint:
curl --request GET \
  --url https://tavusapi.com/v2/videos/<video_id> \
  --header 'x-api-key: <api-key>'
Replace <api_key> with your actual API key (see Step 1). Replace <video_id> with the ID returned when you created the video.
If the video is still being generated, the response will include a status field set to generating.
{
  "video_id": "<video_id>",
  "video_name": "replica_id: <replica_id> - June 24, 2025 - video: <video_id>",
  "status": "generating",
  "data": {
    "script": "<text_script>",
    "start_with_wave": true
  },
  "replica_id": "<replica_id>",
  "download_url": null,
  "hosted_url": "<hosted_url>",
  "stream_url": null,
  "status_details": "",
  "created_at": "Tue, 24 Jun 2025 07:01:57 GMT",
  "updated_at": "Tue, 24 Jun 2025 07:02:25 GMT",
  "generation_progress": "37/100"
}
Once the video is fully generated, the response will return a status field set to ready.
3

Step 3: Accessing Your Video

Once generated, videos can be:
  • Streamed or Downloaded: Generated video is hosted on a shareable URL. If a callback is set, a download link is returned when the video generated.
  • Embedded or Shared: Use the provided links to distribute your videos across social media, internal tools, or customer platforms.