Bring Your Own Key (BYOK)

Use your own AI and TTS provider API keys with Avatarium. All plans support BYOK – configure it in the dashboard or pass keys via the SDK.

Supported Providers

AI Providers

Provider	API Key Format	Models
Anthropic	`sk-ant-...`	claude-sonnet-4-6, claude-haiku-4-5-20251001, claude-opus-4
OpenAI	`sk-...`	gpt-4o, gpt-4o-mini, gpt-4.1
Google	`AIzaSy...`	gemini-2.5-pro, gemini-2.5-flash
Groq	`gsk_...`	llama-3.3-70b-versatile, mixtral-8x7b-32768

Without BYOK, Avatarium uses Anthropic Claude as the built-in AI provider. BYOK lets you use any supported provider with your own API key.

TTS Providers

Provider	API Key Format
ElevenLabs	`xi_...`

SDK Setup

Pass your keys via byokAI and byokTTS props:

import { Avatar } from '@avatarium/react';
 
function MyAvatar() {
  return (
    <Avatar
      apiKey="av_live_xxxxx"
      avatarId="8yb8p7oj3sK"
      byokAI={{
        provider: 'anthropic',
        apiKey: process.env.NEXT_PUBLIC_ANTHROPIC_KEY,
        model: 'claude-sonnet-4-6'
      }}
      byokTTS={{
        provider: 'elevenlabs',
        apiKey: process.env.NEXT_PUBLIC_ELEVENLABS_KEY,
        voice: 'EXAVITQu4vr4xnSDxMaL'
      }}
    />
  );
}

🚫

Never expose API keys in client-side JavaScript. Use environment variables or a server-side proxy to inject keys at request time.

Configuration Reference

interface BYOKAIProviderConfig {
  provider: 'anthropic' | 'openai' | 'gemini' | 'groq';
  apiKey: string;
  model?: string;
}
 
interface BYOKTTSProviderConfig {
  provider: 'elevenlabs';
  apiKey: string;
  voice?: string;
}

Provider Examples

<Avatar
  byokAI={{
    provider: 'anthropic',
    apiKey: 'sk-ant-xxxxx',
    model: 'claude-sonnet-4-6'
  }}
/>

Server-Side Proxy (Recommended)

Inject keys from your backend to avoid exposing them in the client:

// pages/api/avatar-config.ts (Next.js example)
export default function handler(req, res) {
  res.json({
    byokAI: {
      provider: 'anthropic',
      apiKey: process.env.ANTHROPIC_API_KEY,  // server-only env var
    }
  });
}

Security Best Practices

Do	Don't
Store keys in environment variables	Hardcode in source
Use a secrets manager (AWS, GCP, etc.)	Commit to git
Rotate keys periodically	Share keys across environments

Troubleshooting

"Invalid API key" – verify the key is active and has the required permissions in your provider's dashboard.

"Rate limit exceeded" – this is from the provider, not Avatarium. Check your provider's quotas.

BYOK not working – ensure provider matches your key type and apiKey is a valid string (not undefined).

Next Steps

Brain Configuration – full brain setup options
Voice Configuration – configure TTS voices
SDK Reference – full component API

Embedding Going to Production