​
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: 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": ""
}'
  • Replace <api_key> with your actual API key. You can generate one in the Developer Portal.
  • Replace <replica_id> with the Replica ID you want to use.
  • Replace <text_script> with your video script.
  • Replace <audio_url> with the downloadable URL of your audio script.
2

Step 2: 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>'
Replace <api_key> with your actual 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"
}
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.