> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hoox.video/llms.txt
> Use this file to discover all available pages before exploring further.

# List Avatars

> Retrieve available avatar looks for your space and public catalog

## Overview

This endpoint retrieves a list of available avatar looks. It returns looks from your space first (if any), followed by looks from the public catalog. Results can be filtered by avatar and look metadata.

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Query Parameters

<ParamField query="gender" type="enum">
  Filter by gender. Available values: `male`, `female`.
</ParamField>

<ParamField query="age_range" type="enum">
  Filter by avatar age range. Accepts a comma-separated list. Available values: `senior`, `adult`, `young_adult`, `adolescent`.
</ParamField>

<ParamField query="ethnicity" type="enum">
  Filter by avatar ethnicity. Accepts a comma-separated list. Available values: `black-or-african-american`, `white-western-european`, `white-eastern-european`, `hispanic-or-latino`, `middle-eastern-or-north-african`, `east-asian`, `southeast-asian`, `south-asian`.
</ParamField>

<ParamField query="hair_color" type="enum">
  Filter by hair color. Accepts a comma-separated list. Available values: `black`, `brown`, `blonde`, `red`, `gray`, `white`, `bald`.
</ParamField>

<ParamField query="place" type="enum">
  Filter by look place. Accepts a comma-separated list. Available values: `bathroom`, `beach`, `car`, `bedroom`, `podcast`, `home`, `office`, `gym`, `outdoor`, `kitchen`, `restaurant`, `studio`, `street`, `classroom`, `hospital`, `hotel`, `park`, `store`, `cafe`, `other`.
</ParamField>

<ParamField query="selfie" type="boolean">
  Filter by selfie looks. Use `true` or `false`.
</ParamField>

<ParamField query="action" type="enum">
  Filter by look action. Accepts a comma-separated list. Available values: `working`, `eating`, `drinking`, `cooking`, `exercising`, `reading`, `driving`, `listening_to_music`, `getting_a_haircut`, `presenting`, `calling`, `relaxing`, `shopping`, `traveling`, `applying_skincare`.
</ParamField>

<ParamField query="emotion" type="enum">
  Filter by look emotion. Accepts a comma-separated list. Available values: `happy`, `calm`, `focused`, `relaxed`, `neutral`, `excited`, `confident`, `sad`, `skeptical`, `bored`, `engaged`.
</ParamField>

<ParamField query="accessories" type="enum">
  Filter by visible accessories. Accepts a comma-separated list. Available values: `microphone`, `laptop`, `phone`, `headphones`, `earbuds`, `glasses`, `watch`, `drink`, `skincare`, `book`, `bag`, `camera`, `pillow`, `earrings`, `necklace`, `bracelet`, `ring`.
</ParamField>

<ParamField query="onlyPublic" type="boolean" default="false">
  If `true`, returns only public catalog avatars (excludes custom space avatars). Defaults to `false` (returns both space and public avatars).
</ParamField>

## Response

Returns an array of avatar look objects.

<ResponseField name="id" type="string">
  Unique identifier of the look.
</ResponseField>

<ResponseField name="avatar_id" type="string">
  Unique identifier of the parent avatar.
</ResponseField>

<ResponseField name="avatar_name" type="string">
  Name of the avatar.
</ResponseField>

<ResponseField name="look_name" type="string">
  Name of the avatar look.
</ResponseField>

<ResponseField name="gender" type="string">
  Gender of the avatar: `male` or `female`.
</ResponseField>

<ResponseField name="age_range" type="string">
  Avatar age range.
</ResponseField>

<ResponseField name="ethnicity" type="string">
  Avatar ethnicity.
</ResponseField>

<ResponseField name="hair_color" type="string">
  Avatar hair color.
</ResponseField>

<ResponseField name="place" type="string">
  Place or context of the look (e.g., "studio", "office").
</ResponseField>

<ResponseField name="accessories" type="array">
  Visible accessories or props in the look.
</ResponseField>

<ResponseField name="action" type="string">
  Main action detected for the look.
</ResponseField>

<ResponseField name="emotion" type="string">
  Emotion or mood detected for the look.
</ResponseField>

<ResponseField name="selfie" type="boolean">
  Whether the look is a selfie-style shot.
</ResponseField>

<ResponseField name="format" type="string">
  Image format: `vertical` or `horizontal`.
</ResponseField>

<ResponseField name="thumbnail" type="string">
  URL of the look thumbnail image.
</ResponseField>

<ResponseField name="preview" type="string">
  Preview URL if available, otherwise `null`.
</ResponseField>

<ResponseField name="model_available" type="array">
  Array of available models for this look. If `preview` exists, only `standard` is available. Otherwise, models like `premium`, `ultra`, `veo-3-fast`, `veo-3`, `veo-3-lite`, `omni-flash`, `ora-lite`, `ora-standard`, `ora-pro`, `seedance-2`, `seedance-2-fast`, and `seedance-2-1080p` may be available.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/avatar/list?gender=male&place=podcast&accessories=microphone" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/avatar/list"
  params = {"gender": "male", "place": "podcast", "accessories": "microphone"}
  headers = {"Authorization": "Bearer your_api_key"}

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = new URL('https://app.hoox.video/api/public/v1/avatar/list');
  url.searchParams.set('gender', 'male');
  url.searchParams.set('place', 'podcast');
  url.searchParams.set('accessories', 'microphone');

  const response = await fetch(url, {
    headers: {
      'Authorization': 'Bearer your_api_key'
    }
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  [
    {
      "id": "look_id",
      "avatar_id": "avatar_id_1",
      "avatar_name": "Avatar name",
      "look_name": "Look name",
      "gender": "male",
      "age_range": "adult",
      "ethnicity": "white-western-european",
      "hair_color": "brown",
      "place": "studio",
      "accessories": ["microphone"],
      "action": "presenting",
      "emotion": "focused",
      "selfie": false,
      "format": "vertical",
      "thumbnail": "https://cdn.example.com/thumbnail.jpg",
      "preview": null,
      "model_available": ["premium", "ultra", "veo-3", "veo-3-fast", "veo-3-lite", "omni-flash", "ora-lite", "ora-standard", "ora-pro", "seedance-2", "seedance-2-fast", "seedance-2-1080p"]
    },
    {
      "id": "look_id_2",
      "avatar_id": "avatar_id_1",
      "avatar_name": "Avatar name",
      "look_name": "Another Look",
      "gender": "female",
      "age_range": "young_adult",
      "ethnicity": "east-asian",
      "hair_color": "black",
      "place": "office",
      "accessories": ["laptop"],
      "action": "working",
      "emotion": "neutral",
      "selfie": false,
      "format": "horizontal",
      "thumbnail": "https://cdn.example.com/thumbnail2.jpg",
      "preview": "https://cdn.example.com/preview2.mp4",
      "model_available": ["standard"]
    }
  ]
  ```
</ResponseExample>

## Notes

* By default, looks from your space are returned first, followed by public catalog looks
* Set `onlyPublic=true` to return only public catalog looks (excludes custom space avatars)
* The `model_available` field indicates which video generation models can be used with this look
* If a look has a `preview` URL, it means the look is pre-rendered and only the `standard` model is available
* Use the `avatar_id` field when referencing the parent avatar, and the `id` field for the specific look when creating videos with the `/generation/start` endpoint