Avatar Providers

MeetLoyd supports multiple AI avatar and voice providers, allowing you to choose the best option for your use case. You can use MeetLoyd's built-in avatars or connect external providers like HeyGen, ElevenLabs, Synthesia, D-ID, or PlayHT.

Overview

Avatar providers fall into two categories:

• Video Providers: Generate AI video with lip-sync (HeyGen, Synthesia, D-ID)
• Voice Providers: Generate AI speech/audio (ElevenLabs, PlayHT)

You can mix providers - for example, use a HeyGen avatar with an ElevenLabs voice.

Supported Providers

MeetLoyd Internal (Default)

Built-in AI avatars powered by Modal. No configuration required.

Feature	Details
Type	Hybrid (video + voice)
Setup	None required
Pricing	Included in plan
Best for	Quick start, cost-effective

HeyGen

Professional AI video generation with photorealistic avatars.

Feature	Details
Type	Video
Setup	API Key
Pricing	From $29/mo
Best for	Marketing videos, sales demos

Features:

• Photorealistic avatars
• Custom avatar creation
• Multi-language support
• Lip sync

ElevenLabs

Industry-leading AI voice synthesis with voice cloning.

Feature	Details
Type	Voice
Setup	API Key
Pricing	From $5/mo
Best for	Voice-first applications, podcasts

Features:

• Voice cloning
• 29+ languages
• Emotion control
• Ultra-realistic speech

Synthesia

Enterprise video generation with compliance-ready avatars.

Feature	Details
Type	Video
Setup	API Key
Pricing	Enterprise
Best for	Corporate training, compliance

Features:

• 140+ languages
• SOC 2 compliant
• Custom avatars
• Enterprise support

D-ID

Creative AI video generation with expressive avatars.

Feature	Details
Type	Video
Setup	API Key
Pricing	From $5.99/mo
Best for	Creative content, social media

Features:

• Creative styles
• Photo-to-video
• Real-time generation
• Expression control

PlayHT

Ultra-realistic text-to-speech with voice cloning.

Feature	Details
Type	Voice
Setup	API Key + User ID
Pricing	From $39/mo
Best for	Podcasts, audiobooks

Features:

• Ultra-realistic voices
• Voice cloning
• SSML support
• 100+ voices

Configuration

Via Dashboard

1. Navigate to Settings > Avatar Providers
2. Select a provider
3. Enter your API credentials
4. Click Test Connection to verify
5. Click Save

Via API

POST /api/avatar-providers/config
Content-Type: application/json
Authorization: Bearer <token>

{
  "providerId": "heygen",
  "credentials": {
    "apiKey": "hg_xxxxx"
  },
  "enabled": true,
  "isDefault": true,
  "config": {
    "defaultAvatarId": "avatar-123"
  }
}

Via Team Manifest

{
  "components": {
    "avatars": [
      {
        "ref": "external://heygen/avatar-emma-professional",
        "localId": "emma",
        "config": {
          "voiceProvider": "elevenlabs",
          "voiceId": "voice-rachel"
        }
      }
    ]
  }
}

Provider Comparison

Provider	Video	Voice	Cloning	Languages	Realtime	Starting Price
Internal	✅	✅	❌	10+	✅	Included
HeyGen	✅	✅	✅	40+	❌	$29/mo
ElevenLabs	❌	✅	✅	29+	✅	$5/mo
Synthesia	✅	✅	✅	140+	❌	Enterprise
D-ID	✅	✅	❌	100+	✅	$5.99/mo
PlayHT	❌	✅	✅	142+	✅	$39/mo

Using Avatars

Generate Video

import { generateVideo } from '@meetloyd/avatars'

const result = await generateVideo({
  providerId: 'heygen',
  text: 'Hello! Welcome to our demo.',
  avatarId: 'avatar-emma',
  voiceId: 'voice-professional',
  settings: {
    resolution: '1080p',
    background: 'office'
  }
})

