tavus

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 6, 2026 License: MIT Imports: 6 Imported by: 0

README

Tavus-Go SDK

Go CI Go Lint Go SAST Docs Visualization License

Go SDK for the Tavus API.

Tavus provides conversational video interfaces (CVI), video generation, and AI avatar management capabilities.

Installation

go get github.com/plexusone/tavus-go

Quick Start

package main

import (
    "context"
    "log"

    "github.com/plexusone/tavus-go"
    "github.com/plexusone/tavus-go/api"
)

func main() {
    // Create client (reads TAVUS_API_KEY from environment if not provided)
    client, err := tavus.NewClient(tavus.WithAPIKey("your-api-key"))
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // Create a conversation
    conv, err := client.Conversations().Create(ctx, &api.CreateConversationRequest{
        PalID:  api.NewOptString("pal_abc123"),
        FaceID: api.NewOptString("face_xyz789"),
    })
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Conversation created: %s", conv.ConversationID.Value)
    log.Printf("Join URL: %s", conv.ConversationURL.Value)
}

Configuration

Options
// Use environment variable TAVUS_API_KEY
client, _ := tavus.NewClient()

// Explicit API key
client, _ := tavus.NewClient(tavus.WithAPIKey("your-api-key"))

// Custom base URL
client, _ := tavus.NewClient(tavus.WithBaseURL("https://custom.tavusapi.com"))

// Custom timeout
client, _ := tavus.NewClient(tavus.WithTimeout(60 * time.Second))

// Custom HTTP client
client, _ := tavus.NewClient(tavus.WithHTTPClient(&http.Client{
    Transport: customTransport,
}))

Services

Conversations

Real-time video conversation sessions.

// Create a conversation
conv, err := client.Conversations().Create(ctx, &api.CreateConversationRequest{
    PalID:  api.NewOptString("pal_id"),
    FaceID: api.NewOptString("face_id"),
})

// List conversations
list, err := client.Conversations().List(ctx, api.ListConversationsParams{
    Limit: api.NewOptInt(10),
})

// Get a conversation
conv, err := client.Conversations().Get(ctx, "conversation_id")

// End a conversation
err := client.Conversations().End(ctx, "conversation_id")

// Delete a conversation
err := client.Conversations().Delete(ctx, "conversation_id")
PALs (Personality AI Layers)

AI personas with custom instructions and behaviors.

// Create a PAL
pal, err := client.Pals().Create(ctx, &api.CreatePalRequest{
    Name:               "Sales Assistant",
    SystemInstructions: api.NewOptString("You are a helpful sales assistant..."),
})

// List PALs
list, err := client.Pals().List(ctx, api.ListPalsParams{})

// Get a PAL
pal, err := client.Pals().Get(ctx, "pal_id")

// Update a PAL
pal, err := client.Pals().Update(ctx, "pal_id", &api.UpdatePalRequest{
    Name: api.NewOptString("Updated Name"),
})

// Attach a tool to a PAL
err := client.Pals().AttachTool(ctx, "pal_id", "tool_id")

// Delete a PAL
err := client.Pals().Delete(ctx, "pal_id")
Faces

Visual identities for avatars.

// Create/train a face
face, err := client.Faces().Create(ctx, &api.CreateFaceRequest{
    TrainingVideo: "https://example.com/training-video.mp4",
    FaceName:      api.NewOptString("My Avatar"),
})

// List faces
list, err := client.Faces().List(ctx, api.ListFacesParams{})

// Get a face
face, err := client.Faces().Get(ctx, "face_id")

// Rename a face
err := client.Faces().Rename(ctx, "face_id", "New Name")

// Delete a face
err := client.Faces().Delete(ctx, "face_id")
Voices

Stock voices for avatars.

// List available voices
voices, err := client.Voices().List(ctx, api.ListVoicesParams{})
Videos

Async video generation.

// Create a video
video, err := client.Videos().Create(ctx, &api.CreateVideoRequest{
    ReplicaID: "replica_id",
    Script:    "Hello, this is a generated video.",
})

// List videos
list, err := client.Videos().List(ctx, api.ListVideosParams{})

// Get a video
video, err := client.Videos().Get(ctx, "video_id")

// Rename a video
err := client.Videos().Rename(ctx, "video_id", "New Name")

// Delete a video
err := client.Videos().Delete(ctx, "video_id")
Tools

