Prerequisites

Before starting, ensure you have:

  • A replica to be used for the video.
  • Script:
    • Text format.
    • Audio: .mp3 or .wav format.

Generate a video

1

Step 1: Get an API Key

  1. Go to the Tavus platform and select API Key from the sidebar menu.
  2. Click Create New Key to begin generating your API key.
  3. Enter a name for the key and (optional) specify allowed IP addresses, then click Create API Key.
  4. Copy your newly created API key and store it securely.

We cannot recover your API Key if you lose it.

2

Step 2: Make a Request

Use the following request to generate a video:

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": ""
}'

You can also customize the video background to suit your needs. See the Background Customizations article for more details.

3

Step 3: Check Video Generation Status

You can monitor the training status using the Get Video endpoint:

curl --request GET \
  --url https://tavusapi.com/v2/videos/<video_id> \
  --header 'x-api-key: <api-key>'

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.

{
  "video_id": "<video_id>",
  "video_name": "replica_id: <replica_id> - June 24, 2025 - video: <video_id>",
  "status": "ready",
  "data": {
    "script": "<text_script>",
    "start_with_wave": true
  },
  "replica_id": "<replica_id>",
  "download_url": "<download_url>",
  "hosted_url": "<hosted_url>",
  "stream_url": "<stream_url>",
  "status_details": "Your request has processed successfully!",
  "created_at": "Tue, 24 Jun 2025 07:01:57 GMT",
  "updated_at": "Tue, 24 Jun 2025 07:04:56 GMT",
  "generation_progress": "100/100"
}
4

Step 4: 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.