> ## 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 Available Avatars

> Get list of available avatar looks for video generation

## Overview

This endpoint returns all available avatar looks that you can use in video generation. Avatar looks are specific appearances/styles of digital presenters that can deliver your video content.

## 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 avatars 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>

## Response

Array of available avatar look objects:

<ResponseField name="id" type="string">
  Unique identifier for the avatar look (use this in generation requests).
</ResponseField>

<ResponseField name="name" type="string">
  Human-readable name of the avatar look.
</ResponseField>

<ResponseField name="gender" type="string">
  Avatar gender: `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">
  Setting/background of the avatar (e.g., "office", "studio", "outdoor").
</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">
  Optimal video format for this avatar (e.g., "vertical", "horizontal").
</ResponseField>

<ResponseField name="thumbnail" type="string">
  URL to a static thumbnail image of the avatar.
</ResponseField>

<ResponseField name="preview" type="string">
  URL to a short video preview of the avatar in action.
</ResponseField>

<ResponseField name="model_available" type="array">
  Array of avatar model IDs compatible with this avatar look. Possible values: `standard`, `premium`, `ultra`, `veo-3-fast`, `veo-3`, `veo-3-lite`, `omni-flash`, `ora-lite`, `ora-standard`, `ora-pro`, `seedance-2`, `seedance-2-fast`, `seedance-2-1080p`.
</ResponseField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/resources/avatars" \
    -H "Authorization: Bearer your_api_key"

  # With filters
  curl -X GET "https://app.hoox.video/api/public/v1/resources/avatars?gender=female&place=office&hair_color=brown" \
    -H "Authorization: Bearer your_api_key"
  ```

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

  url = "https://app.hoox.video/api/public/v1/resources/avatars"
  headers = {
      "Authorization": "Bearer your_api_key"
  }

  # Get all avatars
  response = requests.get(url, headers=headers)
  avatars = response.json()

  # Filter for specific avatar metadata
  params = {
      "gender": "female",
      "place": "office,podcast",
      "hair_color": "brown"
  }
  response = requests.get(url, headers=headers, params=params)
  filtered_avatars = response.json()

  print(f"Found {len(filtered_avatars)} matching avatars")
  for avatar in filtered_avatars:
      print(f"- {avatar['name']} ({avatar['id']}) - {avatar['place']}")
  ```

  ```javascript JavaScript theme={null}
  // Get all avatars
  const response = await fetch('https://app.hoox.video/api/public/v1/resources/avatars', {
    headers: {
      'Authorization': 'Bearer your_api_key'
    }
  });

  const data = await response.json();
  console.log(`Found ${data.length} avatars`);

  // Filter for specific criteria
  const filteredResponse = await fetch(
    'https://app.hoox.video/api/public/v1/resources/avatars?gender=female&place=office&selfie=false',
    {
      headers: {
        'Authorization': 'Bearer your_api_key'
      }
    }
  );

  const filteredData = await filteredResponse.json();
  console.log('Filtered avatars:', filteredData);
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  [
    {
      "id": "avatar_business_woman_office_1",
      "name": "Professional Sarah - Office",
      "gender": "female",
      "age_range": "adult",
      "ethnicity": "white-western-european",
      "hair_color": "brown",
      "place": "office",
      "accessories": ["laptop"],
      "action": "working",
      "emotion": "focused",
      "selfie": false,
      "format": "vertical",
      "thumbnail": "https://storage.hoox.video/avatars/thumbnails/avatar_business_woman_office_1.jpg",
      "preview": "https://storage.hoox.video/avatars/previews/avatar_business_woman_office_1.mp4",
      "model_available": ["standard"]
    },
    {
      "id": "avatar_business_man_studio_1",
      "name": "Executive James - Studio",
      "gender": "male",
      "age_range": "adult",
      "ethnicity": "white-western-european",
      "hair_color": "brown",
      "place": "studio",
      "accessories": ["microphone"],
      "action": "presenting",
      "emotion": "confident",
      "selfie": false,
      "format": "vertical",
      "thumbnail": "https://storage.hoox.video/avatars/thumbnails/avatar_business_man_studio_1.jpg",
      "preview": "https://storage.hoox.video/avatars/previews/avatar_business_man_studio_1.mp4",
      "model_available": ["standard"]
    },
    {
      "id": "avatar_casual_woman_home_1",
      "name": "Friendly Emma - Home",
      "gender": "female",
      "age_range": "young_adult",
      "ethnicity": "white-western-european",
      "hair_color": "blonde",
      "place": "home",
      "accessories": [],
      "action": "relaxing",
      "emotion": "happy",
      "selfie": false,
      "format": "vertical",
      "thumbnail": "https://storage.hoox.video/avatars/thumbnails/avatar_casual_woman_home_1.jpg",
      "preview": "https://storage.hoox.video/avatars/previews/avatar_casual_woman_home_1.mp4",
      "model_available": ["standard"]
    },
    {
      "id": "custom_avatar_user_456",
      "name": "My Brand Ambassador",
      "gender": "female",
      "age_range": "adult",
      "ethnicity": "hispanic-or-latino",
      "hair_color": "brown",
      "place": "office",
      "accessories": [],
      "action": "presenting",
      "emotion": "neutral",
      "selfie": false,
      "format": "vertical",
      "thumbnail": "https://storage.hoox.video/avatars/thumbnails/custom_avatar_user_456.jpg",
      "model_available": ["premium", "ultra", "veo-3-fast", "veo-3", "veo-3-lite", "omni-flash", "ora-lite", "ora-standard", "ora-pro", "seedance-2", "seedance-2-fast", "seedance-2-1080p"]
    }
  ]
  ```
</ResponseExample>