Reblium Avatar API

Load a Reblium 3D avatar (a MetaHuman head built in the Reblium studio) into your own app and make it talk. You send text; Reblium answers with the voice as a WAV file plus the face movement as 52 Apple ARKit blend shape curves at 100 frames a second, made by Reblium's own lipsync model on Reblium's server. The voice is Reblium's ElevenLabs account or your own. Built for XREAL glasses (Unity, Android, IL2CPP); the data works in any engine.

This file is written for people and for AI coding agents. Everything needed to integrate is here or linked from here.

1. Base URL and authentication

Base URL: https://app.reblium.com

Every /api/v1 request carries the key:

Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Rules:

2. Where avatars come from

Avatars are published from the Reblium studio, not through this API. In the studio a person opens their character, saves it to their account (Save, Cloud) under its name, then in the Export panel picks the preset "API / XR" and presses "Publish to API". Publishing again replaces the package and keeps the same avatar id. The ids (like av_12) are listed by GET /api/v1/avatars for any key of that account.

3. Errors

Every error is an HTTP status of 400 or more with this JSON body:

{ "error": "a sentence for a person", "code": "machine_readable_reason", "reason": "machine_readable_reason" }

Switch on the HTTP status and code together (too_long comes as 400 for text and 413 for audio; a 404 is not_found from the API or bad_signature from a package link). If code is missing, use reason; if both are missing (the hourly limit's 429, a 405), the body is only { "error": "..." }: use the HTTP status. error is for logs and people, its wording can change.

HTTPcodemeaningwhat a client should do
401keykey missing, mistyped, or revokedstop; fix the key
400browserthe request carried an Origin headercall from the app or a server
403key_pausedReblium paused this keystop; contact Reblium
429rate_limitmore than 20 speak/chat/lipsync calls in the last minutewait 30 s, then 60 s; at most 2 retries
429(no code)more than 600 API requests in the last hourwait 30 s, then 60 s; at most 2 retries; then stop for a while
429daily_limittoday's speech seconds for this key are used upstop until 00:00 UTC; do not retry
400bad_requesta field is wrong or missing; error says whichfix the request; do not retry as is
400too_longtext over 1000 characterssplit the text
404not_foundno such avatar on this account, or no such voiceProvidercheck the id (GET /api/v1/avatars)
415bad_typelipsync body not sent as audio/wavset Content-Type: audio/wav
400bad_audiolipsync body is not a readable WAVsend PCM WAV (section 4, lipsync)
413too_longlipsync audio over 30 secondssplit the audio
413too_largea body over the size limitsend less
502voicethe voice service failed (with your own ElevenLabs key: your account refused; the message says why)retry once; with your own key, check its credit and voice id
502llmthe chat language model failedretry once
503not_configuredspeech or chat is not set up on this serverstop; contact Reblium
503, 504(other)the server or a proxy in front of it is briefly unavailableretry (1 s, then 2 s)
404bad_signaturepackageUrl damaged or not oursget a fresh detail, download again
410expiredpackageUrl older than 1 hourget a fresh detail, download again

Retry policy, in one place (the table above says the same):

4. Routes

GET /api/v1/avatars

The avatars of the key's account (published from the studio, section 2), newest first.

Response 200:

{
  "avatars": [
    { "id": "av_12", "name": "Ada", "thumb": null, "updated": "2026-11-17T10:00:00.000Z", "bytes": 21634512 }
  ]
}

GET /api/v1/avatars/{id}

Response 200:

{
  "id": "av_12",
  "name": "Ada",
  "manifest": { ...the manifest, below... },
  "packageUrl": "https://app.reblium.com/api/v1/avatars/av_12/package?exp=1763380000&sig=0123456789abcdef0123456789abcdef"
}

packageUrl is an absolute https URL to the package zip, signed and valid for 1 hour (exp in it is the expiry in Unix seconds; the signature covers it, so do not edit the URL). Download it with a plain GET and NO Authorization header (it needs none; never send the key anywhere it is not needed). An old link answers 410 "expired", a damaged one 404 "bad_signature": on either, ask for the detail again and download from the new link, once. The manifest here is the same as manifest.json inside the package.

The package is a standard zip (deflate or stored entries, no Zip64, no encryption; check each entry's CRC-32 if your unzip does not) with two files at its root:

Manifest (version 1; fields may be added later, ignore the ones you do not know):

{
  "version": 1,
  "name": "Ada",
  "units": "m",
  "up": "Y",
  "forward": "+Z",
  "handedness": "right",
  "face": "MH_head",
  "morphMeshes": ["MH_head", "MH_teeth", "MH_eyeLeft", "MH_eyeRight"],
  "morphs": {
    "arkit": ["eyeBlinkLeft", "...", "tongueOut"],
    "emotions": ["emo_happy", "emo_smile", "emo_excited", "emo_surprise", "emo_thoughtful", "emo_corners_down", "emo_snarl", "emo_disgust"],
    "empty": ["tongueOut"]
  },
  "voice": { "provider": "reblium", "voiceId": "21m00Tcm4TlvDq8ikWAM" },
  "eyes": [0, 0.249, 0.063],
  "bounds": { "min": [-0.149, 0, -0.101], "max": [0.149, 0.349, 0.101] },
  "hair": [{ "mesh": "cards_long", "kind": "long", "triangles": 24000 }],
  "textures": { "size": 2048 },
  "pivot": { "at": "bottom of the neck, centred under the head" }
}

POST /api/v1/speak

Text in, voice and face curves out.

Request (the // notes explain the fields; they are not part of the JSON you send):

{
  "avatar": "av_12",                  // required
  "text": "Hello there!",             // required, at most 1000 characters; one or two sentences per call is best
  "voice": "21m00Tcm4TlvDq8ikWAM",    // optional ElevenLabs voice id (10 to 40 letters and digits); default: the manifest's voice
  "voiceProvider": "prv_3",           // optional; leave out for Reblium's voice account, prv_N for your own ElevenLabs key (section 7)
  "emotion": "happy",                 // optional: a name, or {"name": "happy", "weight": 0.8}
  "language": "en"                    // optional code like en, nl, fr; default: from the text
}

Response 200:

{
  "audio": { "format": "wav", "sampleRate": 24000, "base64": "UklGR..." },
  "fps": 100,
  "frames": 182,
  "encoding": "uint8-base64, value = byte / 255, frames x channels, row major",
  "arkit":   { "names": [52 names], "data": "base64..." },
  "visemes": { "names": [14 names], "data": "base64..." },
  "emotion": { "name": "happy", "weight": 0.6, "morph": "emo_happy" },
  "durationMs": 1820,
  "text": "Hello there!"
}

POST /api/v1/chat

The avatar answers in character (its role, rules and language are set in the studio's chat settings), in 1 to 3 short spoken sentences, and the answer is spoken.

Request:

{
  "avatar": "av_12",
  "text": "What can you do?",
  "history": [
    { "role": "user", "text": "Hi!" },
    { "role": "assistant", "text": "Hello! Nice to meet you." }
  ],
  "voice": "...", "voiceProvider": "prv_3", "language": "en", "emotion": "happy"
}

Response 200: the same object as /speak, plus "reply" (the answer; the same words as "text"). The model tags its own answer with one of neutral, happy, sad, angry, surprised, thinking; that becomes emotion.name.

POST /api/v1/lipsync

Face curves for audio you made yourself (your own TTS, a recording).

Request: the body is a WAV file with Content-Type: audio/wav. Accepted: 16, 24 or 32-bit integer PCM, or 32-bit float; mono or stereo; 8 to 192 kHz; at most 30 seconds (longer: 413 too_long; not a WAV: 400 bad_audio; another Content-Type: 415 bad_type).

Response 200: { "fps", "frames", "encoding", "arkit", "visemes", "durationMs" } as in /speak, without "audio", "emotion" or "text". Play your own audio and the curves together from time 0.

GET /api/v1/usage

This key's use today. The 3D avatar API's part is "speech" (the other fields are for Reblium's video avatars):

{
  "speech": { "secondsToday": 42.6, "callsToday": 17, "maxDailySeconds": 3600 },
  "...": "other fields, for video avatars"
}

speech is null if the count is unavailable for a moment. Check it before a long session rather than polling it; it counts toward the hourly request limit.

5. Curves and emotions

A curve track is { "names": [C strings], "data": base64 }.

Reading a weight at audio time t seconds (linear interpolation, clamped at both ends):

f = t * fps
if f <= 0: value = byte[0*C + c] / 255
else:
  i = floor(f), a = f - i
  if i >= frames - 1: value = byte[(frames-1)*C + c] / 255
  else: value = (byte[i*C + c] * (1-a) + byte[(i+1)*C + c] * a) / 255

Drive the face from the audio player's own clock (in Unity, AudioSource.timeSamples / clip.frequency), not from a frame counter or wall clock, so face and voice stay together after a hitch. Add every curve as it comes: mouthClose is authored over an open jaw (Apple's definition), so jawOpen 1 + mouthClose 1 is a dropped jaw with sealed lips (M, B, P).

When nothing is playing, ease every ARKit weight back to 0 over about 0.1 s. Add your own blinks (eyeBlinkLeft and eyeBlinkRight to 1 for about 0.15 s every 2.5 to 5.5 s), taking the larger of the blink and the curve.

Emotions. Use emotion.morph: it is the blend shape to set (null for neutral). If emotion.morph names a shape the avatar does not have, show nothing. For reference, this is how the server picks it from emotion.name (the studio's own table):

emotion.nameemotion.morph
neutralnull
happyemo_happy
smileemo_smile
excitedemo_excited
surprised, surpriseemo_surprise
thinking, thoughtfulemo_thoughtful
sademo_corners_down
angryemo_snarl
disgusted, disgustemo_disgust
any other Xemo_X

Fade the morph in over about 0.35 s to emotion.weight and out over about 0.8 s after the line. Show emo_thoughtful only as a short glance (about 2 s, then back to neutral), not for a whole answer.

6. Names

The 52 ARKit names (Apple's standard set):

eyeBlinkLeft, eyeLookDownLeft, eyeLookInLeft, eyeLookOutLeft, eyeLookUpLeft, eyeSquintLeft, eyeWideLeft, eyeBlinkRight, eyeLookDownRight, eyeLookInRight, eyeLookOutRight, eyeLookUpRight, eyeSquintRight, eyeWideRight, jawForward, jawLeft, jawRight, jawOpen, mouthClose, mouthFunnel, mouthPucker, mouthLeft, mouthRight, mouthSmileLeft, mouthSmileRight, mouthFrownLeft, mouthFrownRight, mouthDimpleLeft, mouthDimpleRight, mouthStretchLeft, mouthStretchRight, mouthRollLower, mouthRollUpper, mouthShrugLower, mouthShrugUpper, mouthPressLeft, mouthPressRight, mouthLowerDownLeft, mouthLowerDownRight, mouthUpperUpLeft, mouthUpperUpRight, browDownLeft, browDownRight, browInnerUp, browOuterUpLeft, browOuterUpRight, cheekPuff, cheekSquintLeft, cheekSquintRight, noseSneerLeft, noseSneerRight, tongueOut

Left and Right are the face's own: eyeBlinkLeft closes the avatar's left eye (screen right when it faces you).

The 14 visemes (for engines that animate by viseme instead of ARKit; same format, same frames): sil, aa, E, I, O, U, PP, FF, DD, kk, CH, SS, nn, RR

7. Voices and limits

Voices:

Limits per key (Reblium can change them per key; the refusal says which one you met):

8. Quick test with curl (bash)

Keep the key in a file, never in the command. A person creates ~/.reblium_key with a text editor and pastes the key into it (not with echo or printf: the shell would keep the key in its history). Then:

KEY="$(cat ~/.reblium_key)"
curl -s https://app.reblium.com/api/v1/avatars -H "Authorization: Bearer $KEY"
curl -s https://app.reblium.com/api/v1/speak -H "Authorization: Bearer $KEY" \
     -H "Content-Type: application/json" -d '{"avatar":"av_12","text":"Hello there!"}' > answer.json

In a program, read the file (or an environment variable) yourself; never print the key or log a request's headers.

9. Production: proxy through your own server

The app talks to your server; your server adds the key. Rules for the proxy:

In the Unity package, set RebliumSettings.baseUrl to your proxy and leave the key file out of the build.

10. Unity (XREAL glasses, Android, IL2CPP)

Use the package com.reblium.avatar (link at the top). It has no dependency but Unity's own glTFast, and is safe for IL2CPP: no reflection, no threads, its own zip reader, UnityWebRequest for HTTP. It does everything in sections 4 and 5 (emotion table, thinking glance, blinks, audio clock, retries, package cache, expired links). Steps in short (the README in the package has every detail and the exact files to write):

  1. Unzip the package into the Unity project's Packages/ folder, so Packages/com.reblium.avatar/package.json exists. Unity fetches com.unity.cloud.gltfast 6.8.0 by itself on the next import.
  2. Add /Assets/Resources/RebliumKey.txt and /Assets/Resources/RebliumKey.txt.meta to .gitignore. Then have the person put their key in Assets/Resources/RebliumKey.txt (one line, nothing else).
  3. Copy Samples~/XrealDemo/XrealDemo.cs and XrealDemoBoot.cs into Assets/Reblium/. Press Play: the first avatar of the key appears 1 m in front of the camera and says hello.
  4. In your own code: a GameObject with RebliumAvatar, an AudioSource and RebliumSpeaker; call speaker.Say("text") or speaker.Ask("question"). Errors arrive in speaker.Failed as RebliumException with .Code.
  5. Android: run the Editor methods Reblium.EditorTools.RebliumSetup.ConfigureAndroid (IL2CPP, ARM64, internet) and IncludeGltfShaders, then RebliumSetup.SmokeTest to call the real API from the command line. Install the XREAL SDK for Unity following XREAL's own documentation; this package does not depend on it and needs nothing from it.

11. Other engines

Any engine that loads glTF 2.0 with morph targets works: load avatar.glb, look up blend shapes by name on the morphMeshes nodes, play the WAV, set weights from the curves at the audio clock (section 5). three.js: GLTFLoader, mesh.morphTargetDictionary[name], mesh.morphTargetInfluences[index] = value. Unreal: glTFRuntime or Interchange, morph target names as above.