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

# List Avatars

> Retrieve a paginated list of avatars available for video generation

Retrieves a paginated list of avatars. You can request either realistic (public) avatars available to all users, or your custom avatars.

## Query Parameters

<ParamField query="type" type="string" required>
  The type of avatars to retrieve.

  **Allowed values:** `realistic`, `custom`

  * `realistic`: Public avatars available to all users
  * `custom`: Your custom avatars (uploaded or AI-generated)
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Maximum number of avatars to return per page.

  **Range:** 1-100
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of avatars to skip (for pagination).

  **Minimum:** 0
</ParamField>

## Response

<ResponseField name="avatars" type="array" required>
  List of avatar objects.

  <Expandable title="Avatar properties">
    <ResponseField name="avatars[].id" type="string">
      Unique identifier for the avatar. Use this ID when creating videos with the avatar.
    </ResponseField>

    <ResponseField name="avatars[].name" type="string">
      Display name of the avatar.
    </ResponseField>

    <ResponseField name="avatars[].type" type="string">
      Avatar type: `realistic` or `custom`.
    </ResponseField>

    <ResponseField name="avatars[].image_url" type="string | null">
      Thumbnail image URL for the avatar. May be `null` if not available.
    </ResponseField>

    <ResponseField name="avatars[].video_url" type="string | null">
      Thumbnail video URL for the avatar preview. May be `null` if not available.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object" required>
  Pagination information.

  <Expandable title="Pagination properties">
    <ResponseField name="pagination.total" type="integer">
      Total number of avatars available.
    </ResponseField>

    <ResponseField name="pagination.limit" type="integer">
      Number of avatars per page (as requested).
    </ResponseField>

    <ResponseField name="pagination.offset" type="integer">
      Current offset (as requested).
    </ResponseField>

    <ResponseField name="pagination.has_more" type="boolean">
      Whether there are more avatars available after this page.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  # List realistic avatars
  curl "https://api.vibepeak.ai/v1/avatars?type=realistic" \
    -H "Authorization: Bearer vpk_live_xxxxx"

  # List custom avatars with pagination
  curl "https://api.vibepeak.ai/v1/avatars?type=custom&limit=10&offset=0" \
    -H "Authorization: Bearer vpk_live_xxxxx"
  ```

  ```javascript Node.js theme={null}
  // List realistic avatars
  const response = await fetch('https://api.vibepeak.ai/v1/avatars?type=realistic', {
    headers: {
      'Authorization': 'Bearer vpk_live_xxxxx'
    }
  });

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

  for (const avatar of data.avatars) {
    console.log(`${avatar.name} (${avatar.id})`);
  }

  // Paginate through all avatars
  async function getAllAvatars(type) {
    const avatars = [];
    let offset = 0;
    const limit = 50;

    while (true) {
      const res = await fetch(
        `https://api.vibepeak.ai/v1/avatars?type=${type}&limit=${limit}&offset=${offset}`,
        { headers: { 'Authorization': 'Bearer vpk_live_xxxxx' } }
      );
      const data = await res.json();
      avatars.push(...data.avatars);

      if (!data.pagination.has_more) break;
      offset += limit;
    }

    return avatars;
  }
  ```

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

  # List realistic avatars
  response = requests.get(
      'https://api.vibepeak.ai/v1/avatars',
      params={'type': 'realistic'},
      headers={'Authorization': 'Bearer vpk_live_xxxxx'}
  )

  data = response.json()
  print(f"Found {data['pagination']['total']} avatars")

  for avatar in data['avatars']:
      print(f"{avatar['name']} ({avatar['id']})")

  # Paginate through all custom avatars
  def get_all_avatars(avatar_type):
      avatars = []
      offset = 0
      limit = 50

      while True:
          response = requests.get(
              'https://api.vibepeak.ai/v1/avatars',
              params={'type': avatar_type, 'limit': limit, 'offset': offset},
              headers={'Authorization': 'Bearer vpk_live_xxxxx'}
          )
          data = response.json()
          avatars.extend(data['avatars'])

          if not data['pagination']['has_more']:
              break
          offset += limit

      return avatars
  ```
