Tavus

https://docs.tavus.io
Admin
Tavus provides AI agents with human-like perception and presence through its Conversational Video...
Tokens:575,125
Snippets:4,250
Trust Score:9.7
Update:1 day ago
Show doc for...
Tokens:
Raw
### Create Vite React app and install server dependencies

Source: https://docs.tavus.io/sections/conversational-video-interface/quickstart/build-first-app

Run these commands to scaffold a React TypeScript app and install Express, CORS, dotenv, and TypeScript types for the backend server used in this guide.

```bash
npm create vite@latest tavus-first-call -- --template react-ts
cd tavus-first-call
npm install
npm install express cors dotenv
npm install -D tsx @types/express @types/cors
```

--------------------------------

### Go example for Get Memory Store

Source: https://docs.tavus.io/api-reference/memory-stores/get-memory-store

Uses net/http to send a GET request to the memory store endpoint. Prints the response body.

```go
package main

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

func main() {

	url := "https://tavusapi.com/v2/memory-stores/{memory_store_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

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

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

	fmt.Println(string(body))

}
```

--------------------------------

### JavaScript fetch example for starting a deployment conversation

Source: https://docs.tavus.io/api-reference/deployments/start-deployment-conversation

Uses fetch to POST the JSON payload to the start endpoint and logs the JSON response or error.

```javascript
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    password: '<string>',
    conversational_context: '<string>',
    custom_greeting: '<string>',
    pal_id: '<string>',
    memory_stores: ['<string>'],
    captcha_token: '<string>'
  })
};

fetch('https://tavusapi.com/v2/deployments/{deployment_id}/start', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Go example for starting a deployment conversation

Source: https://docs.tavus.io/api-reference/deployments/start-deployment-conversation

Creates an HTTP POST request with a JSON string payload and prints the response body.

```go
package main

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

func main() {

	url := "https://tavusapi.com/v2/deployments/{deployment_id}/start"

	payload := strings.NewReader("{\n  \"password\": \"<string>\",\n  \"conversational_context\": \"<string>\",\n  \"custom_greeting\": \"<string>\",\n  \"pal_id\": \"<string>\",\n  \"memory_stores\": [\n    \"<string>\"\n  ],\n  \"captcha_token\": \"<string>\"\n}")

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

	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))

}
```

--------------------------------

### Python requests example for starting a deployment conversation

Source: https://docs.tavus.io/api-reference/deployments/start-deployment-conversation

Uses the requests library to POST the same payload to the start endpoint and prints the response text.

```python
import requests

url = "https://tavusapi.com/v2/deployments/{deployment_id}/start"

payload = {
    "password": "<string>",
    "conversational_context": "<string>",
    "custom_greeting": "<string>",
    "pal_id": "<string>",
    "memory_stores": ["<string>"],
    "captcha_token": "<string>"
}
headers = {"Content-Type": "application/json"}

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

print(response.text)
```

--------------------------------

### Ruby Net::HTTP example for starting a deployment conversation

Source: https://docs.tavus.io/api-reference/deployments/start-deployment-conversation

Uses Net::HTTP to POST a JSON string body to the start endpoint and prints the response body.

```ruby
require 'uri'
require 'net/http'

url = URI("https://tavusapi.com/v2/deployments/{deployment_id}/start")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"password\": \"<string>\",\n  \"conversational_context\": \"<string>\",\n  \"custom_greeting\": \"<string>\",\n  \"pal_id\": \"<string>\",\n  \"memory_stores\": [\n    \"<string>\"\n  ],\n  \"captcha_token\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body
```

--------------------------------

### POST /v2/voices

Source: https://docs.tavus.io/api-reference/voices/create-voice

Creates a voice from a sample of audio and returns immediately with status: "started". The voice cloning runs asynchronously, and you can be notified via a callback_url webhook or by polling the Get Voice endpoint.

```APIDOC
## POST /v2/voices

### Description
Creates a voice from a sample of audio and returns immediately with `status: "started"`. The voice cloning runs asynchronously, and you can be notified via a callback_url webhook or by polling the Get Voice endpoint.

### Method
POST

### Endpoint
/v2/voices

