> For the complete documentation index, see [llms.txt](https://docs.colossyan.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.colossyan.com/basics/openapi/list-avatars.md).
# List avatars
The endpoint will return the available avatars for your workspace.
The types of avatars the endpoint will return:
* **Studio**: Avatars provided by Colossyan.
* **Scenario**: Also provided by Colossyan, but shown with a specific scenario background.
* **Instant**: Custom-made avatars. To learn how to create one using the API, check out the following page ⇒[Create avatar](/avatar-creation/create-avatar.md)
* **ssa\_lite/ssa\_studio**: These are also custom-made avatars. To learn more, visit [this link](https://www.colossyan.com/custom-avatar).
{% hint style="warning" %}
**Important:** *Scenario* and *Instant* avatars are not included by default. To access them, please contact support.
{% endhint %}
#### Avatar inference model and variant support
There are three different inference models supported by the API (returned by the `supportedInferenceModels` parameter):
* `legacy`
* `neo`
* `neo2`
There are multiple different avatar variants supported by the API (returned by the `supportedActorTrackVariant` parameter):
* `full_body`
* `bubble`
* `shoulder`
* `fullscreen` *(deprecated)*
* `halfscreen` *(deprecated)*
{% hint style="warning" %}
**Important:** Not all inference models support all avatar variants.
{% endhint %}
| Avatar variant | Legacy supported | Neo supported |
|---|
full_body | ✅ | ❌ |
bubble | ✅ | ✅ |
shoulder | ✅ | ✅ |
## Retrieve a list of avatars
> Fetches a list of avatars that the user has access to.
```json
{"openapi":"3.0.3","info":{"title":"Avatar API","version":"1.0.0"},"servers":[{"url":"https://app.colossyan.com/api/v1","description":"V1 API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Avatar":{"type":"object","properties":{"id":{"type":"string","description":"Stable ID of the underlying avatar record"},"name":{"type":"string","description":"Key in the database"},"display_name":{"type":"string","description":"Display name of the avatar"},"preview_url":{"type":"string","description":"URL to the avatar's preview video"},"version":{"type":"string","enum":["v1","v2"]},"type":{"type":"string","enum":["Studio","Scenario","Instant","ssa_lite","ssa_studio"]},"gender":{"type":"string","enum":["Male","Female"]},"age":{"type":"integer","description":"Age of the avatar"},"ethnicity":{"$ref":"#/components/schemas/ActorEthnicity"},"clothing_style":{"$ref":"#/components/schemas/ActorClothingStyle"},"style":{"$ref":"#/components/schemas/ActorStyle"},"quality":{"$ref":"#/components/schemas/ActorTrackQuality"},"emotions":{"type":"array","description":"Deprecated field, will be removed in future versions.","items":{"type":"string"}},"default_voice":{"type":"string","description":"Default voice for the avatar"},"views":{"type":"array","description":"A list of views supported by the avatar","items":{"type":"object","properties":{"viewVariantType":{"$ref":"#/components/schemas/ActorView"},"aspectRatio":{"type":"object","properties":{"height":{"type":"number"},"width":{"type":"number"},"ratio":{"type":"number"}}},"supportedActorTrackVariants":{"$ref":"#/components/schemas/ActorTrackVariant"},"supportedInferenceModels":{"type":"array","description":"Public inference models supported by this view","items":{"type":"string","enum":["legacy","neo","neo2"]}},"inferenceModel":{"deprecated":true,"type":"string","description":"Deprecated. Use supportedInferenceModels instead.","enum":["legacy","neo","omnia"]},"pictarSourceUrl":{"type":"string"},"images":{"type":"object","properties":{"thumbnail":{"type":"string"},"editor":{"type":"string"},"editor-happy":{"type":"string"},"editor-sad":{"type":"string"},"shoulder":{"type":"string"}}},"videos":{"type":"object","properties":{"base":{"type":"string"},"baseTransparent":{"type":"string"},"dynamicPreviewUrl":{"type":"string"},"dynamicShoulderPreviewUrl":{"type":"string"}}},"emotions":{"deprecated":true,"type":"array","items":{"type":"string"}},"bubbleVariantDefaults":{"$ref":"#/components/schemas/VariantDefaults"},"shoulderVariantDefaults":{"$ref":"#/components/schemas/VariantDefaults"},"logoApply":{"type":"object","description":"Logo branding configuration for this view"},"livePreviewEnabled":{"type":"boolean"}}}},"features":{"type":"object","properties":{"side_view":{"type":"boolean"},"emotions":{"type":"boolean"},"sitting":{"type":"boolean"},"logo_addition":{"type":"boolean"}}}},"required":["id","name","display_name","preview_url","version","gender","views","features","default_voice"]},"ActorEthnicity":{"type":"string","enum":["Caucasian","Black / African American","East Asian","Hispanic / Latino","South Asian","Middle Eastern / North African"]},"ActorClothingStyle":{"type":"string","enum":["Casual","Formal","Sport","Doctor","Electrician","Uniform","Nurse","Support"]},"ActorStyle":{"type":"string","enum":["Realistic","Cartoon"]},"ActorTrackQuality":{"type":"string","enum":["lite","studio","pictar"]},"ActorView":{"type":"string","enum":["front","side-front","side-back","sitting","close-up","vertical","front 2","conversation"]},"ActorTrackVariant":{"type":"array","items":{"type":"string","enum":["full_body","bubble","shoulder","fullscreen","halfscreen"]}},"VariantDefaults":{"type":"object","properties":{"crop":{"type":"object","properties":{"left":{"description":"The percentage of the image to crop from the left (0-1)","type":"number"},"top":{"description":"The percentage of the image to crop from the top (0-1)","type":"number"},"right":{"description":"The percentage of the image to crop from the right (0-1)","type":"number"},"bottom":{"description":"The percentage of the image to crop from the bottom (0-1)","type":"number"}}}}}}},"paths":{"/assets/actors":{"get":{"summary":"Retrieve a list of avatars","description":"Fetches a list of avatars that the user has access to.","operationId":"getActors","responses":{"200":{"description":"A list of avatars","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Avatar"}}}}},"401":{"description":"Unauthorized. Authentication required."},"500":{"description":"Internal server error."}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.colossyan.com/basics/openapi/list-avatars.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.