---
agentTools:
  projectIndex: https://elai.readme.io/llms.txt
---

# Avatars list

Get all available avatars

> 📘 How to add avatar to your video
>
> Please check [slide structure](https://elai.readme.io/reference/slide-structure) page on how to add avatar to videos

# OpenAPI definition

````json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Elai Public API",
    "version": "1.0",
    "description": "Every endpoint below is served under `https://apis.elai.io/api/v1`.\n\n## Authentication\n\nSend your workspace API token as a bearer token on every request:\n\n```\nAuthorization: Bearer <your-api-token>\n```\n\nGenerate and rotate the token in the Elai web app under **Settings → API**, or through\n`POST /generateToken`. The token is scoped to one **workspace** and authenticates as that\nworkspace's admin user — it is not tied to an individual person, and it carries admin rights\ninside that workspace.\n\nA request with a missing, unknown or revoked token gets a bare `401` with no response body.\n\n> **Organizations on the Unlimited plan cannot use the API.** Their requests are rejected with the\n> same bare `401` as an invalid token, with nothing to distinguish the two. If a valid, freshly\n> generated token returns `401` on every endpoint, check the plan first.\n\n## Errors\n\nFailures carry a JSON body of the shape `{ \"message\": \"...\" }`. Validation failures on the newer\nendpoints may add an `errors` array naming the offending fields. `401` is the exception: it has no\nbody at all.\n\nBoth render endpoints are **fire-and-forget** — they queue work and return immediately, so a\n`200` means \"accepted\", not \"rendered\". Render failures surface only through the `video_error`\nwebhook, never as an HTTP error on the call that started the render.\n\n## Scope\n\nThis reference is generated from the running code rather than maintained by hand, so it cannot\nquietly fall behind the API it describes. It documents 96 operations across the\n`/api/v1` surface.\n\nEndpoints are grouped by subject in the sidebar. If something you need is missing, or an endpoint\ndoes not behave as described here, tell us.\n\n---\n\n_Generated from `chore/web-4760/api-v1-reference-build` at `5289745d` on 2026-09-04._"
  },
  "servers": [
    {
      "url": "https://apis.elai.io/api/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "x-bearer-format": "bearer",
        "x-default": "SECRET_KEY"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/avatars": {
      "get": {
        "summary": "Avatars list",
        "description": "Get all available avatars",
        "operationId": "avatars-list",
        "parameters": [
          {
            "name": "realtime",
            "in": "query",
            "description": "If this is true or 1 only avatars that supports realtime will be returned",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": [
                      {
                        "_id": "62ea3143b3c0dc1e3ae25e4f",
                        "id": "custom",
                        "name": "Alex (Personal)",
                        "type": "selfie",
                        "version": 1,
                        "status": 4,
                        "gender": "male",
                        "thumbnail": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/custom/custom_roger.jpg",
                        "canvas": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/custom/custom_roger.png",
                        "tilt": {
                          "top": 0.1,
                          "left": -0.05
                        }
                      },
                      {
                        "_id": "6374ca89dc87c5c48f5a8499",
                        "id": "dairon",
                        "name": "Dairon",
                        "version": 1,
                        "status": 2,
                        "gender": "male",
                        "intro": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/dairon.mp4",
                        "tilt": {},
                        "variants": [
                          {
                            "id": "business",
                            "name": "Business",
                            "canvas": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/dairon_business.png",
                            "thumbnail": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/dairon_business.jpg",
                            "gif": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/dairon_business.gif"
                          },
                          {
                            "id": "regular",
                            "name": "Casual",
                            "tilt": {
                              "top": -0.05
                            },
                            "canvas": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/dairon.png",
                            "thumbnail": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/dairon.jpg",
                            "gif": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/dairon.gif"
                          },
                          {
                            "id": "builder",
                            "name": "Constructor",
                            "canvas": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/dairon_builder.png",
                            "thumbnail": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/dairon_builder.jpg",
                            "gif": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/dairon_builder.gif"
                          }
                        ]
                      },
                      {
                        "_id": "6374ca89dc87c5c48f5a849d",
                        "id": "anna",
                        "name": "Anna",
                        "version": 1,
                        "status": 2,
                        "gender": "female",
                        "intro": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/anna.mp4",
                        "tilt": {},
                        "variants": [
                          {
                            "id": "business",
                            "name": "Business",
                            "tilt": {
                              "left": -0.01
                            },
                            "canvas": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/anna_business.png",
                            "thumbnail": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/anna_business.jpg",
                            "gif": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/anna_business.gif"
                          },
                          {
                            "id": "regular",
                            "name": "Casual",
                            "tilt": {
                              "left": -0.03
                            },
                            "canvas": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/anna.png",
                            "thumbnail": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/anna.jpg",
                            "gif": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/anna.gif"
                          }
                        ]
                      }
                    ]
                  }
                },
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "_id": {
                        "type": "string",
                        "example": "62ea3143b3c0dc1e3ae25e4f",
                        "description": "Same value as `id`, for older clients."
                      },
                      "id": {
                        "type": "string",
                        "example": "custom",
                        "description": "The avatar's document id."
                      },
                      "name": {
                        "type": "string",
                        "example": "Alex (Personal)"
                      },
                      "type": {
                        "type": "string",
                        "example": "selfie"
                      },
                      "version": {
                        "type": "integer",
                        "example": 1,
                        "default": 0
                      },
                      "status": {
                        "type": "integer",
                        "example": 4,
                        "default": 0
                      },
                      "gender": {
                        "type": "string",
                        "example": "male"
                      },
                      "thumbnail": {
                        "type": "string",
                        "example": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/custom/custom_roger.jpg"
                      },
                      "canvas": {
                        "type": "string",
                        "example": "https://elai-media.s3.eu-west-2.amazonaws.com/avatars/custom/custom_roger.png"
                      },
                      "tilt": {
                        "type": "object",
                        "properties": {
                          "top": {
                            "type": "number",
                            "example": 0.1,
                            "default": 0
                          },
                          "left": {
                            "type": "number",
                            "example": -0.05,
                            "default": 0
                          }
                        }
                      },
                      "code": {
                        "type": "string",
                        "description": "Stable avatar code."
                      },
                      "premium": {
                        "type": "boolean",
                        "description": "True for premium avatars, which require a plan that allows them."
                      },
                      "organizationId": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "Null for avatars from the shared public catalog."
                      },
                      "intro": {
                        "type": "string",
                        "description": "Preview video URL."
                      },
                      "introPoster": {
                        "type": "string",
                        "description": "Poster image for the preview video."
                      },
                      "defaultVoice": {
                        "type": "string",
                        "description": "Voice suggested for this avatar."
                      },
                      "limit": {
                        "type": "number",
                        "description": "Maximum slide length this avatar supports, in seconds."
                      },
                      "age": {
                        "type": "number"
                      },
                      "ethnicity": {
                        "type": "string"
                      },
                      "faceBbox": {
                        "type": "object",
                        "additionalProperties": true,
                        "description": "Face bounding box used for framing."
                      },
                      "listeningAvatar": {
                        "type": "object",
                        "additionalProperties": true,
                        "description": "Listening-state variant, for interactive use."
                      },
                      "variants": {
                        "type": "array",
                        "description": "Selectable looks for this avatar. Render with a variant `code` — or with the code of one of its nested poses, side views or scenarios.",
                        "items": {
                          "type": "object",
                          "additionalProperties": true,
                          "properties": {
                            "id": {
                              "type": "string",
                              "description": "Legacy alias of `code`."
                            },
                            "code": {
                              "type": "string",
                              "description": "Pass this as the avatar code when rendering."
                            },
                            "name": {
                              "type": "string"
                            },
                            "isScenario": {
                              "type": "boolean"
                            },
                            "poses": {
                              "type": "array",
                              "description": "Alternative body poses.",
                              "items": {
                                "type": "object",
                                "description": "Spreads its own `frontendConfig`, so extra presentation fields may appear.",
                                "additionalProperties": true,
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "description": "Pass this as the avatar code when rendering."
                                  },
                                  "name": {
                                    "type": "string"
                                  },
                                  "thumbnail": {
                                    "type": "string"
                                  },
                                  "canvas": {
                                    "type": "string"
                                  },
                                  "tags": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    }
                                  },
                                  "isFrontView": {
                                    "type": "boolean"
                                  }
                                }
                              }
                            },
                            "sideViews": {
                              "type": "array",
                              "description": "Side-facing views.",
                              "items": {
                                "type": "object",
                                "description": "Spreads its own `frontendConfig`, so extra presentation fields may appear.",
                                "additionalProperties": true,
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "description": "Pass this as the avatar code when rendering."
                                  },
                                  "name": {
                                    "type": "string"
                                  },
                                  "thumbnail": {
                                    "type": "string"
                                  },
                                  "canvas": {
                                    "type": "string"
                                  },
                                  "tags": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    }
                                  }
                                }
                              }
                            },
                            "scenarios": {
                              "type": "array",
                              "description": "Scene/background variations.",
                              "items": {
                                "type": "object",
                                "description": "Spreads its own `frontendConfig`, so extra presentation fields may appear.",
                                "additionalProperties": true,
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "description": "Pass this as the avatar code when rendering."
                                  },
                                  "name": {
                                    "type": "string"
                                  },
                                  "thumbnail": {
                                    "type": "string"
                                  },
                                  "canvas": {
                                    "type": "string"
                                  },
                                  "tags": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    }
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "additionalProperties": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": {}
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          }
        },
        "deprecated": false,
        "tags": [
          "Avatars"
        ]
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "tags": [
    {
      "name": "Avatars",
      "description": "The avatar catalog, and submitting footage for a custom avatar."
    }
  ],
  "_id": {
    "buffer": {
      "0": 106,
      "1": 154,
      "2": 229,
      "3": 101,
      "4": 201,
      "5": 178,
      "6": 243,
      "7": 252,
      "8": 223,
      "9": 58,
      "10": 69,
      "11": 151
    }
  }
}
````