# 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](https://docs.colossyan.com/avatar-creation/create-avatar "mention")
* **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 two different inference models supported by the API (returned by the  `supportedInferenceModel` parameter):

* `legacy`
* `neo`

There are three different avatar variants supported by the API (returned by the `supportedActorTrackVariant` parameter):

* `full_body`
* `bubble`
* `shoulder`

{% 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":{"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"},"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","items":{"type":"string","enum":["legacy","neo"]}},"pictarSourceUrl":{"type":"string"},"images":{"type":"object","properties":{"thumbnail":{"type":"string"},"editor":{"type":"string"},"editor-happy":{"type":"string"},"editor-sad":{"type":"string"}}},"videos":{"type":"object","properties":{"base":{"type":"string"},"baseTransparent":{"type":"string"},"dynamicPreviewUrl":{"type":"string"}}},"emotions":{"deprecated":true,"type":"array","items":{"type":"string"}},"bubbleVariantDefaults":{"$ref":"#/components/schemas/VariantDefaults"},"shoulderVariantDefaults":{"$ref":"#/components/schemas/VariantDefaults"}}}},"features":{"type":"object","properties":{"side_view":{"type":"boolean"},"emotions":{"type":"boolean"},"hand_gesture":{"type":"boolean"}}}},"required":["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"]},"ActorClothingStyle":{"type":"string","enum":["Casual","Formal","Sport","Doctor","Electrician"]},"ActorTrackQuality":{"type":"string","enum":["lite","studio","pictar"]},"ActorView":{"type":"string","enum":["front","side-front","side-back","sitting"]},"ActorTrackVariant":{"type":"array","items":{"type":"string","enum":["full_body","bubble","shoulder"]}},"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: 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:

```
GET https://docs.colossyan.com/basics/openapi/list-avatars.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.