Guides
Custom 3D Models

Custom 3D Models

Bring your own avatars to Avatarium.

Supported Formats

  • GLB/GLTF – Recommended format
  • Ready Player Me – Direct import supported

From Ready Player Me

The easiest way to create a custom avatar:

Step 1: Create Your Avatar

  1. Visit readyplayer.me (opens in a new tab)
  2. Create or customize an avatar
  3. Copy the avatar URL (ends in .glb)

Step 2: Use in Avatarium

<Avatar
  model={{
    type: 'ready-player-me',
    url: 'https://models.readyplayer.me/YOUR_AVATAR_ID.glb'
  }}
/>

Required Morph Targets

Add these parameters to your Ready Player Me URL for lip sync:

?morphTargets=ARKit,Oculus+Visemes,mouthOpen,mouthSmile,eyesClosed,eyesLookUp,eyesLookDown
&textureSizeLimit=1024
&textureFormat=png

Full URL example:

https://models.readyplayer.me/YOUR_ID.glb?morphTargets=ARKit,Oculus+Visemes,mouthOpen,mouthSmile,eyesClosed,eyesLookUp,eyesLookDown&textureSizeLimit=1024&textureFormat=png

From Custom GLB

Requirements

Your 3D model must have:

  1. Standard humanoid skeleton – Head, neck, spine bones
  2. ARKit blend shapes – For lip sync and expressions
  3. Proper scale – 1 unit = 1 meter

Required Blend Shapes

For lip sync to work, include these visemes:

Blend ShapeDescription
viseme_silSilence
viseme_aa"ah" sound
viseme_E"ee" sound
viseme_I"ih" sound
viseme_O"oh" sound
viseme_U"oo" sound
viseme_FF"f/v" sound
viseme_TH"th" sound
viseme_DD"d/t" sound
viseme_kk"k/g" sound
viseme_CH"ch/j" sound
viseme_SS"s/z" sound
viseme_nn"n" sound
viseme_RR"r" sound
viseme_PP"p/b/m" sound

Optional Expression Blend Shapes

Blend ShapeDescription
mouthSmileHappy expression
eyesClosedBlinking
browDownLeftFrowning
browInnerUpConcerned

Uploading Your Model

Via Dashboard

  1. Go to Dashboard > Avatars > Create
  2. Select Custom Model
  3. Upload your GLB file
  4. Configure personality and voice
  5. Save

Via API

POST /v1/avatars
Content-Type: multipart/form-data

{
  "name": "My Custom Avatar",
  "model": <GLB file>,
  "personality": "You are a helpful assistant..."
}

Using Custom Model in SDK

<Avatar
  model={{
    type: 'custom',
    url: 'https://your-cdn.com/avatar.glb'
  }}
  personality="You are a helpful assistant..."
/>

Or reference an uploaded avatar by ID:

<Avatar avatarId="avt_your_custom_avatar" />

Performance Optimization

File Size

  • Keep models under 10MB
  • Compress textures to 1024x1024 or smaller
  • Use Draco compression for geometry

Texture Tips

  • Use PNG for transparency, JPEG for opaque
  • Atlas multiple textures when possible
  • Avoid textures larger than 2048x2048

Polygon Count

  • Target: 20,000-50,000 triangles
  • Mobile: Under 30,000 triangles
  • Test on low-end devices

Testing Your Avatar

In Dashboard

  1. Upload your model
  2. Use the Preview tab
  3. Test lip sync with sample text
  4. Check all expressions work

Common Issues

IssueSolution
Lips don't moveCheck blend shape names match exactly
Avatar too big/smallEnsure 1 unit = 1 meter in export
Textures missingEmbed textures in GLB file
Slow to loadReduce file size and texture resolution

Best Practices

  1. Test on mobile – Most users are on phones
  2. Optimize aggressively – Smaller = faster
  3. Use Ready Player Me – Easiest path to custom avatars
  4. Keep expressions simple – 15 visemes is enough
  5. Validate blend shapes – Use Blender to verify

Upload Custom Avatar → (opens in a new tab)

Voice Mode APIWebhooks