> 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 %}

<table data-full-width="false"><thead><tr><th>Avatar variant</th><th align="center">Legacy supported</th><th align="center">Neo supported</th></tr></thead><tbody><tr><td><code>full_body</code></td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span></td></tr><tr><td><code>bubble</code></td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td><code>shoulder</code></td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr></tbody></table>

## 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."}}}}}}
```