</RequestExample>

<ResponseExample>
  ```json Realistic Avatars theme={null}
  {
    "avatars": [
      {
        "id": "e225efd4-f936-4a01-b56a-bb3ab30c2cbd",
        "name": "Sarah",
        "type": "realistic",
        "image_url": "https://storage.vibepeak.ai/avatars/sarah-thumb.jpg",
        "video_url": "https://storage.vibepeak.ai/avatars/sarah-thumb.mp4"
      },
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Michael",
        "type": "realistic",
        "image_url": "https://storage.vibepeak.ai/avatars/michael-thumb.jpg",
        "video_url": "https://storage.vibepeak.ai/avatars/michael-thumb.mp4"
      }
    ],
    "pagination": {
      "total": 45,
      "limit": 20,
      "offset": 0,
      "has_more": true
    }
  }
  ```

  ```json Custom Avatars theme={null}
  {
    "avatars": [
      {
        "id": "43d54a0f-ea77-45e3-8f1e-f1c6feca7f42",
        "name": "My Business Avatar",
        "type": "custom",
        "image_url": "https://storage.vibepeak.ai/custom/user123/avatar1-thumb.jpg",
        "video_url": null
      }
    ],
    "pagination": {
      "total": 3,
      "limit": 20,
      "offset": 0,
      "has_more": false
    }
  }
  ```

  ```json Empty Response theme={null}
  {
    "avatars": [],
    "pagination": {
      "total": 0,
      "limit": 20,
      "offset": 0,
      "has_more": false
    }
  }
  ```

  ```json 400 Missing Parameter theme={null}
  {
    "error": {
      "code": "MISSING_PARAMETER",
      "message": "Missing required query parameter: 'type'. Must be 'realistic' or 'custom'.",
      "request_id": "req_xyz123"
    }
  }
  ```

  ```json 400 Invalid Parameter theme={null}
  {
    "error": {
      "code": "INVALID_PARAMETER",
      "message": "Invalid value for 'type'. Must be 'realistic' or 'custom'.",
      "request_id": "req_xyz123"
    }
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": {
      "code": "INVALID_API_KEY",
      "message": "Invalid or missing API key.",
      "request_id": "req_xyz123"
    }
  }
  ```
</ResponseExample>

## Usage with Video Creation

Once you've retrieved the avatar list, use the avatar `id` when creating videos:

```javascript theme={null}
// 1. List available avatars
const avatarsResponse = await fetch('https://api.vibepeak.ai/v1/avatars?type=realistic', {
  headers: { 'Authorization': 'Bearer vpk_live_xxxxx' }
});
const { avatars } = await avatarsResponse.json();

// 2. Select an avatar and create a video
const selectedAvatar = avatars[0];

const videoResponse = await fetch('https://api.vibepeak.ai/v1/real-estate/narrated-slideshow', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vpk_live_xxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    images: ['https://example.com/image1.jpg', /* ... */],
    script: 'Welcome to this beautiful property...',
    voice: { voice_id: 'voice-123' },
    style: 'do-not-modify',
    avatar_id: selectedAvatar.id  // Use the avatar ID here
  })
});
```

## Error Codes

| Code                | Status | Description                                    |
| ------------------- | ------ | ---------------------------------------------- |
| `MISSING_PARAMETER` | 400    | Required `type` parameter is missing           |
| `INVALID_PARAMETER` | 400    | Invalid value for `type`, `limit`, or `offset` |
| `VALIDATION_ERROR`  | 400    | Query parameter validation failed              |
| `INVALID_API_KEY`   | 401    | Invalid or missing API key                     |

See [Error Handling](/concepts/error-handling) for more details.