console.log(result.videoUrl)

Generate Audio Only

import { generateAudio } from '@meetloyd/avatars'

const result = await generateAudio({
  providerId: 'elevenlabs',
  text: 'This is a voice-only message.',
  voiceId: 'voice-rachel',
  settings: {
    stability: 0.5,
    clarity: 0.75
  }
})

console.log(result.audioUrl)

Clone a Voice

import { cloneVoice } from '@meetloyd/avatars'

const result = await cloneVoice({
  providerId: 'elevenlabs',
  name: 'CEO Voice',
  samples: [
    'https://example.com/sample1.mp3',
    'https://example.com/sample2.mp3'
  ],
  description: 'Professional male voice'
})

console.log(result.voiceId)

Fallback Behavior

Configure fallback providers for reliability:

{
  "avatarProviders": [
    { "providerId": "heygen", "priority": 1 },
    { "providerId": "d-id", "priority": 2 },
    { "providerId": "internal", "priority": 3 }
  ]
}

If the primary provider fails, MeetLoyd automatically tries the next in priority order.

Health Monitoring

Check provider health status:

import { healthCheckProvider } from '@meetloyd/avatars'

const health = await healthCheckProvider('heygen')
// { healthy: true, latencyMs: 234 }

Dashboard Health View

Navigate to Settings > Avatar Providers to see:

• Current health status
• Latency metrics
• Usage this month
• Error rates

Credential Security

• Credentials are encrypted at rest using AES-256
• Credentials are never logged or exposed
• API keys are transmitted over HTTPS only
• Credentials can be rotated without downtime

Best Practices

1. Choose the Right Provider

• Marketing videos: HeyGen or Synthesia
• Voice-first apps: ElevenLabs
• Cost-conscious: Internal or D-ID
• Enterprise/Compliance: Synthesia

2. Configure Fallbacks

Always configure at least one fallback provider to ensure availability.

3. Monitor Usage

External providers often have usage limits. Monitor your usage in the dashboard to avoid service interruptions.

4. Cache Generated Content

Video generation can be slow. Cache results for frequently-used content:

const cached = await getCachedVideo(text, avatarId)
if (cached) return cached

const video = await generateVideo({ ... })
await cacheVideo(text, avatarId, video)
return video

5. Test in Development

Use lower-quality settings for development to save costs:

const settings = process.env.NODE_ENV === 'development'
  ? { resolution: '480p', quality: 'draft' }
  : { resolution: '1080p', quality: 'production' }

API Reference

List Available Providers

GET /api/avatar-providers

Get Provider Config

GET /api/avatar-providers/:providerId

Update Provider Config

PUT /api/avatar-providers/:providerId
Content-Type: application/json

{
  "enabled": true,
  "isDefault": false,
  "priority": 2
}

Validate Credentials

POST /api/avatar-providers/:providerId/validate
Content-Type: application/json

{
  "credentials": {
    "apiKey": "xxx"
  }
}

Health Check

GET /api/avatar-providers/:providerId/health

List Provider Avatars

GET /api/avatar-providers/:providerId/avatars

List Provider Voices

GET /api/avatar-providers/:providerId/voices

Troubleshooting

"Invalid API Key"

1. Verify the API key is correct
2. Check if the key has the required permissions
3. Ensure the key hasn't expired
4. Try regenerating the key in the provider's dashboard

"Rate Limited"

1. Check your plan limits with the provider
2. Implement exponential backoff
3. Consider upgrading your plan
4. Use caching to reduce API calls

"Generation Failed"

1. Check the provider's status page
2. Try a different avatar/voice
3. Reduce text length
4. Try the fallback provider

"Slow Generation"

1. Video generation typically takes 30-120 seconds
2. Use webhooks for async generation
3. Pre-generate common content
4. Consider using audio-only for faster response

See Also

• Team Manifests - Use avatars in manifests
• Avatars Overview - General avatar concepts
• Streaming - Real-time audio streaming