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: https://animaze.tv/vmc |
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.
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 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 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
} |
Send to Animaze
{
"action": "LoadAvatar", // required
"id": <id> // optional (string)
"name": "Avatar03" // Avatar name (required by action)
} |
Receive from Animaze
same command
{
"action": "LoadScene", // required
"id": <id> // optional (string)
"name": "customization01_scene" // Scene name (required by action)
} |
Receive from Animaze
same command
Get the list of ready to use avatars (.avatar files are already on disk).
Send to Animaze
{
"action": "GetAvatars", // required (string)
"id": <id> // optional (string)
} |
Receive from Animaze
{
"action": "GetAvatars", // string
"id": <id>, // string
"avatars": ["avatar03", "AvatarBomb"] // All available avatars (array)
} |
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
{
"action": "GetCurrentAvatarInfo", // required (string)
"id": "MyDevName" // optional (string)
} |
Receive from Animaze
{
"action": "GetCurrentAvatarInfo",
"avatars": [{
"animStandard": "AnimazeStandard_1_0",
"description": "A spiffy and adorable red panda.",
"friendlyName": "Fluffo",
"isCustomized": true,
"itemName": "avatar01_BS_Full",
"itemType": "Avatar3D",
"numProps": 3,
"props": ["crown_king", "greenGlasses", "headphones"]
}],
"id": "MyDevName",
"numAvatars": 1
} |
Get the list of ready-to-use scenes (.avatar files are already on disk).
Send to Animaze
{
"action": "GetScenes", // required (string)
"id": <id> // optional (string)
} |
Receive from Animaze
{
"action": "GetScenes", // string
"id": <id>, // string
"scenes": ["Spaceship", "Stream"] // All available scenes (array)
} |
Get advanced info on the currently loaded scene.
Send to Animaze
{
"action": "GetCurrentSceneInfo", // required (string)
"id": "MyDevName" // optional (string)
} |
Receive from Animaze
{
"action": "GetCurrentSceneInfo",
"description": "A gamer's room.",
"friendlyName": "The RGB Room",
"id": "MyDevName",
"itemName": "RGBRoom"
} |
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
{
"action": "GetItemIcon", // required (string)
"id": <id> // optional (string)
"name": "customization01_scene" // Works for all animaze items that are present
// in a gallery: avatars, scenes, props,
// voice effects, etc (required by action)
} |
Receive from Animaze
{
"action": "GetItemIcon", // string
"id": <id>, // string
"image": "iVBORw0KGgoAAAANSUhE..." // base64 encoded image file (string)
} |
Get the list of ready to use emotes (.avatar files are already on disk).
Send to Animaze
{
"action": "GetEmotes" // required (string)
} |
Receive from Animaze
{
"action": "GetEmotes", // string
"emotes":[{"friendlyName":"Alarm","itemName":"Emote_Alarm"},{"friendlyName":"Angry","itemName":"Emote_Angry"}..] //all available Emotes
} |
Triggers an emote
Send to Animaze
{
"action": "TriggerEmote", // required (string)
"itemName": "Emote_Alarm" // required (string)
} |
Receive from Animaze
same command
Get the special actions list of the current avatar
Send to Animaze
{
"action": "GetSpecialActions" // required (string)
} |
Receive from Animaze
{
"action": "GetSpecialActions", // string
{"action":"GetSpecialActions","specialActions":[{"animName":"Come here","index":0},{"animName":"Hello","index":1},..] //list of all special actions for the current avatar
} |
Start a special action on the current avatar
Send to Animaze
{
"action": "TriggerSpecialAction", // required (string)
"index": <int> // required (int)
} |
Receive from Animaze
same command
Get the special poses list of the current avatar
Send to Animaze
{
"action": "GetPoses" // required (string)
} |
Receive from Animaze
{
"action": "GetPoses", // string
{"action":"GetPoses","poseList":[{"animName":"Puff Cheeks","index":0},{"animName":"Tongue Out","index":1}]} //list of all special poses for the current avatar
} |
Set the pose for the current avatar
Send to Animaze
{
"action": "TriggerPose", // required (string)
"index" : <int> // required (int)
} |
Receive from Animaze
same command
Get the idle animations list of the current avatar
Send to Animaze
{
"action": "GetIdleAnims" // required (string)
} |
Receive from Animaze
{
"action": "GetIdleAnims", // string
{"action":"GetIdleAnims","idleList":[{"animName":"Default Idle","index":0},{"animName":"Bored","index":2},{"animName":"Fight","index":3}]} //list of all idle animations for the current avatar
} |
Set the idle animations for the current avatar
Send to Animaze
{
"action": "TriggerIdle", // required (string)
"index" : <int> // required (int)
} |
Receive from Animaze
same command
Get the ready-to-use Quickscenes list
Send to Animaze
{
"action": "GetQuickscenes" // required (string)
} |
Receive from Animaze
{
"action": "GetQuickscenes", // required (string)
"quickslots":[{"index":0,"image":"iVBORw0KGgoAAAANSUhE..."}..] // list of indices and base64 encoded image file (string)
} |
Loads the Quickscene
Send to Animaze
{
"action": "LoadQuickscene", // required (string)
"index" : <int> // required (int)
} |
Receive from Animaze
same command
Triggers saving current setup (avatar, scene, camera placement, voice effects, etc.) to be saved as a Quickscene.
Send to Animaze
{
"action": "SaveQuickscene", // required (string)
"index" : <int> // required (int)
} |
Receive from Animaze
same command
Trigger Animaze’s tracker calibration function
Send to Animaze
{
"action": "CalibrateTracker" // required (string)
} |
Receive from Animaze
same command
Enables virtual camera broadcast.
Send to Animaze
{
"action": "Broadcast", // required (string)
"toggle": <bool> // required (bool)
} |
Receive from Animaze
same command
Sets a custom World Space transformation to the render camera. Camera transformation is right-handed (OpenGL).
Send to Animaze
{
"action": "SetCameraTransform", // required (string)
"position" : [<float>, <float>, <float>], // required ([float, float, float])
"rotation" : [<float>, <float>, <float>, <float>] // required ([float, float, float, float]) quaternion
}
|
Receive from Animaze
same command
Gets render camera’s World Space Transformation. Camera transformation is right-handed (OpenGL).
Send to Animaze
{
"action": "GetCameraTransform" // required (string)
}
|
Receive from Animaze
{
"action": "GetCameraTransform", // (string)
"position":[0.0,1.7000000476837158,1.0], // (float, float, float)
"rotation":[0.0,0.0,0.0,1.0] // (float, float, float, float) quaternion
} |
Sets a a new Fov to the render camera. Fov must be given in degrees.
Send to Animaze
{
"action": "SetCameraFov", // required (string)
"fov" : float // required (float) in degrees
}
|
Receive from Animaze
same command
Gets render camera’s Fov
Send to Animaze
{
"action": "GetCameraFov" // required (string)
}
|
Receive from Animaze
{
"action": "GetCameraFov", // (string)
"fov":60.000003814697266 // (float)
} |
Sets a custom Word Space transformation to the render camera. Camera transformation is right-handed (OpenGL).
Send to Animaze
{
"action": "SetAvatarTransform", // required (string)
"position" : [<float>, <float>, <float>], // required ([float, float, float])
"rotation" : [<float>, <float>, <float>, <float>], // required ([float, float, float, float]) quaternion
"scale": <float> // required (float)
} |
Receive from Animaze
same command
Gets render camera’s World Space Transformation. Camera transformation is right-handed (OpenGL).
Send to Animaze
{
"action": "GetAvatarTransform" // required (string)
} |
Receive from Animaze
{
"action": "GetAvatarTransform", // (string)
"position":[0.0,1.7000000476837158,1.0], // (float, float, float)
"rotation":[0.0,0.0,0.0,1.0], // (float, float, float, float) quaternion
"scale": 1.0 // (float)
} |
Activates/deactivates one of the following override behaviors on the current avatar. Parameters are optional:
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Follow Mouse Cursor", // required (string)
"value": <bool> // required (bool)
} |
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Mouse Keyboard Behavior", // required (string)
"value": <bool>, // required (bool)
"keyboardScale": <float>, // optional (float)
"handToKeyboardDist": <float>, // optional (float)
"xAxisOffset": <float>, // optional (float)
"yAxisOffset": <float>, // optional (float)
"zAxisOffset ": <float> // optional (float)
} |
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Tracked Blinking", // required (string)
"value": <bool> // required (bool)
} |
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Auto Blink", // required (string)
"value": <bool>, // required (bool)
"frequency": <float> // optional (float)
} |
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Look At Camera", // required (string)
"value": <bool>, // required (bool)
"range": <float> // optional (float)
} |
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Look At Camera Head", // required (string)
"value": <bool> // required (bool)
} |
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Cross Eyes", // required (string)
"value": <bool> // required (bool)
} |
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Pupil Behavior", // required (string)
"value": <bool>, // required (bool)
"frequency": <float> // optional (float)
} |
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Forced Symmetry Eyebrows", // required (string)
"value": <bool>, // required (bool)
"range": <float> // optional (float)
} |
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Forced Symmetry Eyelids", // required (string)
"value": <bool>, // required (bool)
"range": <float> // optional (float)
} |
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Forced Symmetry Mouth", // required (string)
"value": <bool>, // required (bool)
"range": <float> // optional (float)
} |
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Enhanced Body Movement 2D", // required (string)
"value": <bool> // required (bool)
} |
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Enhanced Body Movement 3D", // required (string)
"value": <bool> // required (bool)
} |
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Extreme Head Angles Attenuation", // required (string)
"value": <bool>, // required (bool)
"range": <float>, // optional (float)
"maxSmoothingValue" : <float> // optional (float)
} |
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Sound to Mouth Open", // required (string)
"value": <bool>, // required (bool)
"mouthSmoothTme": <float>, // optional (float)
"soundSensitivity": <float> // optional (float)
} |
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Alternate lipsync Retargeting", // required (string)
"value": <bool> // required (bool)
} |
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Idle Intensity", // required (string)
"value": <bool>, // required (bool)
"intensity": <float> // optional (float)
} |
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Inferred Body Yaw Movement", // required (string)
"value": <bool>, // required (bool)
"neutralZoneSize": <float>, // optional (float)
"movementSmoothing": <float>, // optional (float)
"headYawWeight": <float> // optional (float)
} |
Send to Animaze
{
"action": "SetOverride", // required (string)
"behavior": "Breathing Behavior", // required (string)
"value": <bool>, // required (bool)
"amplitude": <float>, // optional (float)
"frequency": <float> // optional (float)
} |
Receive from Animaze
same command
Returns the status of an override behavior (activated/deactivated) and its current parameters, applied on the current avatar.
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": "Follow Mouse Cursor" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Follow Mouse Cursor", // string
"value": true/false // bool
}
|
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": "Mouse Keyboard Behavior" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Mouse Keyboard Behavior", // string
"value": true/false, // bool
"keyboardScale": <float>, // float
"handToKeyboardDist": <float>, // float
"xAxisOffset": <float>, // float
"yAxisOffset": <float>, // float
"zAxisOffset ": <float> // float
}
|
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": "Tracked Blinking" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Tracked Blinking", // string
"value": true/false // bool
}
|
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": "Auto Blink" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Auto Blink", // string
"value": true/false, // bool
"frequency": <float> // float
}
|
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": "Look At Camera" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Look At Camera", // string
"value": true/false, // bool
"range": <float> // float
}
|
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": "Look At Camera Head" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Look At Camera Head", // string
"value": true/false // bool
}
|
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": "Cross Eyes" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Cross Eyes", // string
"value": true/false // bool
}
|
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": "Pupil Behavior" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Pupil Behavior", // string
"value": true/false, // bool
"frequency": <float> // float
}
|
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": "Forced Symmetry Eyebrows" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Forced Symmetry Eyebrows", // string
"value": true/false, // bool
"range": <float> // float
}
|
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": "Forced Symmetry Eyelids" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Forced Symmetry Eyelids", // string
"value": true/false, // bool
"range": <float> // float
}
|
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": "Forced Symmetry Mouth" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Forced Symmetry Mouth", // string
"value": true/false, // bool
"range": <float> // float
}
|
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": "Enhanced Body Movement 2D" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Enhanced Body Movement 2D", // string
"value": true/false // bool
}
|
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": "Enhanced Body Movement 3D" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Enhanced Body Movement 3D", // string
"value": true/false // bool
}
|
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": "Extreme Head Angles Attenuation" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Extreme Head Angles Attenuation", // string
"value": true/false, // bool
"range": <float>, // float
"maxSmoothingValue" : <float> // float
}
|
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": "Sound to Mouth Open" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Sound to Mouth Open", // string
"value": true/false, // bool
"mouthSmoothTme": <float>, // float
"soundSensitivity": <float> // float
}
|
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": ""Alternate lipsync Retargeting" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Alternate lipsync Retargeting", // string
"value": true/false // bool
}
|
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": "Idle Intensity" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Idle Intensity", // string
"value": true/false, // bool
"intensity": <float> // float
}
|
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": "Inferred Body Yaw Movement" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Inferred Body Yaw Movement", // string
"value": true/false, // bool
"neutralZoneSize": <float>, // float
"movementSmoothing": <float>, // float
"headYawWeight": <float> // float
}
|
Send to Animaze
{
"action": "GetOverride", // required (string)
"behavior": "Breathing Behavior" // required (string)
} |
Receive from Animaze
{
"action": "GetOverride", // string
"behavior": "Breathing Behavior", // string
"value": true/false, // bool
"amplitude": <float>, // float
"frequency": <float> // float
}
|
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
{
"action": "ChatbotSendMessage", // required (string)
"id": <id>, // optional (string)
"message": "prompt to Animaze Chatpal" // required (string)
} |
Receive from Animaze
{
"action": "ChatbotSendMessage", // string
"response": "response from Animaze ChatPal" // string
} |
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.
{
"event": "ChatbotSpeechStarted"
} |
{
"event": "ChatbotSpeechEnded"
} |
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