Function calling tools for PALs.

// Create a tool
tool, err := client.Tools().Create(ctx, &api.CreateToolRequest{
    Name:        "get_weather",
    Description: api.NewOptString("Get current weather for a location"),
    Parameters:  api.NewOptCreateToolRequestParameters(params),
})

// List tools
list, err := client.Tools().List(ctx, api.ListToolsParams{})

// Get a tool
tool, err := client.Tools().Get(ctx, "tool_id")

// Update a tool
tool, err := client.Tools().Update(ctx, "tool_id", &api.UpdateToolRequest{
    Description: api.NewOptString("Updated description"),
})

// Delete a tool
err := client.Tools().Delete(ctx, "tool_id")
Guardrails

Behavioral boundaries for conversations.

// Create a guardrail
guardrail, err := client.Guardrails().Create(ctx, &api.CreateGuardrailRequest{
    Name:        "No Personal Info",
    Description: api.NewOptString("Don't ask for personal information"),
})

// List guardrails
list, err := client.Guardrails().List(ctx, api.ListGuardrailsParams{})

// Get a guardrail
guardrail, err := client.Guardrails().Get(ctx, "guardrail_id")

// Update a guardrail
guardrail, err := client.Guardrails().Update(ctx, "guardrail_id", &api.UpdateGuardrailRequest{
    Name: api.NewOptString("Updated Name"),
})

// Delete a guardrail
err := client.Guardrails().Delete(ctx, "guardrail_id")
Objectives

Conversation goals and outcomes.

// Create objectives
objectives, err := client.Objectives().Create(ctx, &api.CreateObjectivesRequest{
    Objectives: []api.Objective{
        {Name: "Book Demo", Description: api.NewOptString("Schedule a demo call")},
    },
})

// List objectives
list, err := client.Objectives().List(ctx, api.ListObjectivesParams{})

// Get objectives
objectives, err := client.Objectives().Get(ctx, "objectives_id")

// Update objectives
objectives, err := client.Objectives().Update(ctx, "objectives_id", &api.UpdateObjectivesRequest{})

// Delete objectives
err := client.Objectives().Delete(ctx, "objectives_id")
Documents

Knowledge base documents for PALs.

// Create/upload a document
doc, err := client.Documents().Create(ctx, &api.CreateDocumentRequest{
    URL:      api.NewOptString("https://example.com/document.pdf"),
    FileName: api.NewOptString("product-guide.pdf"),
})

// List documents
list, err := client.Documents().List(ctx, api.ListDocumentsParams{})

// Get a document
doc, err := client.Documents().Get(ctx, "document_id")

// Update document metadata
doc, err := client.Documents().Update(ctx, "document_id", &api.UpdateDocumentRequest{
    FileName: api.NewOptString("updated-name.pdf"),
})

// Delete a document
err := client.Documents().Delete(ctx, "document_id")
Deployments

Distribution channels for conversations.

// Create a deployment
deployment, err := client.Deployments().Create(ctx, &api.CreateDeploymentRequest{
    Name:  "Production Widget",
    PalID: "pal_id",
})

// List deployments
list, err := client.Deployments().List(ctx, api.ListDeploymentsParams{})

// Get a deployment
deployment, err := client.Deployments().Get(ctx, "deployment_id")

// Update a deployment
deployment, err := client.Deployments().Update(ctx, "deployment_id", &api.UpdateDeploymentRequest{
    Name: api.NewOptString("Updated Name"),
})

// Delete a deployment
err := client.Deployments().Delete(ctx, "deployment_id")

Low-Level API Access

For operations not covered by the high-level wrapper methods, use the underlying ogen-generated client:

client, _ := tavus.NewClient()
apiClient := client.API()

// Direct access to all generated methods
res, err := apiClient.SomeOperation(ctx, params)

Development

Prerequisites
Regenerate API Client
./generate.sh

This regenerates the client from openapi/openapi.yaml and applies post-processing fixes.

License

MIT

Documentation

Overview

Package tavus provides a Go client for the Tavus API.

Tavus is an AI video research company providing conversational video interfaces, video generation, and avatar management capabilities.

The client wraps the ogen-generated API client with a higher-level interface that handles authentication and provides convenient methods for common operations.

Quick Start 

