1 Intro
2 Setup
3 Overview
- 3.1 Actions
- 3.2 Triggers
4 API Reference (Actions)
- 4.1 Load Avatar
- 4.2 Load Scene
- 4.3 Get Avatars
- 4.4 Get Current Avatar Info (available only on next-version branch of Animaze App)
- 4.5 Get Scenes
- 4.6 Get Current Scene Info (available only on next-version branch of Animaze App)
- 4.7 Get Item Icon
- 4.8 Get Emotes
- 4.9 Trigger Emote
- 4.10 Get Special Actions
- 4.11 Trigger Special Action
- 4.12 Get Poses
- 4.13 Trigger Pose
- 4.14 Get Idle Anims
- 4.15 Trigger Idle
- 4.16 Get Quickscenes
- 4.17 Load Quickscene
- 4.18 Save Quickscene
- 4.19 Calibrate Tracker
- 4.20 Broadcast
- 4.21 Set Camera Transform
- 4.22 Get Camera Transform
- 4.23 Set Camera Fov
- 4.24 Get Camera Fov
- 4.25 Set Avatar Transform
- 4.26 Get Avatar Transform
- 4.27 Set Override
  - 4.27.1 Follow Mouse Cursor
  - 4.27.2 Mouse Keyboard Behavior
  - 4.27.3 Tracked Blinking
  - 4.27.4 Auto Blink
  - 4.27.5 Look At Camera
  - 4.27.6 Look At Camera Head
  - 4.27.7 Cross Eyes
  - 4.27.8 Pupil Behavior
  - 4.27.9 Forced Symmetry Eyebrows
  - 4.27.10 Forced Symmetry Eyelids
  - 4.27.11 Forced Symmetry Mouth
  - 4.27.12 Enhanced Body Movement 2D
  - 4.27.13 Enhanced Body Movement 3D
  - 4.27.14 Extreme Head Angles Attenuation
  - 4.27.15 Sound to Mouth Open
  - 4.27.16 Alternate lipsync Retargeting
  - 4.27.17 Idle Intensity
  - 4.27.18 Inferred Body Yaw Movement
  - 4.27.19 Breathing Behavior
- 4.28 Get Override
  - 4.28.1 Follow Mouse Cursor
  - 4.28.2 Mouse Keyboard Behavior
  - 4.28.3 Tracked Blinking
  - 4.28.4 Auto Blink
  - 4.28.5 Look At Camera
  - 4.28.6 Look At Camera Head
  - 4.28.7 Cross Eyes
  - 4.28.8 Pupil Behavior
  - 4.28.9 Forced Symmetry Eyebrows
  - 4.28.10 Forced Symmetry Eyelids
  - 4.28.11 Forced Symmetry Mouth
  - 4.28.12 Enhanced Body Movement 2D
  - 4.28.13 Enhanced Body Movement 3D
  - 4.28.14 Extreme Head Angles Attenuation
  - 4.28.15 Sound to Mouth Open
  - 4.28.16 Alternate lipsync Retargeting
  - 4.28.17 Idle Intensity
  - 4.28.18 Inferred Body Yaw Movement
  - 4.28.19 Breathing Behavior
- 4.29 Send Message to Animaze ChatPal
5 API Reference (Triggers)
- 5.1 Animaze ChatPal Speech Start/End Events (available only on next-version branch of Animaze App)
6 Sample

Intro

The Animaze API enables 3rd party apps to control certain functions (e.g. load avatar) or get certain info (e.g. list of ready to use avatars) of/from the Animaze Desktop application. The API is implemented using a websocket that exchanges JSON messages between the Animaze app and 3rd party clients.

If you are looking into making your app control the avatar’s expressions and body motions, best to look into our Programmable Tracker, which allows for you to directly retarget your tracking data to the avatar. Read more here.

If you are looking into making your app control the avatar’s body (full body tracking or hands tracking), best to look into using the VMC protocol, as Animaze supports it. Here is a user-facing guide: Animaze VMC protocol Body Tracker Usage Guide

Setup

The Animaze API websocket uses by default ws://localhost:9000 address.

