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

# List Avatars

> Get all available avatars (library + custom) for creating videos

## Overview

This endpoint returns all avatars available to your account, including both the Hooked library avatars and any custom avatars you've created.

### Query Parameters

<ParamField query="type" type="string" default="all">
  Filter avatars by type:

  * `library`: Only library avatars from Hooked
  * `custom`: Only custom avatars created by your team
  * `all`: Both library and custom avatars (default)
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="avatars" type="array">
      Array of avatar objects

      <Expandable title="avatar">
        <ResponseField name="id" type="string">
          Unique identifier for the avatar
        </ResponseField>

        <ResponseField name="name" type="string">
          Avatar display name
        </ResponseField>

        <ResponseField name="type" type="string">
          Avatar type (AI or Realistic)
        </ResponseField>

        <ResponseField name="gender" type="string">
          Avatar gender (Male, Female, or Non-binary)
        </ResponseField>

        <ResponseField name="age" type="string">
          Age category (Young, Middle-aged, Senior)
        </ResponseField>

        <ResponseField name="thumbnail" type="string">
          URL to avatar thumbnail image
        </ResponseField>

        <ResponseField name="isCustom" type="boolean">
          Whether this is a custom avatar
        </ResponseField>

        <ResponseField name="isPro" type="boolean">
          Whether this avatar requires a Pro plan
        </ResponseField>

        <ResponseField name="isHD" type="boolean">
          Whether this avatar supports HD quality
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="total" type="number">
      Total number of avatars returned
    </ResponseField>

    <ResponseField name="library" type="number">
      Number of library avatars
    </ResponseField>

    <ResponseField name="custom" type="number">
      Number of custom avatars
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.hooked.so/v1/avatar/list?type=library" \
    -H "x-api-key: your_api_key_here"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.hooked.so/v1/avatar/list?type=library', {
    headers: {
      'x-api-key': 'your_api_key_here'
    }
  });

  const data = await response.json();
  console.log(data.data.avatars);
  ```

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

  response = requests.get(
      'https://api.hooked.so/v1/avatar/list',
      params={'type': 'library'},
      headers={'x-api-key': 'your_api_key_here'}
  )

  avatars = response.json()['data']['avatars']
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "avatars": [
        {
          "id": "avatar_sarah_01",
          "name": "Sarah",
          "type": "Realistic",
          "gender": "Female",
          "age": "Young",
          "thumbnail": "https://cdn.hooked.so/avatars/sarah-thumb.jpg",
          "templateUrl": "https://cdn.hooked.so/avatars/sarah.mp4",
          "voiceActor": "Professional",
          "isHD": true,
          "isPro": false,
          "isNew": false,
          "situation": ["Business", "Casual"],
          "emotions": ["Happy", "Confident"],
          "skinTone": "medium",
          "isCustom": false,
          "source": "library"
        },
        {
          "id": "avatar_john_02",
          "name": "John",
          "type": "Realistic",
          "gender": "Male",
          "age": "Middle-aged",
          "thumbnail": "https://cdn.hooked.so/avatars/john-thumb.jpg",
          "templateUrl": "https://cdn.hooked.so/avatars/john.mp4",
          "voiceActor": "Professional",
          "isHD": true,
          "isPro": true,
          "isNew": false,
          "situation": ["Business", "Professional"],
          "emotions": ["Neutral", "Serious"],
          "skinTone": "light",
          "isCustom": false,
          "source": "library"
        }
      ],
      "total": 2,
      "library": 2,
      "custom": 0
    }
  }
  ```
</ResponseExample>

## Use Cases

<AccordionGroup>
  <Accordion title="Filter by gender and age" icon="filter">
    While the API doesn't support direct gender/age filtering, you can filter the results client-side:

    ```javascript theme={null}
    const youngFemaleAvatars = data.avatars.filter(
      avatar => avatar.gender === 'Female' && avatar.age === 'Young'
    );
    ```
  </Accordion>

  <Accordion title="Find HD avatars" icon="hd">
    Get only avatars that support HD quality:

    ```javascript theme={null}
    const hdAvatars = data.avatars.filter(avatar => avatar.isHD);
    ```
  </Accordion>

  <Accordion title="Check Pro requirements" icon="crown">
    Identify which avatars require a Pro subscription:

    ```python theme={null}
    pro_avatars = [a for a in avatars if a['isPro']]
    free_avatars = [a for a in avatars if not a['isPro']]
    ```
  </Accordion>
</AccordionGroup>

## Notes

<Note>
  Custom avatars require processing time after creation. Only avatars with `status: 2` (completed) are included in the list.
</Note>

<Tip>
  Cache avatar lists for better performance. Avatar libraries don't change frequently, so you can safely cache this data for 24 hours.
</Tip>


## OpenAPI

````yaml GET /v1/avatar/list
openapi: 3.0.0
info:
  title: Hooked API
  version: 1.0.0
  description: AI Video Generation API
servers:
  - url: https://api.hooked.so
security:
  - ApiKeyAuth: []
paths:
  /v1/avatar/list:
    get:
      tags: []
      summary: List Avatars
      description: Get all available avatars (library + custom) for creating videos
      operationId: listAvatars
      parameters:
        - name: type
          in: query
          description: Filter by avatar type
          required: false
          schema:
            type: string
            enum:
              - library
              - custom
              - all
            default: all
      responses:
        '200':
          description: Success
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````