LiveAvatar API Reference¶

Package liveavatar provides access to the LiveAvatar real-time streaming API.

import "github.com/plexusone/heygen-go/liveavatar"

Constants¶

const (
    DefaultBaseURL  = "https://api.liveavatar.com"
    EnvAPIKey       = "LIVEAVATAR_API_KEY"
    DefaultTimeout  = 30 * time.Second
    SandboxAvatarID = "65f9e3c9-d48b-4118-b73a-4ae2e3cbb8f0"
)

Video Quality¶

type VideoQuality string

const (
    QualityVeryHigh VideoQuality = "very_high"
    QualityHigh     VideoQuality = "high"
    QualityMedium   VideoQuality = "medium"
    QualityLow      VideoQuality = "low"
)

Stop Reasons¶

type StopReason string

const (
    StopReasonUserDisconnected StopReason = "USER_DISCONNECTED"
    StopReasonSessionEnded     StopReason = "SESSION_ENDED"
)

Types¶

Config¶

Configuration for the LiveAvatar client.

type Config struct {
    APIKey     string       // API key (or LIVEAVATAR_API_KEY env var)
    BaseURL    string       // API base URL (default: https://api.liveavatar.com)
    HTTPClient *http.Client // Custom HTTP client
}

LiveKitConfig¶

LiveKit room configuration for LITE mode.

type LiveKitConfig struct {
    LiveKitURL         string `json:"livekit_url"`
    LiveKitRoom        string `json:"livekit_room"`
    LiveKitClientToken string `json:"livekit_client_token"`
}

Field	Description
`LiveKitURL`	LiveKit server URL (wss://...)
`LiveKitRoom`	Room name for the avatar to join
`LiveKitClientToken`	JWT token with room_join, can_publish, can_subscribe, can_publish_data

NewSessionRequest¶

Parameters for creating a streaming session.

type NewSessionRequest struct {
    Mode          string         `json:"mode"`
    AvatarID      string         `json:"avatar_id"`
    IsSandbox     bool           `json:"is_sandbox,omitempty"`
    VideoQuality  VideoQuality   `json:"video_quality,omitempty"`
    LiveKitConfig *LiveKitConfig `json:"livekit_config,omitempty"`
}

Field	Description
`Mode`	Session mode: `"LITE"` for BYO AI stack
`AvatarID`	UUID of the avatar to use
`IsSandbox`	Enable sandbox mode (60s limit, no credits)
`VideoQuality`	Avatar video quality
`LiveKitConfig`	LiveKit configuration (required for LITE mode)

NewSessionResponse¶

Response from creating a session.

type NewSessionResponse struct {
    SessionID    string `json:"session_id"`
    SessionToken string `json:"session_token"`
}

StartSessionResponse¶

Response from starting a session.

type StartSessionResponse struct {
    SessionID          string `json:"session_id"`
    WSURL              string `json:"ws_url"`
    MaxSessionDuration int    `json:"max_session_duration"`
}

Field	Description
`SessionID`	Unique session identifier
`WSURL`	WebSocket URL for streaming audio/events
`MaxSessionDuration`	Maximum session duration in seconds

Functions¶

NewClient¶

Creates a new LiveAvatar client.

func NewClient(cfg *Config) (*Client, error)

Example:

// Using environment variable
client, err := liveavatar.NewClient(nil)

// With explicit API key
client, err := liveavatar.NewClient(&liveavatar.Config{
    APIKey: "your-api-key",
})

Methods¶

NewSession¶

Creates a new streaming session and returns session credentials.

func (c *Client) NewSession(ctx context.Context, req *NewSessionRequest) (*NewSessionResponse, error)

Example:

resp, err := client.NewSession(ctx, &liveavatar.NewSessionRequest{
    Mode:      "LITE",
    AvatarID:  liveavatar.SandboxAvatarID,
    IsSandbox: true,
    LiveKitConfig: &liveavatar.LiveKitConfig{
        LiveKitURL:         "wss://project.livekit.cloud",
        LiveKitRoom:        "my-room",
        LiveKitClientToken: lkToken,
    },
})

StartSession¶

Starts a streaming session and returns the WebSocket URL.

func (c *Client) StartSession(ctx context.Context, sessionID, sessionToken string) (*StartSessionResponse, error)

Example:

startResp, err := client.StartSession(ctx, resp.SessionID, resp.SessionToken)
fmt.Printf("WebSocket: %s\n", startResp.WSURL)

StopSession¶

Stops a streaming session.

func (c *Client) StopSession(ctx context.Context, sessionID, sessionToken string, reason StopReason) error

Example:

err := client.StopSession(ctx, sessionID, sessionToken, liveavatar.StopReasonUserDisconnected)

Error Codes¶

Code	Description
1000	Success
4000	Validation error (check request format)
4010	Invalid credentials (check API key)

Public Avatar Catalog¶

The liveavatar package ships a static catalog of HeyGen public avatars, so you can look them up without an API call.

import "github.com/plexusone/heygen-go/liveavatar"

// All 26 public + photo avatars
for _, a := range liveavatar.PublicAvatars {
    fmt.Println(a.ID, a.Name)
}

// Lookups and filters
josh, ok := liveavatar.GetAvatarByID(liveavatar.AvatarJoshua)
byName, ok := liveavatar.GetAvatarByName("Joshua")
women := liveavatar.GetAvatarsByGender("female")
photos := liveavatar.GetAvatarsByType("photo")

// Recommended avatars for AI panel discussions
panel := liveavatar.PanelPresets

Avatar constants (e.g. liveavatar.AvatarJoshua) are provided for common avatars.