Animaze is not accepting commands by default, so you need to activate the API from Settings > Animaze API > Enabled. The Port number can also be changed from Settings > Animaze API in the Animaze Desktop app.

Present and future API settings will reside in Settings > Animaze API, so be sure to check them from time to time.

Overview

The Animaze API supports commands or actions (send a command, receive a response) and in the future will also support triggers, Animaze state changes broadcasted to all clients (e.g. the avatar changed)

Actions

Actions are messages sent to Animaze that describe a specific command that needs to be executed and provide a response.

Action request example

{
  "action": "LoadAvatar",                         // required by all action messages
  "id": "0E9AA4AE-8C70-4999-BFAE-4D639A3F73E2",   // optional
  "name": "Avatar03"                              // required by the "LoadAvatar" action
}

An action response will echo the “action” field and “id“ field if present (use this to link your original request with it’s response for a better management) and an optional “error“ message in case the command failed.

Action response example

{
  "action": "LoadAvatar",
  "id": "0E9AA4AE-8C70-4999-BFAE-4D639A3F73E2",
  "error": "Avatar not found"
}

Triggers

Triggers are messages sent by Animaze to all connected clients with information about state changes initiated by the app.

Trigger example

{
  "event": "AvatarChanged",             // changed state
  "new_avatar": "AvatarBomb"            // state value
}

API Reference (Actions)

Load Avatar

Send to Animaze

Receive from Animaze

same command

Load Scene

Receive from Animaze

same command

Get Avatars

Get the list of ready to use avatars (.avatar files are already on disk).

Send to Animaze

Receive from Animaze

Get Current Avatar Info (available only on next-version branch of Animaze App)

Get advanced info on a list of currently loaded avatars. The command returns a list so that it covers the Animaze Rooms scenario where there are multiple avatars spawned.

Send to Animaze

Receive from Animaze

Get Scenes

Get the list of ready-to-use scenes (.avatar files are already on disk).

Send to Animaze

Receive from Animaze

Get Current Scene Info (available only on next-version branch of Animaze App)

Get advanced info on the currently loaded scene.

Send to Animaze

Receive from Animaze

Get Item Icon

Get the item’s icon as base64 encoded image. This function works for all Animaze items, such as: avatars, scenes, props, emotes, voice effects, etc.

Send to Animaze

Receive from Animaze

Get Emotes

Get the list of ready to use emotes (.avatar files are already on disk).

Send to Animaze

Receive from Animaze

Trigger Emote

Triggers an emote

Send to Animaze

Receive from Animaze

same command

Get Special Actions

Get the special actions list of the current avatar

Send to Animaze

Receive from Animaze

Trigger Special Action

Start a special action on the current avatar

Send to Animaze

Receive from Animaze

same command

Get Poses

Get the special poses list of the current avatar

Send to Animaze

Receive from Animaze

Trigger Pose

Set the pose for the current avatar

Send to Animaze

Receive from Animaze

same command

Get Idle Anims

Get the idle animations list of the current avatar

Send to Animaze

Receive from Animaze

Trigger Idle

Set the idle animations for the current avatar

Send to Animaze

Receive from Animaze

same command

Get Quickscenes

Get the ready-to-use Quickscenes list

Send to Animaze

Receive from Animaze

Load Quickscene

Loads the Quickscene

Send to Animaze

Receive from Animaze

same command

Save Quickscene

Triggers saving current setup (avatar, scene, camera placement, voice effects, etc.) to be saved as a Quickscene.

Send to Animaze

Receive from Animaze

same command

Calibrate Tracker

Trigger Animaze’s tracker calibration function

Send to Animaze

Receive from Animaze

same command

Broadcast

Enables virtual camera broadcast.

Send to Animaze

Receive from Animaze

same command

Set Camera Transform

Sets a custom World Space transformation to the render camera. Camera transformation is right-handed (OpenGL).

Send to Animaze

Receive from Animaze

same command

Get Camera Transform

Gets render camera’s World Space Transformation. Camera transformation is right-handed (OpenGL).

Send to Animaze

Receive from Animaze

Set Camera Fov