client, err := tavus.NewClient(tavus.WithAPIKey("your-api-key"))
if err != nil {
    log.Fatal(err)
}

// Create a conversation
conv, err := client.Conversations().Create(ctx, &api.CreateConversationRequest{
    PalId:  "pal-id",
    FaceId: "face-id",
})

Environment Variables

If no API key is provided, the client will look for TAVUS_API_KEY in the environment.

Index

Constants

View Source 
const DefaultBaseURL = "https://tavusapi.com"

DefaultBaseURL is the default Tavus API base URL.

View Source 
const Version = "0.1.0"

Version is the SDK version.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the main Tavus client for interacting with the API.

func NewClient 

func NewClient(opts ...Option) (*Client, error)

NewClient creates a new Tavus client with the given options.

func (*Client) API 

func (c *Client) API() *api.Client

API returns the underlying ogen-generated API client for advanced usage. Use this when you need access to API endpoints not covered by the high-level wrapper methods.

func (*Client) APIKey 

func (c *Client) APIKey() string

APIKey returns the API key used by the client.

func (*Client) BaseURL 

func (c *Client) BaseURL() string

BaseURL returns the base URL used by the client.

func (*Client) Conversations 

func (c *Client) Conversations() *ConversationsService

Conversations returns the conversations service for real-time video sessions.

func (*Client) Deployments 

func (c *Client) Deployments() *DeploymentsService

Deployments returns the deployments service for distribution channels.

func (*Client) Documents 

func (c *Client) Documents() *DocumentsService

Documents returns the documents service for knowledge base management.

func (*Client) Faces 

func (c *Client) Faces() *FacesService

Faces returns the faces service for visual identity management.

func (*Client) Guardrails 

func (c *Client) Guardrails() *GuardrailsService

Guardrails returns the guardrails service for behavioral boundaries.

func (*Client) Objectives 

func (c *Client) Objectives() *ObjectivesService

Objectives returns the objectives service for conversation goals.

func (*Client) Pals 

func (c *Client) Pals() *PalsService

Pals returns the PALs service for personality AI layer management.

func (*Client) Tools 

func (c *Client) Tools() *ToolsService

Tools returns the tools service for function calling management.

func (*Client) Videos 

func (c *Client) Videos() *VideosService

Videos returns the videos service for async video generation.

func (*Client) Voices 

func (c *Client) Voices() *VoicesService

Voices returns the voices service for stock voice listing.

type ConversationsService 

type ConversationsService struct {
	// contains filtered or unexported fields
}

ConversationsService handles real-time conversation sessions.

func (*ConversationsService) Create 

func (s *ConversationsService) Create(ctx context.Context, req *api.CreateConversationRequest) (*api.CreateConversationResponse, error)

Create creates a new conversation session.

func (*ConversationsService) Delete 

func (s *ConversationsService) Delete(ctx context.Context, conversationID string) error

Delete deletes a conversation.

func (*ConversationsService) End 

func (s *ConversationsService) End(ctx context.Context, conversationID string) error

End gracefully ends an active conversation.

func (*ConversationsService) Get 

func (s *ConversationsService) Get(ctx context.Context, conversationID string) (*api.Conversation, error)

Get returns a specific conversation.

func (*ConversationsService) List 

func (s *ConversationsService) List(ctx context.Context, params api.ListConversationsParams) (*api.ListConversationsResponse, error)

List returns all conversations.

type DeploymentsService 

type DeploymentsService struct {
	// contains filtered or unexported fields
}

DeploymentsService handles distribution channel management.

func (*DeploymentsService) Create 

func (s *DeploymentsService) Create(ctx context.Context, req *api.CreateDeploymentRequest) (*api.Deployment, error)

Create creates a new deployment.

func (*DeploymentsService) Delete 

func (s *DeploymentsService) Delete(ctx context.Context, deploymentID string) error

Delete deletes a deployment.

func (*DeploymentsService) Get 

func (s *DeploymentsService) Get(ctx context.Context, deploymentID string) (*api.Deployment, error)

Get returns a specific deployment.

func (*DeploymentsService) List 

func (s *DeploymentsService) List(ctx context.Context, params api.ListDeploymentsParams) (*api.ListDeploymentsResponse, error)

List returns all deployments.

func (*DeploymentsService) Update 

func (s *DeploymentsService) Update(ctx context.Context, deploymentID string, req *api.UpdateDeploymentRequest) (*api.Deployment, error)