### Parameters
#### Request Body
- **voice_name** (string) - Required - Name of the voice.
- **training_audio_url** (string) - Required - URL to the audio sample used for cloning.
- **description** (string) - Optional - Description of the voice.
- **callback_url** (string) - Optional - URL to receive a webhook event when the voice status changes.
- **tags** (array of strings) - Optional - Tags for the voice.

### Request Example
```json
{
  "voice_name": "Ana",
  "training_audio_url": "https://example.com/ana.mp3",
  "description": "Warm, unhurried, mid-Atlantic",
  "callback_url": "https://example.com/webhooks/voices",
  "tags": [
    "support",
    "en"
  ]
}
```

### Response
#### Success Response (200)
- **status** (string) - Initial status, "started".
- **voice_id** (string) - Identifier for the created voice.
- **voice_name** (string) - Name of the voice.

#### Response Example
```json
{
  "status": "started",
  "voice_id": "voice_123",
  "voice_name": "Ana"
}
```

### Notes
- The voice is not ready to speak until `status` reaches `completed`.
- You can receive a webhook event `application.voice_status_changed` by passing `callback_url`.
- Alternatively, poll the Get Voice endpoint to check status.
- Once ready, use the `voice_id` as `layers.tts.voice_id` on a PAL or as a face's `default_voice_id`.
- You must hold the rights to the voice in your training audio.
```

--------------------------------

### chat start

Source: https://docs.tavus.io/sections/agent-tools/cli

Start a text-only conversation against a PAL.

```APIDOC
## chat start

### Description
Start a text-only conversation against a PAL.

### Command
`chat start`

### Options
- `--pal-id` (string) - Required - The PAL ID.
- `--greeting` (string) - Optional - Greeting message.
- `--name` (string) - Optional - Conversation name.

```

--------------------------------

### builder create

Source: https://docs.tavus.io/sections/agent-tools/cli

Start a builder session.

```APIDOC
## builder create

### Description
Start a builder session.

### Command
`builder create`

### Options
- `--name` (string) - Optional - Name of the builder session.
- `--greeting` (string) - Optional - Greeting message.
- `--pal-id` (string) - Optional - PAL ID.
- `--model` (string) - Optional - Model to use.

```

--------------------------------

### Go GET document

Source: https://docs.tavus.io/api-reference/documents/get-document

Go example using net/http to fetch a document. Replace <api-key> with your API key.

```go
package main

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

func main() {

	url := "https://tavusapi.com/v2/documents/{document_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

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

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

	fmt.Println(string(body))

}
```

--------------------------------

### Java Unirest example for starting a deployment conversation

Source: https://docs.tavus.io/api-reference/deployments/start-deployment-conversation

Uses Unirest to send a POST request with a JSON string body and returns the response as a string.

```java
HttpResponse<String> response = Unirest.post("https://tavusapi.com/v2/deployments/{deployment_id}/start")
  .header("Content-Type", "application/json")
  .body("{\n  \"password\": \"<string>\",\n  \"conversational_context\": \"<string>\",\n  \"custom_greeting\": \"<string>\",\n  \"pal_id\": \"<string>\",\n  \"memory_stores\": [\n    \"<string>\"\n  ],\n  \"captcha_token\": \"<string>\"\n}")
  .asString();
```

--------------------------------

### Go GET Request to List Videos

Source: https://docs.tavus.io/api-reference/video-request/get-videos

Uses the net/http package to send a GET request to the /v2/videos endpoint with an x-api-key header. Prints the response body.

```go
package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

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

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

	fmt.Println(string(body))

}
```

--------------------------------

### Get Tools with Go

Source: https://docs.tavus.io/api-reference/tools/get-tools

Uses net/http to send a GET request to the tools endpoint. Prints the response body. Replace <api-key> with your API key.

```go
package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

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

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

	fmt.Println(string(body))

}
```

--------------------------------

### Get Face with Python requests

Source: https://docs.tavus.io/api-reference/faces/get-face

Uses the requests library to perform a GET request to the same endpoint. The response text is printed to the console. Requires the requests package to be installed.

```python
import requests

url = "https://tavusapi.com/v2/faces/{face_id}"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### Start a conversation with POST /v2/conversations

Source: https://docs.tavus.io/sections/faces/image-to-face-quickstart

Generates a conversation using the created face by providing its face_id.

