# 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. - This file: https://app.reblium.com/llms.txt (also /llms-full.txt and /web/developers/llms.txt, the same text) - The same reference as a web page: https://app.reblium.com/docs/api - OpenAPI 3 description: https://app.reblium.com/web/developers/openapi.json - Unity package (zip): https://app.reblium.com/web/developers/unity/com.reblium.avatar.zip - Unity package README (step-by-step for an agent): inside the zip, com.reblium.avatar/README.md - Keys: https://app.reblium.com/web/developers.html (a person signs in; an agent cannot make a key) ## 1. Base URL and authentication Base URL: https://app.reblium.com Every /api/v1 request carries the key: Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxx Rules: - A key starts with mk_live_. It is shown once, when it is made on the Developers page. Lost key: make a new one. - Call from an app or a server, never from a web page. A request with an Origin header (every browser sends one) is refused with 400, code "browser". Native apps, curl, Node and Unity send no Origin, so they work. - Never put the key in source code, a scene, a prefab, a commit, a command line or a URL. Read it from a file that is in .gitignore, or from an environment variable. A key typed into a shell command stays in the shell history. - A key inside an app (APK) can be extracted by anyone who has the app. Fine for a prototype or an internal test. For a public release, run a small proxy on your own server that adds the Authorization header and forwards /api/v1/* to the base URL, and point the app at your proxy (section 9). - Responses are JSON (UTF-8) unless stated. Request bodies are JSON with Content-Type: application/json, except /api/v1/lipsync, which takes a WAV body. ## 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. | HTTP | code | meaning | what a client should do | |------|----------------|-----------------------------------------------------------|--------------------------------------------| | 401 | key | key missing, mistyped, or revoked | stop; fix the key | | 400 | browser | the request carried an Origin header | call from the app or a server | | 403 | key_paused | Reblium paused this key | stop; contact Reblium | | 429 | rate_limit | more than 20 speak/chat/lipsync calls in the last minute | wait 30 s, then 60 s; at most 2 retries | | 429 | (no code) | more than 600 API requests in the last hour | wait 30 s, then 60 s; at most 2 retries; then stop for a while | | 429 | daily_limit | today's speech seconds for this key are used up | stop until 00:00 UTC; do not retry | | 400 | bad_request | a field is wrong or missing; `error` says which | fix the request; do not retry as is | | 400 | too_long | text over 1000 characters | split the text | | 404 | not_found | no such avatar on this account, or no such voiceProvider | check the id (GET /api/v1/avatars) | | 415 | bad_type | lipsync body not sent as audio/wav | set Content-Type: audio/wav | | 400 | bad_audio | lipsync body is not a readable WAV | send PCM WAV (section 4, lipsync) | | 413 | too_long | lipsync audio over 30 seconds | split the audio | | 413 | too_large | a body over the size limit | send less | | 502 | voice | the 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 | | 502 | llm | the chat language model failed | retry once | | 503 | not_configured | speech or chat is not set up on this server | stop; contact Reblium | | 503, 504 | (other) | the server or a proxy in front of it is briefly unavailable | retry (1 s, then 2 s) | | 404 | bad_signature | packageUrl damaged or not ours | get a fresh detail, download again | | 410 | expired | packageUrl older than 1 hour | get a fresh detail, download again | Retry policy, in one place (the table above says the same): - 429 other than daily_limit: wait 30 s, then 60 s; at most 2 retries. The window is one minute, so shorter waits do not help. (The server sends no Retry-After header today; if one ever appears, it is in seconds: wait that long.) Refused calls may count toward the limit too, so never retry in a tight loop. Better: pace yourself, at most 20 speak/chat/lipsync calls a minute. - 502 (voice, llm): retry once after 1 s. - 503 other than not_configured, 504, and network failures or timeouts: retry after 1 s, then 2 s. - Everything else: do not retry. - Do retry a POST after a network failure; if the first attempt did reach the server, its seconds count too. - Use a request timeout of about 60 s (speech and chat take a few seconds; a long text more). ## 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 } ] } - id: "av_" and a number; use it in every other call. - thumb: picture URL, or null (no pictures yet). - updated: ISO 8601 time of the last publish. Only this list has it (the detail below does not): use id + updated as the cache key for a downloaded package. - bytes: size of the package zip (at most 40 MB). ### 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.json - avatar.glb: binary glTF 2.0. Nodes: the root "RebliumAvatar", then "MH_head", "MH_teeth", "MH_eyeLeft", "MH_eyeRight", and "cards_*" nodes for hair cards when the character has hair. Blend shapes are glTF morph targets, named through mesh.extras.targetNames; the four MH_* meshes carry the same 60 names (52 ARKit, 8 emotions). No skeleton. Metres, Y up, the face looks along +Z, right-handed, life size; the origin is the bottom of the neck, centred under the head. Textures are JPEG and PNG only (no WebP, Draco or meshopt). glTF MESH names are not set: find meshes by NODE name. 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" } } - face: NODE name of the head mesh. morphMeshes: every node with blend shapes. Drive each name on EVERY mesh in morphMeshes, not only the face: jawOpen moves the lower teeth, eyeLook* moves the eyes. - morphs.arkit: the 52 ARKit names (section 6). morphs.empty: names present but never moving (tongueOut). - morphs.emotions: emotion blend shapes, emo_. Mapping from the API's emotion words in section 5. - voice.voiceId: the ElevenLabs voice chosen in the studio, used when a request names none. - eyes: the point between the eyes, metres, in the package frame (Y up, +Z forward). Useful to put the avatar's eyes at the viewer's eye height. bounds: the head mesh's box, same frame. - hair: one entry per hair card object; "mesh" is its NODE name in avatar.glb (cards_*). Hair has no blend shapes. ### 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 } - Leave optional fields out when you do not use them. (An empty string counts as left out.) - emotion: if absent, a leading tag in the text sets it: "[happy] Great to see you!" speaks "Great to see you!" with emotion happy. No tag and no emotion: "neutral". Default weight 0.6. Names are lowercase letters and underscores; use the words in section 5. 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!" } - audio.base64: a complete WAV file (RIFF header included), 16-bit PCM, mono, 24000 Hz. sampleRate always equals the WAV header's rate; if you ever see them differ, trust the header. - frames: number of curve frames; frames / fps equals the audio length within a frame. - arkit, visemes: curves, format in section 5. encoding describes the format in words. - emotion: always present. name: the emotion word ("neutral" when there is none to show). morph: the package's blend shape to set for it (null for neutral); set that morph to weight, faded (section 5). - text: the words spoken (a leading [tag] removed). - durationMs: audio length in milliseconds; this is what counts toward the daily seconds. ### 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" } - text: what the person said, at most 1000 characters. - history: optional. Earlier messages, oldest first. Each entry is ONE message (a user line or an assistant line), role "user" or "assistant", text at most 4000 characters. At most 20 entries: more is refused (400), so send the last 20. The server keeps no conversation: send the history every time. - voice, voiceProvider, language: as in /speak. emotion: same shapes as in /speak (a name or {name, weight}); it forces the face's emotion instead of the one the model picks. 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 }. - Decode data from base64 to bytes. Its length is frames x C. If it is not, the answer is damaged. - The bytes are frame after frame (row major): frame 0's C values, then frame 1's C values, and so on. Channel order is the order of "names", which is NOT necessarily the order in section 6: always map by name. - Each byte is a weight: value / 255, from 0.0 to 1.0. (Unity blend shapes run 0..100: multiply by 100.) - Frame i is the face at audio time i / fps seconds. The model's lookahead is already undone: frame 0 goes with the first audio sample. 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.name | emotion.morph | |-----------------------|------------------| | neutral | null | | happy | emo_happy | | smile | emo_smile | | excited | emo_excited | | surprised, surprise | emo_surprise | | thinking, thoughtful | emo_thoughtful | | sad | emo_corners_down | | angry | emo_snarl | | disgusted, disgust | emo_disgust | | any other X | emo_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: - Reblium's voice account: leave voiceProvider out. The manifest's voice is used unless "voice" names another ElevenLabs voice id. - Your own ElevenLabs account: a person adds your ElevenLabs API key once on the Developers page, under your own providers, kind "ElevenLabs (your own key)". It is stored encrypted and shown only as its last 4 characters. The page gives it an id like prv_3. Send "voiceProvider": "prv_3" (and your own "voice" id if you like; without one, the manifest's voice id is asked of your account); your ElevenLabs account pays for the characters, and your ElevenLabs key never goes in the app. Limits per key (Reblium can change them per key; the refusal says which one you met): - 20 calls a minute of speak, chat and lipsync together (429 rate_limit). - 3600 seconds (60 minutes) of speech a day, reset at 00:00 UTC (429 daily_limit). Every speak, chat and lipsync answer counts its durationMs, with Reblium's voice or your own. GET requests do not count. GET /api/v1/usage shows today's total. - 600 requests an hour of any /api/v1 route, GETs included (429 without a code). - There is no limit on calls running at once, but send the lines of one avatar in order: split a long text into sentences, request the next while the current one plays, and play them in request order. ## 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: - Forward GET /api/v1/avatars, GET /api/v1/avatars/{id}, POST /api/v1/speak, /chat and /lipsync to the base URL with the same method, path, body and Content-Type, plus "Authorization: Bearer ". - Do not forward an Origin header, and do not forward your users' own Authorization header. - Authenticate your own users first, and rate limit them, so one user cannot spend the key's daily seconds. - Return the status and body unchanged, so error codes still reach the app. - packageUrl points at Reblium directly and needs no key; the app downloads it as it is. 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.