Skip to main content
POST
/
v2
/
videos
Generate Video
curl --request POST \
  --url https://tavusapi.com/v2/videos \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "background_url": "https://yourwebsite.com/",
  "replica_id": "r90bbd427f71",
  "script": "Hi, this is my first video.",
  "video_name": "My First Video"
}
'
import requests

url = "https://tavusapi.com/v2/videos"

payload = {
    "background_url": "https://yourwebsite.com/",
    "replica_id": "r90bbd427f71",
    "script": "Hi, this is my first video.",
    "video_name": "My First Video"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    background_url: 'https://yourwebsite.com/',
    replica_id: 'r90bbd427f71',
    script: 'Hi, this is my first video.',
    video_name: 'My First Video'
  })
};

fetch('https://tavusapi.com/v2/videos', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://tavusapi.com/v2/videos",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'background_url' => 'https://yourwebsite.com/',
    'replica_id' => 'r90bbd427f71',
    'script' => 'Hi, this is my first video.',
    'video_name' => 'My First Video'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://tavusapi.com/v2/videos"

	payload := strings.NewReader("{\n  \"background_url\": \"https://yourwebsite.com/\",\n  \"replica_id\": \"r90bbd427f71\",\n  \"script\": \"Hi, this is my first video.\",\n  \"video_name\": \"My First Video\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://tavusapi.com/v2/videos")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"background_url\": \"https://yourwebsite.com/\",\n  \"replica_id\": \"r90bbd427f71\",\n  \"script\": \"Hi, this is my first video.\",\n  \"video_name\": \"My First Video\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://tavusapi.com/v2/videos")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"background_url\": \"https://yourwebsite.com/\",\n  \"replica_id\": \"r90bbd427f71\",\n  \"script\": \"Hi, this is my first video.\",\n  \"video_name\": \"My First Video\"\n}"

response = http.request(request)
puts response.read_body
{
  "video_id": "abcd123",
  "video_name": "Sample Video",
  "status": "queued",
  "hosted_url": "https://tavus.video/abcd123",
  "created_at": "Mon, 14 Jul 2025 09:14:24 GMT"
}
{
  "error": "Invalid replica_id"
}
{
  "message": "Invalid access token"
}
For AI agents, use https://docs.tavus.io/openapi.yaml for the full HTTP API contract.

Authorizations

​
x-api-key
string
header
required

Body

application/json

The only required body parameters are replica_id and either script or audio_url. (replica_id is the face resource ID - the same value returned by GET /v2/faces.)

If a background_url is provided, Tavus records the website and uses it as the background. If a background_source_url is provided (for example a presigned S3 URL to a video), that video is used as the background. If neither is provided, the video is full-screen face only.

To learn more about generating videos with faces, see here.

To learn more about writing an effective script for your video, see Scripting prompting.

​
script
string
required

A text script that will be used to generate the audio in the video.

Example:

"Hello from Tavus! Enjoy your new face"

​
replica_id
string
required

The Face ID to render in the video (same resource as face_id on /v2/faces; this endpoint still accepts replica_id).

Example:

"r90bbd427f71"

​
video_name
string

A name for the video.

Example:

"My First Video"

​
background_url
string

A link to a website. This will be used as the background for the video. The website must be publicly accessible and properly formed.

Example:

"https://yourwebsite.com/"

​
background_source_url
string

A direct link to a video that is publicly accessible via a storage location such as an S3 bucket. This will be used as the background for the video. The video must be publicly accessible.

Example:

"https://my-example-bucket.s3.us-east-1.amazonaws.com/your-background-video.mp4"

​
callback_url
string

A url that will receive a callback on completion of video generation or on error.

Example:

"https://yourwebsite.com/webhook"

​
fast
boolean

If set to true, the video will be generated using a barebones fast rendering process. This will result in a faster generation of the video but some features will be disabled. Features such as background generation, thumbnail images, and streaming urls are not supported when using this fast rendering process.

Example:

false

​
transparent_background
boolean

If set to true, the generated video will be a .webm video with a transparent background.

Please note that this feature only works if the fast parameter is set to true.

Example:

false

​
watermark_image_url
string

A direct link to a image that is publicly accessible via a storage location such as an S3 bucket. This will be used as the watermark on the video. Currently, it support png & jpeg formats only. Ensure the image is publicly accessible.

Example:

"https://s3.amazonaws.com/watermark.png"

​
properties
object

Response

​
video_id
string

A unique identifier for the video.

Example:

"abcd123"

​
video_name
string

The name of the video.

Example:

"Sample Video"

​
status
string

The status of the video. Possible values: queued, generating, ready, deleted, error.

Example:

"queued"

​
hosted_url
string

A direct link to view your video once generation has completed, hosted by Tavus.

Example:

"https://tavus.video/abcd123"

​
created_at
string

The date and time the video was created.

Example:

"Mon, 14 Jul 2025 09:14:24 GMT"