```bash
curl --request POST \
  --url https://tavusapi.com/v2/conversations \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $TAVUS_API_KEY" \
  --data '{
    "face_id": "$FACE_ID"
  }'
```

--------------------------------

### tool example

Source: https://docs.tavus.io/sections/agent-tools/cli

Print a starter JSON body for `tool create`.

```APIDOC
## tool example

### Description
Print a starter JSON body for `tool create`.

### Command
`tool example`

### Options
- `--delivery` (string) - Optional - Delivery type. Possible values: `app_message`, `http`, `http_oauth2`.

```

--------------------------------

### Go GET request to list deployments

Source: https://docs.tavus.io/api-reference/deployments/list-deployments

Go example using net/http to fetch deployments. Prints the response body.

```go
package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

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

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

	fmt.Println(string(body))

}
```

--------------------------------

### Video generation status response (text)

Source: https://docs.tavus.io/sections/video/quickstart

Example response from the Get Video endpoint while the video is still generating, showing status 'generating' and generation_progress. This is the response for a video generated from text.

```json
{
  "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"
}
```

--------------------------------

### Ruby example for Get Memory Store

Source: https://docs.tavus.io/api-reference/memory-stores/get-memory-store

Uses Net::HTTP to send a GET request to the memory store endpoint. Prints the response body.

```ruby
require 'uri'
require 'net/http'

url = URI("https://tavusapi.com/v2/memory-stores/{memory_store_id}")

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

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### objective example

Source: https://docs.tavus.io/sections/agent-tools/cli

Print a starter JSON body for `objective create --file`.

```APIDOC
## objective example

### Description
Print a starter JSON body for `objective create --file`.

### Command
`objective example`

```

--------------------------------

### Go example for creating a deployment

Source: https://docs.tavus.io/api-reference/deployments/create-deployment

Uses net/http to POST to the deployments endpoint with a JSON payload. Prints the response body.

```go
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"pal_id\": \"pcb7a34da5fe\",\n  \"name\": \"<string>\",\n  \"password\": \"<string>\",\n  \"customization\": {},\n  \"limits\": {},\n  \"allowed_origins\": [\n    \"<string>\"\n  ]\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))

}
```

--------------------------------

### Java Unirest example for Get Memory Store

Source: https://docs.tavus.io/api-reference/memory-stores/get-memory-store

Uses Unirest to send a GET request to the memory store endpoint. Returns the response as a string.

```java
HttpResponse<String> response = Unirest.get("https://tavusapi.com/v2/memory-stores/{memory_store_id}")
  .header("x-api-key", "<api-key>")
  .asString();
```

--------------------------------

### Python requests example for Get Memory Store

Source: https://docs.tavus.io/api-reference/memory-stores/get-memory-store

Uses the requests library to call the GET /v2/memory-stores/{memory_store_id} endpoint. Prints the response text.

```python
import requests

url = "https://tavusapi.com/v2/memory-stores/{memory_store_id}"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### Copy .env.example to .env

Source: https://docs.tavus.io/sections/conversational-video-interface/quickstart/build-first-app

Copy the .env.example file to .env locally and fill in your real API key.

```bash
cp .env.example .env
```

--------------------------------

### JavaScript fetch example for Get Memory Store

Source: https://docs.tavus.io/api-reference/memory-stores/get-memory-store

Uses fetch to send a GET request to the memory store endpoint. Logs the JSON response or error.

```javascript
const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://tavusapi.com/v2/memory-stores/{memory_store_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Go example for creating pronunciation dictionary

Source: https://docs.tavus.io/api-reference/pronunciation-dictionaries/create-pronunciation-dictionary

Uses net/http to send a POST request with a JSON string payload. Requires an x-api-key header. Prints the response body.

```go
package main

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