Update updates a deployment.

type DocumentsService 

type DocumentsService struct {
	// contains filtered or unexported fields
}

DocumentsService handles knowledge base document management.

func (*DocumentsService) Create 

func (s *DocumentsService) Create(ctx context.Context, req *api.CreateDocumentRequest) (*api.CreateDocumentResponse, error)

Create uploads a new document.

func (*DocumentsService) Delete 

func (s *DocumentsService) Delete(ctx context.Context, documentID string) error

Delete deletes a document.

func (*DocumentsService) Get 

func (s *DocumentsService) Get(ctx context.Context, documentID string) (*api.Document, error)

Get returns a specific document.

func (*DocumentsService) List 

func (s *DocumentsService) List(ctx context.Context, params api.ListDocumentsParams) (*api.ListDocumentsResponse, error)

List returns all documents.

func (*DocumentsService) Update 

func (s *DocumentsService) Update(ctx context.Context, documentID string, req *api.UpdateDocumentRequest) (*api.Document, error)

Update updates document metadata.

type FacesService 

type FacesService struct {
	// contains filtered or unexported fields
}

FacesService handles face (visual identity) management.

func (*FacesService) Create 

func (s *FacesService) Create(ctx context.Context, req *api.CreateFaceRequest) (*api.CreateFaceResponse, error)

Create starts training a new face.

func (*FacesService) Delete 

func (s *FacesService) Delete(ctx context.Context, faceID string) error

Delete deletes a face.

func (*FacesService) Get 

func (s *FacesService) Get(ctx context.Context, faceID string) (*api.Face, error)

Get returns a specific face.

func (*FacesService) List 

func (s *FacesService) List(ctx context.Context, params api.ListFacesParams) (*api.ListFacesResponse, error)

List returns all faces.

func (*FacesService) Rename 

func (s *FacesService) Rename(ctx context.Context, faceID, name string) error

Rename renames a face.

type GuardrailsService 

type GuardrailsService struct {
	// contains filtered or unexported fields
}

GuardrailsService handles behavioral boundary management.

func (*GuardrailsService) Create 

func (s *GuardrailsService) Create(ctx context.Context, req *api.CreateGuardrailRequest) (*api.Guardrail, error)

Create creates a new guardrail.

func (*GuardrailsService) Delete 

func (s *GuardrailsService) Delete(ctx context.Context, guardrailID string) error

Delete deletes a guardrail.

func (*GuardrailsService) Get 

func (s *GuardrailsService) Get(ctx context.Context, guardrailID string) (*api.Guardrail, error)

Get returns a specific guardrail.

func (*GuardrailsService) List 

func (s *GuardrailsService) List(ctx context.Context, params api.ListGuardrailsParams) (*api.ListGuardrailsResponse, error)

List returns all guardrails.

func (*GuardrailsService) Update 

func (s *GuardrailsService) Update(ctx context.Context, guardrailID string, req *api.UpdateGuardrailRequest) (*api.Guardrail, error)

Update updates a guardrail.

type ObjectivesService 

type ObjectivesService struct {
	// contains filtered or unexported fields
}

ObjectivesService handles conversation goal management.

func (*ObjectivesService) Create 

func (s *ObjectivesService) Create(ctx context.Context, req *api.CreateObjectivesRequest) (*api.CreateObjectivesResponse, error)

Create creates new objectives.

func (*ObjectivesService) Delete 

func (s *ObjectivesService) Delete(ctx context.Context, objectivesID string) error

Delete deletes objectives.

func (*ObjectivesService) Get 

func (s *ObjectivesService) Get(ctx context.Context, objectivesID string) (*api.Objectives, error)

Get returns specific objectives.

func (*ObjectivesService) List 

func (s *ObjectivesService) List(ctx context.Context, params api.ListObjectivesParams) (*api.ListObjectivesResponse, error)

List returns all objectives.

func (*ObjectivesService) Update 

func (s *ObjectivesService) Update(ctx context.Context, objectivesID string, req *api.UpdateObjectivesRequest) (*api.Objectives, error)

Update updates objectives.

type Option 

type Option func(*clientOptions)

Option is a functional option for configuring the Client.

func WithAPIKey 

func WithAPIKey(apiKey string) Option

WithAPIKey sets the API key for authentication.