Sets a a new Fov to the render camera. Fov must be given in degrees.

Send to Animaze

Receive from Animaze

same command

Get Camera Fov

Gets render camera’s Fov

Send to Animaze

Receive from Animaze

Set Avatar Transform

Sets a custom Word Space transformation to the render camera. Camera transformation is right-handed (OpenGL).

Send to Animaze

Receive from Animaze

same command

Get Avatar Transform

Gets render camera’s World Space Transformation. Camera transformation is right-handed (OpenGL).

Send to Animaze

Receive from Animaze

Set Override

Activates/deactivates one of the following override behaviors on the current avatar. Parameters are optional:

Follow Mouse Cursor

Send to Animaze

Mouse Keyboard Behavior

Send to Animaze

Tracked Blinking

Send to Animaze

Auto Blink

Send to Animaze

Look At Camera

Send to Animaze

Look At Camera Head

Send to Animaze

Cross Eyes

Send to Animaze

Pupil Behavior

Send to Animaze

Forced Symmetry Eyebrows

Send to Animaze

Forced Symmetry Eyelids

Send to Animaze

Forced Symmetry Mouth

Send to Animaze

Enhanced Body Movement 2D

Send to Animaze

Enhanced Body Movement 3D

Send to Animaze

Extreme Head Angles Attenuation

Send to Animaze

Sound to Mouth Open

Send to Animaze

Alternate lipsync Retargeting

Send to Animaze

Idle Intensity

Send to Animaze

Inferred Body Yaw Movement

Send to Animaze

Breathing Behavior

Send to Animaze

Receive from Animaze

same command

Get Override

Returns the status of an override behavior (activated/deactivated) and its current parameters, applied on the current avatar.

Follow Mouse Cursor

Send to Animaze

Receive from Animaze

Mouse Keyboard Behavior

Send to Animaze

Receive from Animaze

Tracked Blinking

Send to Animaze

Receive from Animaze

Auto Blink

Send to Animaze

Receive from Animaze

Look At Camera

Send to Animaze

Receive from Animaze

Look At Camera Head

Send to Animaze

Receive from Animaze

Cross Eyes

Send to Animaze

Receive from Animaze

Pupil Behavior

Send to Animaze

Receive from Animaze

Forced Symmetry Eyebrows

Send to Animaze

Receive from Animaze

Forced Symmetry Eyelids

Send to Animaze

Receive from Animaze

Forced Symmetry Mouth

Send to Animaze

Receive from Animaze

Enhanced Body Movement 2D

Send to Animaze

Receive from Animaze

Enhanced Body Movement 3D

Send to Animaze

Receive from Animaze

Extreme Head Angles Attenuation

Send to Animaze

Receive from Animaze

Sound to Mouth Open

Send to Animaze

Receive from Animaze

Alternate lipsync Retargeting

Send to Animaze

Receive from Animaze

Idle Intensity

Send to Animaze

Receive from Animaze

Inferred Body Yaw Movement

Send to Animaze

Receive from Animaze

Breathing Behavior

Send to Animaze

Receive from Animaze

Send Message to Animaze ChatPal

Send a prompt to Animaze ChatPal, and receive the conversational AI response, while the avatar starts speaking. You can use this command as echo (for the text-to-speech functionality) as well by adding -echo at the start of the “message“ string.

Send to Animaze

Receive from Animaze

API Reference (Triggers)

Animaze ChatPal Speech Start/End Events (available only on next-version branch of Animaze App)

ChatbotSpeechStarted and ChatbotSpeechEnded events are sent by Animaze when ChatPal agent starts and stops speaking (start and end of audio). These events aren’t extremely accurate and depend on the voice engine, but the error could be that the ChatbotSpeechStarted is sent slightly earlier and ChatbotSpeechEnded is sent slightly later. Error is empirically determined up to 1 second.

Sample

You can check out a sample Python script that uses all the available actions at this time. Here’s the archive:

The “AnimazeAPITest.py“ script iterates through all commands in the “commands.json” file and sends them through the websocket.

Requirements:

Python 3.11+
Python modules: websockets