func main() {

	url := "https://tavusapi.com/v2/pronunciation-dictionaries"

	payload := strings.NewReader("{\n  \"name\": \"Brand Terms\",\n  \"rules\": [\n    {\n      \"text\": \"Tavus\",\n      \"pronunciation\": \"TAH-vus\",\n      \"type\": \"alias\"\n    }\n  ]\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))

}
```

--------------------------------

### Video generation status response (audio)

Source: https://docs.tavus.io/sections/video/quickstart

Example response from the Get Video endpoint while the video is still generating, showing status 'generating' and generation_progress. This is the response for a video generated from an audio file.

```json
{
  "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"
}
```

--------------------------------

### Example 200 response for Get PAL

Source: https://docs.tavus.io/api-reference/pals/get-pal

Example JSON response returned by the Get PAL endpoint on success. Contains PAL details such as pal_id, system_prompt, layers configuration, and more.

```json
{
  "pal_id": "pcb7a34da5fe",
  "pal_name": "Life Coach",
  "system_prompt": "As a Life Coach, you are a dedicated professional who specializes in...",
  "greeting": "Hey there! What can I help you with today?",
  "dynamic_greeting": false,
  "default_face_id": "rc9cff32ceba",
  "conferencing_email": "acme-anna@tavusinvite.com",
  "disclosure_type": "auto",
  "verbal_disclosure": "Just so you know, you're speaking with an AI agent from Acme.",
  "visual_disclosure": "You are speaking with an AI agent.",
  "document_ids": [
    "d1234567890",
    "d2468101214"
  ],
  "document_tags": [
    "product_info",
    "company_policies"
  ],
  "layers": {
    "llm": {
      "model": "<string>",
      "base_url": "your-base-url",
      "api_key": "your-api-key",
      "tools": [
        {
          "type": "function",
          "function": {
            "name": "get_current_weather",
            "description": "Get the current weather in a given location",
            "parameters": {
              "type": "object",
              "properties": {
                "location": {
                  "type": "string",
                  "description": "The city and state, e.g. San Francisco, CA"
                },
                "unit": {
                  "type": "string",
                  "enum": [
                    "celsius",
                    "fahrenheit"
                  ]
                }
              },
              "required": [
                "location"
              ]
            }
          }
        }
      ],
      "headers": {
        "Authorization": "Bearer your-api-key"
      },
      "extra_body": {
        "temperature": 0.7,
        "top_p": 0.9
      }
    },
    "tts": {
      "api_key": "your-api-key",
      "tts_engine": "tavus-auto",
      "voice_id": "v0a1b2c3d4e5f",
      "external_voice_id": "external-voice-id",
      "voice_settings": {
        "speed": 0.5,
        "emotion": [
          "positivity:high",
          "curiosity"
        ]
      },
      "tts_model_name": "sonic-3",
      "pronunciation_dictionary_id": "pd_abc123def456"
    },
    "perception": {
      "perception_model": "raven-1",
      "callouts": "on",
      "emotion_recognition": "auto",
      "perception_analysis_queries": [
        "Which error messages appeared on the shared screen?"
      ],
      "visual_awareness_queries": [
        "Is the user showing an ID card?",
        "Does the user appear distressed or uncomfortable?"
      ],
      "visual_tool_prompt": "You have a tool to notify the system when an ID card is detected, named `notify_if_id_shown`. You MUST use this tool when a form of ID is detected.",
      "visual_tools": [
        {
          "type": "function",
          "function": {
            "name": "notify_if_id_shown",
            "description": "Use this function when a drivers license or passport is detected in the image with high confidence. After collecting the ID, internally use final_ask()",
            "parameters": {
              "type": "object",
              "properties": {
                "id_type": {
                  "type": "string",
                  "description": "The type of ID detected"
                }
              },
              "required": [
                "id_type"
              ]
            }
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Run both servers with npm run dev:all

Source: https://docs.tavus.io/sections/conversational-video-interface/quickstart/build-first-app

Starts the backend and frontend servers together. After running, open http://localhost:5173, enter your pal_id, and click Start conversation.

```bash
npm run dev:all
```

--------------------------------

### PHP cURL example for Get Memory Store

Source: https://docs.tavus.io/api-reference/memory-stores/get-memory-store

Uses PHP cURL to perform a GET request to the memory store endpoint. Handles errors and prints the response.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://tavusapi.com/v2/memory-stores/{memory_store_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "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;
}
```

--------------------------------

### Ruby Net::HTTP GET to list deployments

Source: https://docs.tavus.io/api-reference/deployments/list-deployments

Ruby example using Net::HTTP to fetch deployments. Prints the response body.

```ruby
require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### pronunciation-dictionary get <dictionary_id>

Source: https://docs.tavus.io/sections/agent-tools/cli

Get a pronunciation dictionary.

```APIDOC
## pronunciation-dictionary get <dictionary_id>

### Description
Get a pronunciation dictionary.

### Command
`pronunciation-dictionary get <dictionary_id>`

### Arguments
- `dictionary_id` (string) - Required - The ID of the pronunciation dictionary.

```

--------------------------------

### Create .env.example with TAVUS_API_KEY

Source: https://docs.tavus.io/sections/conversational-video-interface/quickstart/build-first-app

Create a .env.example file with the TAVUS_API_KEY placeholder. Copy it to .env and fill in your real key. Never expose the key in browser code or public repositories.

```bash
TAVUS_API_KEY=tvsk_your_api_key_here
```

--------------------------------

### tool get <tool_id>

Source: https://docs.tavus.io/sections/agent-tools/cli

Get a tool by its ID.

```APIDOC
## tool get <tool_id>

### Description
Get a tool by its ID.

### Command
`tool get <tool_id>`

### Arguments
- `tool_id` (string) - Required - The ID of the tool.

```

--------------------------------

### Install @daily-co/daily-js

Source: https://docs.tavus.io/sections/integrations/embedding-cvi

Install the Daily JavaScript SDK to build a custom in-call UI for Tavus CVI conversations.

```bash
npm install @daily-co/daily-js
```

--------------------------------

### Install Express

Source: https://docs.tavus.io/sections/integrations/embedding-cvi

Install Express to serve dynamic pages that embed Tavus CVI within Daily rooms.

```bash
npm install express
```

--------------------------------

### tavus guardrail get

Source: https://docs.tavus.io/sections/agent-tools/cli

Gets a guardrail by ID.

```APIDOC
## [CLI] tavus guardrail get

### Description
Gets a guardrail.

### Command
`tavus guardrail get <guardrail_id>`

### Parameters
#### Path Parameters
- **guardrail_id** (string) - Required - The ID of the guardrail.

#### Options
- **--verbose** (boolean) - Optional - Show verbose output.
- **--legacy** (boolean) - Optional - Use legacy shape.
```

--------------------------------

### JavaScript fetch GET to list deployments

Source: https://docs.tavus.io/api-reference/deployments/list-deployments

JavaScript example using fetch to retrieve deployments. Logs the JSON response or error to the console.

```javascript
const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

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

--------------------------------

### objective get <objectives_id>

Source: https://docs.tavus.io/sections/agent-tools/cli

Get an objective set by its ID.

```APIDOC
## objective get <objectives_id>

### Description
Get an objective set by its ID.

### Command
`objective get <objectives_id>`

### Arguments
- `objectives_id` (string) - Required - The ID of the objective set.

```

--------------------------------

### tavus quickstart <system_prompt>

Source: https://docs.tavus.io/sections/agent-tools/cli

Creates a PAL and a conversation using a stock face by default. Options include --name and --face-id.

```APIDOC
## tavus quickstart <system_prompt>

### Description
Creates a PAL and a conversation using a stock face by default. Options include --name and --face-id.

### Method
CLI

### Endpoint
tavus quickstart <system_prompt>

### Parameters
#### Arguments
- `system_prompt` (string) - Required - The system prompt for the PAL.

#### Options
- `--name` (string) - Optional - Name for the PAL.
- `--face-id` (string) - Optional - Face ID to use.

### Response
#### Success Response
- Creates a PAL and a conversation, returning relevant identifiers.
```

--------------------------------

### tavus resource get

Source: https://docs.tavus.io/sections/agent-tools/cli

Gets a single resource by ID.

```APIDOC
## [CLI] tavus resource get

### Description
Gets a single resource by ID.

### Command
`tavus resource get <resource> <resource_id>`

### Parameters
#### Path Parameters
- **resource** (string) - Required - Resource type.
- **resource_id** (string) - Required - The ID of the resource.
```

--------------------------------

### Create a video conversation with callback_url

Source: https://docs.tavus.io/sections/conversational-video-interface/magic-canvas/quickstart

Creates a video conversation that will have Canvas enabled. The callback_url receives interactions in step 4. Must be called from the backend, not the browser.

```bash
curl -X POST https://tavusapi.com/v2/conversations \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "face_id": "r79e1c033f",
    "pal_id": "p5317866",
    "callback_url": "https://yourapp.example.com/webhooks/tavus"
  }'
```

--------------------------------

### Ruby example for creating a deployment

Source: https://docs.tavus.io/api-reference/deployments/create-deployment

Uses Net::HTTP to POST to the deployments endpoint with the same payload. Prints the response body.

```ruby
require 'uri'
require 'net/http'

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

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  \"pal_id\": \"pcb7a34da5fe\",\n  \"name\": \"<string>\",\n  \"password\": \"<string>\",\n  \"customization\": {},\n  \"limits\": {},\n  \"allowed_origins\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body
```

--------------------------------

### tavus document get

Source: https://docs.tavus.io/sections/agent-tools/cli

Gets a single Knowledge document record.

```APIDOC
## [CLI] tavus document get

### Description
Gets one Knowledge document record.

### Command
`tavus document get <document_id>`

### Parameters
#### Path Parameters
- **document_id** (string) - Required - The ID of the document.

#### Options
- **--verbose** (boolean) - Optional - Show verbose output.
```

--------------------------------

### Add Magic Canvas React component via CLI

Source: https://docs.tavus.io/sections/conversational-video-interface/magic-canvas/quickstart

Installs the @tavus/cvi-ui Magic Canvas component using npx.

```bash
npx @tavus/cvi-ui@latest add magic-canvas
```

--------------------------------

### skill get <skill_id>

Source: https://docs.tavus.io/sections/agent-tools/cli

Get one RQH skill registry entry.

```APIDOC
## skill get <skill_id>

### Description
Get one RQH skill registry entry.

### Command
`skill get <skill_id>`

### Arguments
- `skill_id` (string) - Required - The ID of the skill.

```

--------------------------------

### Initialize and add CVI UI components with npx

Source: https://docs.tavus.io/sections/conversational-video-interface/component-library/overview

Run these commands to set up the Tavus CVI UI library and add the conversation and tavus-api components. Requires Node.js and npm.

```bash
npx @tavus/cvi-ui@latest init
npx @tavus/cvi-ui@latest add conversation
npx @tavus/cvi-ui@latest add tavus-api
```

--------------------------------

### Python requests GET to list deployments

Source: https://docs.tavus.io/api-reference/deployments/list-deployments

Python example using the requests library to fetch deployments. Replace <api-key> with your actual API key.

```python
import requests

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

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### Java Unirest GET learned memory

Source: https://docs.tavus.io/api-reference/memory-stores/get-learned-memory

Uses the Unirest library to send a GET request with the x-api-key header and returns the response as a string.

```java
HttpResponse<String> response = Unirest.get("https://tavusapi.com/v2/memory-stores/{memory_store_id}/learned")
  .header("x-api-key", "<api-key>")
  .asString();
```

--------------------------------

### Go example for listing PAL tools

Source: https://docs.tavus.io/api-reference/pal-tools/list-pal-tools

Uses net/http to send a GET request to /v2/pals/{pal_id}/tools with the x-api-key header and prints the response body.

```go
package main

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

func main() {

	url := "https://tavusapi.com/v2/pals/{pal_id}/tools"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

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

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

	fmt.Println(string(body))

}
```

--------------------------------

### 404 Not Found response

Source: https://docs.tavus.io/api-reference/pronunciation-dictionaries/get-pronunciation-dictionary

Example of a 404 Not Found response returned when the specified pronunciation dictionary does not exist.

```json
{
  "message": "Pronunciation dictionary not found"
}
```

--------------------------------

### JavaScript fetch example for creating a deployment

Source: https://docs.tavus.io/api-reference/deployments/create-deployment

Uses fetch to POST to the deployments endpoint with the same payload. Logs the response JSON or error.

```javascript
const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    pal_id: 'pcb7a34da5fe',
    name: '<string>',
    password: '<string>',
    customization: {},
    limits: {},
    allowed_origins: ['<string>']
  })
};

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

--------------------------------

### Get Tools 200 Response

Source: https://docs.tavus.io/api-reference/tools/get-tools

Example successful response (HTTP 200) containing a list of tools with details like tool_id, name, parameters, delivery, and timestamps.

```json
{
  "data": [
    {
      "tool_id": "tabc123def456",
      "owner_id": 3675,
      "name": "get_weather",
      "description": "Get the current weather for a city",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "City name"
          }
        },
        "required": [
          "city"
        ]
      },
      "delivery": {
        "app_message": true,
        "api": {
          "url": "https://api.example.com/v1/weather/{city}",
          "method": "POST",
          "timeout": 10,
          "headers": {
            "X-Service": "weather-bot"
          },
          "auth": {
            "type": "none",
            "token": "<string>",
            "username": "<string>",
            "password": "<string>",
            "name": "X-API-Key",
            "value": "<string>",
            "location": "header",
            "secret": "<string>",
            "token_url": "https://auth.example.com/oauth/token",
            "client_id": "<string>",
            "client_secret": "<string>",
            "scope": "<string>"
          },
          "body_template": {},
          "query_params": {
            "units": "metric"
          },
          "content_type": "application/json"
        }
      },
      "is_system_tool": false,
      "trigger_type": "in_call",
      "origin": "llm",
      "on_call": "generate_filler",
      "on_resolve": "generate_response",
      "static_filler": "Sure, let me grab that for you.",
      "created_at": "2026-05-15T10:30:00",
      "updated_at": "2026-05-15T10:30:00"
    }
  ],
  "total_count": 12
}
```

--------------------------------

### Go GET request to retrieve a tool

Source: https://docs.tavus.io/api-reference/tools/get-tool

Go example using net/http to GET a tool by ID. Sets the API key header and prints the response body.

```go
package main

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

func main() {

	url := "https://tavusapi.com/v2/tools/{tool_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

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

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

	fmt.Println(string(body))

}
```

--------------------------------

### JavaScript fetch GET request to retrieve a tool

Source: https://docs.tavus.io/api-reference/tools/get-tool

JavaScript example using fetch to GET a tool by ID. Handles the response as JSON and logs it or logs an error.

```javascript
const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://tavusapi.com/v2/tools/{tool_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### pronunciation-dictionary example

Source: https://docs.tavus.io/sections/agent-tools/cli

Print a starter JSON body for `pronunciation-dictionary create`.

```APIDOC
## pronunciation-dictionary example

### Description
Print a starter JSON body for `pronunciation-dictionary create`.

### Command
`pronunciation-dictionary example`

```

--------------------------------

### Create conversation with S3 recording storage (cURL)

Source: https://docs.tavus.io/sections/conversational-video-interface/quickstart/conversation-recordings

POST to `https://tavusapi.com/v2/conversations` to start a recording with S3 storage. Replace `<api_key>`, `your-bucket-name`, `bucket_region`, `assume_role_arn`, and `face_id` with your values. The `key_template` enables the account-scoped layout; Tavus prepends `tavus/<your_workspace_id>/` to the template. Omitting `key_template` falls back to the default layout and the recording is not delivered.

```bash
curl --request POST \
  --url https://tavusapi.com/v2/conversations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "properties": {
      "auto_start_recording": true,
      "recording_storage": {
        "provider": "s3",
        "bucket_name": "your-bucket-name",
        "bucket_region": "us-east-1",
        "assume_role_arn": "arn:aws:iam::123456789012:role/TavusRecordingWriter",
        "key_template": "recordings/{conversation_id}/{epoch_ms}.mp4"
      }
    },
    "face_id": "r5f0577fc829"
  }'
```

--------------------------------

### Python requests GET request to retrieve a tool

Source: https://docs.tavus.io/api-reference/tools/get-tool

Python example using the requests library to GET a tool by ID. Requires the requests package and an API key.

```python
import requests

url = "https://tavusapi.com/v2/tools/{tool_id}"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### Create a face with POST /v2/faces

Source: https://docs.tavus.io/sections/faces/image-to-face-quickstart

Sends a headshot image URL and voice to create a Phoenix face. Use "model_name": "phoenix-4.5" for Phoenix-4.5 or "phoenix-4" for Phoenix-4; image training is not available on Phoenix-3. Do not send both train_video_url and train_image_url. Set auto_fix_training_image to true to let Tavus's AI Image Fixer adjust the image automatically.

```bash
curl --request POST \
  --url https://tavusapi.com/v2/faces \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $TAVUS_API_KEY" \
  --data '{
    "callback_url": "",
    "face_name": "my_image_replica",
    "model_name": "phoenix-4.5",
    "train_image_url": "https://example.com/headshot.png",
    "voice_name": "anna",
    "auto_fix_training_image": true
  }'
```

--------------------------------

### Go GET learned memory

Source: https://docs.tavus.io/api-reference/memory-stores/get-learned-memory

Creates an HTTP GET request with the x-api-key header and prints the response body. Uses net/http and io packages.

```go
package main

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

func main() {

	url := "https://tavusapi.com/v2/memory-stores/{memory_store_id}/learned"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

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

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

	fmt.Println(string(body))

}
```

--------------------------------

### JavaScript fetch GET learned memory

Source: https://docs.tavus.io/api-reference/memory-stores/get-learned-memory

Uses the fetch API to send a GET request with the x-api-key header and logs the JSON response or error.

```javascript
const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://tavusapi.com/v2/memory-stores/{memory_store_id}/learned', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Python requests GET learned memory

Source: https://docs.tavus.io/api-reference/memory-stores/get-learned-memory

Uses the requests library to perform a GET request to the same endpoint with the x-api-key header. Prints the response text.

```python
import requests

url = "https://tavusapi.com/v2/memory-stores/{memory_store_id}/learned"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### Install Pipecat with OpenAI, Tavus, and Daily extras

Source: https://docs.tavus.io/sections/integrations/speech-to-speech

Install the required Pipecat extras for OpenAI, Tavus, and Daily. Use this command before configuring the environment.

```bash
pip install "pipecat-ai[openai,tavus,daily]"
```

--------------------------------

### Create Tool with JavaScript fetch

Source: https://docs.tavus.io/api-reference/tools/create-tool

POST to https://tavusapi.com/v2/tools using fetch. Creates an in-call LLM tool with app_message delivery. Replace <api-key> with your API key.

```javascript
const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'get_weather',
    description: 'Get the current weather for a city',
    parameters: {
      type: 'object',
      properties: {city: {type: 'string', description: 'City name'}},
      required: ['city']
    },
    delivery: {app_message: true},
    trigger_type: 'in_call',
    origin: 'llm',
    on_call: 'generate_filler',
    on_resolve: 'generate_response',
    static_filler: 'Sure, let me grab that for you.'
  })
};

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

