API Endpoints

rooomAvatars API endpoints for avatar registration, GLB model downloads, preview images, and built-in animation files.

All examples use https://api.avatars.rooom.com as the rooomAvatars API base URL. For staging editor deployments, see Discovering the API base URL.

Avatar Registration

POST /avatar

POST /avatar

Registers an avatar configuration and returns the created avatar ID with model and preview URLs.

INFO

When you embed the editor iframe, the editor calls this endpoint after the user completes the flow. Call it directly only when you register avatar settings from your own backend or application code.

• Auth: required (Authorization: Bearer ...)
• Body: avatar settings JSON (see Configuration Schema)

Register an avatar configuration with cURL or JavaScript:

Request (cURL)

# API_TOKEN is your rooomAvatars API token.
curl -X POST "https://api.avatars.rooom.com/avatar" \
  -H "Authorization: Bearer API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"version":"1.0.0"}'

Request (fetch)

// API_TOKEN is your rooomAvatars API token.
const response = await fetch('https://api.avatars.rooom.com/avatar', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ version: '1.0.0' }),
});

Replace API_TOKEN with the token for your rooomAvatars integration.

The response includes the registered avatar ID and download URLs:

{
  "status": "ok",
  "data": {
    "modelId": "AVATAR_ID",
    "modelUrl": "https://api.avatars.rooom.com/model/AVATAR_ID.glb",
    "previewUrl": "https://api.avatars.rooom.com/preview/AVATAR_ID.png"
  }
}

Replace AVATAR_ID with the ID returned as modelId.

Resolving the project default avatar

Send an empty JSON object ({}) as the body to receive the project's configured default avatar. The API resolves it to a random or predefined avatar based on the integration's settings and returns the same response shape as a regular registration.

# API_TOKEN is your rooomAvatars API token.
curl -X POST "https://api.avatars.rooom.com/avatar" \
  -H "Authorization: Bearer API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'

Use this when your application needs to render an avatar before the user has gone through the editor flow.

Built-in default avatars

The IDs default-male and default-female are reserved pseudo-IDs that resolve to a built-in masculine or feminine avatar without a prior POST /avatar call. They work on every endpoint that takes an :id (/model/:id.glb, /preview/:id.{png,jpg,webp}).

curl -o avatar.glb     "https://api.avatars.rooom.com/model/default-male.glb"
curl -o avatar-preview.png "https://api.avatars.rooom.com/preview/default-female.png"

Use them as an immediate fallback while a user's freshly-registered avatar is still being generated, or as a generic placeholder when no avatar has been registered yet.

Model Downloads

GET /model/:id.glb

GET /model/:id.glb

Downloads the .glb model file for a previously registered avatar. The .glb extension is required in the URL path.

• Auth: not required
• Response: binary .glb file (Content-Type: application/octet-stream or as set by the server)

Query parameters:

Parameter	Value	Effect
lod	0, 1, 2	Level of detail. 0 is highest quality (default).
animations	all, none, locomotion, locomotions, gesture, gestures, or comma-separated list	Which animations to include in the model. Default: none.
textureFormat	webp, png, compat	Texture format for the model textures. Default: webp.
mergeMesh	0, 1	Merge all meshes into a single mesh. Default: 0.
textureAtlasSize	integer, 64–2048	Size of the texture atlas in pixels (must be a power of 2). Default: 1024.

Choosing a textureFormat

Value	When to use
webp (default)	Web viewers and any modern engine that reads WebP. Smallest file size, best for browser delivery.
png	When you need lossless textures (e.g. for further authoring or post-processing). Largest files.
compat	Engines that cannot read WebP (some Unity, Unreal or older 3D pipelines). Opaque textures are encoded as JPEG, transparent ones as PNG, and the EXT_texture_webp extension is stripped.

Recommended parameters

For most use cases, the defaults already give a good balance of quality, file size, and runtime performance. The one setting you typically want to change is mergeMesh=1, which reduces draw calls and speeds up rendering on the GPU.

Leave the other parameters at their defaults:

• textureAtlasSize defaults to 1024 — enough detail for most viewports while keeping the texture payload small.
• animations defaults to none — keep animations out of the model file. Download them separately via GET /animations/:gender/:name.glb and bake them into the rig at runtime so you can reuse the same animations across multiple avatars.
• textureFormat defaults to webp for the smallest file size. Switch to compat only when targeting engines that cannot decode WebP (see Choosing a textureFormat).

When you need multiple LODs, request them one after another on demand instead of preloading them in parallel. Each LOD is generated in the background, and concurrent requests delay the one you actually want to display first.

If model generation fails, the server returns a JSON error response.

Download a generated model with cURL or JavaScript:

Request (cURL)

# AVATAR_ID is the registered avatar ID.
curl -o avatar.glb "https://api.avatars.rooom.com/model/AVATAR_ID.glb?lod=1&animations=none"

Request (fetch)

// AVATAR_ID is the registered avatar ID.
const response = await fetch(`https://api.avatars.rooom.com/model/${AVATAR_ID}.glb?lod=1&animations=none`);
const modelBlob = await response.blob();

Replace AVATAR_ID with the registered avatar ID.

---

GET /preview/:id.

GET /preview/:id.{png,jpg,webp}

Downloads a preview image for a previously registered avatar. The .{png,jpg,webp} extension is required in the URL path.

Call this endpoint directly when your application needs a preview image for a registered avatar.

• Auth: not required
• Response: PNG image (Content-Type: image/png)

Query parameters:

Parameter	Value	Effect
size	integer, 32–512 (rounded to nearest power of 2)	Image size in pixels. Default: 512.
camera	full / portrait	Camera framing. Default: portrait.
background	R,G,B (e.g. 144,89,156)	Background color as comma-separated RGB values. If omitted, the background is transparent.

Download a portrait preview with cURL or JavaScript:

Request (cURL)

# AVATAR_ID is the registered avatar ID.
curl -o avatar-preview.png "https://api.avatars.rooom.com/preview/AVATAR_ID.png?size=512&camera=portrait"

Request (fetch)

// AVATAR_ID is the registered avatar ID.
const response = await fetch(`https://api.avatars.rooom.com/preview/${AVATAR_ID}.png?size=512&camera=portrait`);
const previewBlob = await response.blob();

Replace AVATAR_ID with the registered avatar ID.

Animations

GET /animations

GET /animations

Lists the built-in animations shipped with rooomAvatars, grouped by gender. Use this to discover which animation names are available for GET /animations/:gender/:name.glb.

• Auth: not required
• Response: JSON object grouped by gender

List available animations with cURL or JavaScript:

Request (cURL)

curl "https://api.avatars.rooom.com/animations"

Request (fetch)

const response = await fetch('https://api.avatars.rooom.com/animations');
const animations = await response.json();

The response is grouped by avatar gender:

{
  "status": "ok",
  "data": {
    "masculine": ["locomotion_idle", "locomotion_walk", "locomotion_run"],
    "feminine":  ["locomotion_idle", "locomotion_walk", "locomotion_run"]
  }
}

INFO

Animation names are identical across genders today, but each gender ships its own GLB file with a gender-specific skeleton and retargeted motion. Always download the animation matching your avatar's gender.

---

GET /animations/:gender/:name.glb

GET /animations/:gender/:name.glb

Downloads a single animation GLB file. The rig is Mixamo-compatible, so the clip can be applied to any rooomAvatars model of the same gender.

• Auth: not required
• Path parameters:
  • gender — one of masculine, feminine
  • name — one of the animation names returned by GET /animations (without the .glb suffix)
• Response: binary GLB file (Content-Type: model/gltf-binary)

Download a built-in animation with cURL or JavaScript:

Request (cURL)

curl -o idle.glb "https://api.avatars.rooom.com/animations/masculine/locomotion_idle.glb"

Request (fetch)

const response = await fetch('https://api.avatars.rooom.com/animations/masculine/locomotion_idle.glb');
const animationBlob = await response.blob();

Error responses:

Status	Reason
400	Unknown gender, or name is not in the built-in animation list.
404	Animation file is not available for the requested path.

TIP

For an end-to-end example that plays a built-in animation on an avatar in three.js or Babylon.js, see Playing Built-in Animations.

For user-supplied animations from Mixamo or other sources, see Using Mixamo Animations.