Quickstart - Tavus

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 PAL-driven real-time session here.

Prerequisites

Before starting, ensure you have:

A replica_id for the video (this field name is unchanged on the Video API; the value is a Face ID from Stock faces or your own trained face). For your own likeness, see Face 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

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": "<face_id>",
  "script": "<text_script>",
  "callback_url": ""
}'

curl --request POST \
  --url https://tavusapi.com/v2/videos \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "replica_id": "<face_id>",
  "audio_url": "<audio_url>",
  "callback_url": ""
}'

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: <face_id> - June 24, 2025 - video: <video_id>",
  "status": "generating",
  "data": {
    "script": "<text_script>",
    "start_with_wave": true
  },
  "replica_id": "<face_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"
}

{
  "video_id": "<video_id>",
  "video_name": "replica_id: <face_id> - June 24, 2025 - video: <video_id>",
  "status": "generating",
  "data": {
    "audio_url": "<audio_url>",
    "start_with_wave": true
  },
  "replica_id": "<face_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.

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.

​Prerequisites

​Generate a video

Prerequisites

Generate a video