```

--------------------------------

### JavaScript fetch GET document

Source: https://docs.tavus.io/api-reference/documents/get-document

JavaScript example using fetch to retrieve a document. Replace YOUR_API_KEY with your key.

```javascript
const response = await fetch(
  "https://tavusapi.com/v2/documents/{document_id}",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY"
    }
  }
);
```

--------------------------------

### PHP cURL GET to list deployments

Source: https://docs.tavus.io/api-reference/deployments/list-deployments

PHP example using cURL to fetch deployments. Prints the response or a cURL error message.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://tavusapi.com/v2/deployments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "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;
}
```

--------------------------------

### Ruby GET request to retrieve a tool

Source: https://docs.tavus.io/api-reference/tools/get-tool

Ruby example using Net::HTTP to GET a tool by ID. Sets the API key header and prints the response body.

```ruby
require 'uri'
require 'net/http'

url = URI("https://tavusapi.com/v2/tools/{tool_id}")

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

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Java Unirest GET request to retrieve a tool

Source: https://docs.tavus.io/api-reference/tools/get-tool

Java example using Unirest to GET a tool by ID. Sets the API key header and returns the response as a string.

```java
HttpResponse<String> response = Unirest.get("https://tavusapi.com/v2/tools/{tool_id}")
  .header("x-api-key", "<api-key>")
  .asString();
```

--------------------------------

### Start recording from client after participant joins (Daily)

Source: https://docs.tavus.io/sections/conversational-video-interface/quickstart/conversation-recordings

By default, recording does not start on its own. Trigger it after the participant joins by calling `startRecording()` inside the `joined-meeting` event handler.

```javascript
const call = Daily.createCallObject();

call.on('joined-meeting', () => {
  call.startRecording();
});
```

--------------------------------

### Run the webhook server

Source: https://docs.tavus.io/sections/webhooks-and-callbacks

Starts the Flask server on port 5000.

```bash
python server.py
```

--------------------------------

### Error response (400) for Get Tool

Source: https://docs.tavus.io/api-reference/tools/get-tool

Example JSON error response for a bad request, indicating the tool was not found.

```json
{
  "error": "Bad Request. Tool not found"
}
```
Tokens:
Raw