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": "r4b03c679d42",
"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": "r4b03c679d42",
"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: 'r4b03c679d42',
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' => 'r4b03c679d42',
'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\": \"r4b03c679d42\",\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\": \"r4b03c679d42\",\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\": \"r4b03c679d42\",\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"
}Generate Video
This endpoint generates a new video using a face and either a script or an audio file.
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": "r4b03c679d42",
"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": "r4b03c679d42",
"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: 'r4b03c679d42',
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' => 'r4b03c679d42',
'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\": \"r4b03c679d42\",\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\": \"r4b03c679d42\",\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\": \"r4b03c679d42\",\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"
}https://docs.tavus.io/openapi.yaml for the full HTTP API contract.Body
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.
- Generate from Text
- Generate from Audio File
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.
"https://my-example-bucket.s3.us-east-1.amazonaws.com/your-background-video.mp4"
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.
false
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.
"https://s3.amazonaws.com/watermark.png"

