API Endpoints

rooomAvatars API endpoints for registering avatars and downloading models.

These endpoints are used by the configurator embedding flow.

POST /avatar

Note: This endpoint is primarily used by the avatar editor. If you are embedding the configurator iframe, you do not need to call this endpoint directly — the configurator handles avatar registration internally.

Registers an avatar configuration and returns an ID together with download URLs.

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

Example successful response showing the created avatar ID and download URLs:

{
  "status": "ok",
  "data": {
    "modelId": "...",
    "modelUrl": "https://HOST/model/ID.glb",
    "previewUrl": "https://HOST/preview/ID.png"
  }
}

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	Texture format for the model textures. Defaults to JPEG for solid meshes and PNG for meshes with transparency.
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).

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

GET /preview/:id.png

Downloads a preview image for a previously registered avatar. The .png extension is required in the URL path.

This endpoint is used internally by the editor. You can call it directly to fetch preview images, but it is not part of the primary integration flow.

• 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.

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

Example response:

{
  "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

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)

Example:

curl -o idle.glb "https://HOST/animations/masculine/locomotion_idle.glb"

Error responses:

Status	Reason
400	Unknown gender, or name is not in the built-in animation list.
404	Animation file is missing on the server (should not happen for valid names).

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.