Avatars

List and retrieve available avatar configurations.

List Avatars

GET /v1/avatars

Returns all available avatars. This endpoint is public and does not require authentication.

Example Request

curl https://api.avatarium.ai/v1/avatars

Example Response

{
  "data": [
    {
      "id": "aria-001",
      "name": "Aria",
      "description": "Friendly and professional assistant",
      "previewUrl": "https://cdn.avatarium.ai/previews/aria-001.webp",
      "modelUrl": "https://cdn.avatarium.ai/models/aria-001.glb",
      "defaultVoice": "en-US-Neural2-F",
      "tags": ["professional", "friendly", "female"]
    }
  ],
  "meta": {
    "requestId": "req_abc123"
  }
}

Get Avatar

GET /v1/avatars/:id

Retrieves detailed information about a specific avatar.

Path Parameters

Parameter	Type	Description
`id`	string	Avatar ID

Example Request

curl https://api.avatarium.ai/v1/avatars/aria-001

Example Response

{
  "data": {
    "id": "aria-001",
    "name": "Aria",
    "description": "Friendly and professional assistant",
    "previewUrl": "https://cdn.avatarium.ai/previews/aria-001.webp",
    "modelUrl": "https://cdn.avatarium.ai/models/aria-001.glb",
    "animations": {
      "idle": "idle_breathing",
      "talking": "talk_gesture",
      "thinking": "think_look"
    },
    "voice": {
      "default": "en-US-Neural2-F",
      "alternatives": ["en-GB-Neural2-A", "en-AU-Neural2-A"]
    },
    "tags": ["professional", "friendly", "female"]
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Get Avatar Model

GET /v1/avatars/:id/model?quality=medium

Returns the 3D model URL for a specific avatar with quality selection.

Query Parameters

Parameter	Type	Default	Description
`quality`	string	`medium`	`low`, `medium`, or `high`

Example Response

{
  "data": {
    "modelUrl": "https://cdn.avatarium.ai/models/aria-001-medium.glb",
    "quality": "medium"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Get Avatar Asset

GET /v1/avatars/:id/assets/:path

Retrieve avatar assets (textures, animations) from storage.

Messages Errors