func WithBaseURL 

func WithBaseURL(baseURL string) Option

WithBaseURL sets the API base URL.

func WithHTTPClient 

func WithHTTPClient(client *http.Client) Option

WithHTTPClient sets a custom HTTP client.

func WithTimeout 

func WithTimeout(timeout time.Duration) Option

WithTimeout sets the request timeout.

type PalsService 

type PalsService struct {
	// contains filtered or unexported fields
}

PalsService handles PAL (Personality AI Layer) management.

func (*PalsService) AttachTool 

func (s *PalsService) AttachTool(ctx context.Context, palID, toolID string) error

AttachTool attaches a tool to a PAL.

func (*PalsService) Create 

func (s *PalsService) Create(ctx context.Context, req *api.CreatePalRequest) (*api.CreatePalResponse, error)

Create creates a new PAL.

func (*PalsService) Delete 

func (s *PalsService) Delete(ctx context.Context, palID string) error

Delete deletes a PAL.

func (*PalsService) Get 

func (s *PalsService) Get(ctx context.Context, palID string) (*api.Pal, error)

Get returns a specific PAL.

func (*PalsService) List 

func (s *PalsService) List(ctx context.Context, params api.ListPalsParams) (*api.ListPalsResponse, error)

List returns all PALs.

func (*PalsService) Update 

func (s *PalsService) Update(ctx context.Context, palID string, req *api.UpdatePalRequest) (*api.Pal, error)

Update updates a PAL.

type ToolsService 

type ToolsService struct {
	// contains filtered or unexported fields
}

ToolsService handles function calling tool management.

func (*ToolsService) Create 

func (s *ToolsService) Create(ctx context.Context, req *api.CreateToolRequest) (*api.Tool, error)

Create creates a new tool.

func (*ToolsService) Delete 

func (s *ToolsService) Delete(ctx context.Context, toolID string) error

Delete deletes a tool.

func (*ToolsService) Get 

func (s *ToolsService) Get(ctx context.Context, toolID string) (*api.Tool, error)

Get returns a specific tool.

func (*ToolsService) List 

func (s *ToolsService) List(ctx context.Context, params api.ListToolsParams) (*api.ListToolsResponse, error)

List returns all tools.

func (*ToolsService) Update 

func (s *ToolsService) Update(ctx context.Context, toolID string, req *api.UpdateToolRequest) (*api.Tool, error)

Update updates a tool.

type VideosService 

type VideosService struct {
	// contains filtered or unexported fields
}

VideosService handles async video generation.

func (*VideosService) Create 

func (s *VideosService) Create(ctx context.Context, req *api.CreateVideoRequest) (*api.CreateVideoResponse, error)

Create starts generating a new video.

func (*VideosService) Delete 

func (s *VideosService) Delete(ctx context.Context, videoID string) error

Delete deletes a video.

func (*VideosService) Get 

func (s *VideosService) Get(ctx context.Context, videoID string) (*api.Video, error)

Get returns a specific video.

func (*VideosService) List 

func (s *VideosService) List(ctx context.Context, params api.ListVideosParams) (*api.ListVideosResponse, error)

List returns all videos.

func (*VideosService) Rename 

func (s *VideosService) Rename(ctx context.Context, videoID, name string) error

Rename renames a video.

type VoicesService 

type VoicesService struct {
	// contains filtered or unexported fields
}

VoicesService handles stock voice listing.

func (*VoicesService) List 

func (s *VoicesService) List(ctx context.Context, params api.ListVoicesParams) (*api.ListVoicesResponse, error)

List returns available stock voices.

Source Files

View all Source files

Directories

Path Synopsis
Code generated by ogen, DO NOT EDIT.
 Code generated by ogen, DO NOT EDIT.
examples
basic command
Example: Basic conversation creation and management
 Example: Basic conversation creation and management
custom-llm command
Example: Custom LLM backend integration
 Example: Custom LLM backend integration
custom-llm-server command
Example: Custom LLM Server (OpenAI-compatible)
 Example: Custom LLM Server (OpenAI-compatible)
list-resources command
Example: List all Tavus resources
 Example: List all Tavus resources
pal-management command
Example: PAL (Personality AI Layer) management
 Example: PAL (Personality AI Layer) management
tool-calling command
Example: Tool calling with PALs
 Example: Tool calling with PALs

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.