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

# Get Avatars

> Retrieve the list of available AI avatars and their looks for video creation

## Overview

The Get Avatars API retrieves a paginated list of all available AI avatars organized by avatar groups. Each avatar group contains multiple "looks" (different styles/outfits) that you can use to create presenter-style videos.

<Tip>
  Use this endpoint to discover available avatars before creating avatar videos. The look `id` becomes your `avatarId` when using the [Create Storyboard Preview](/api-reference/videos/create-storyboard-preview) API.
</Tip>

***

## API Endpoint

```http theme={null}
GET https://api.pictory.ai/pictoryapis/v1/avatars
```

***

## Request Headers

<ParamField header="Authorization" type="string" required>
  API key for authentication

  ```
  Authorization: YOUR_API_KEY
  ```
</ParamField>

***

## Query Parameters

<ParamField query="nextPageKey" type="string">
  Base64 pagination token returned in `nextPageKey` from previous response. Omit for first page.
</ParamField>

***

## Response

The API returns avatar groups with their available looks.

<ResponseField name="items" type="array">
  Array of avatar group objects
</ResponseField>

<ResponseField name="nextPageKey" type="string | null">
  Base64 pagination token for next page. `null` indicates no more pages available.
</ResponseField>

### Avatar Group Object (`items[]`)

<ResponseField name="items[].id" type="string">
  Unique avatar group ID (e.g., "e0e84faea390465896db75a83be45085")
</ResponseField>

<ResponseField name="items[].name" type="string">
  Display name of the avatar person (e.g., "Annie", "Brandon").
</ResponseField>

<ResponseField name="items[].gender" type="string | null">
  Gender of the avatar: `"Male"`, `"Female"`, or `null`
</ResponseField>

<ResponseField name="items[].looks" type="array">
  Array of available looks/styles for this avatar person
</ResponseField>

### Avatar Look Object (`items[].looks[]`)

<ResponseField name="items[].looks[].id" type="string">
  Unique look identifier (e.g., "Annie\_expressive12\_public"). Use this as `avatarId` in video creation.
</ResponseField>

<ResponseField name="items[].looks[].name" type="string">
  Display name of the look (e.g., "Annie in Tan Jacket", "Brandon in Grey Suit")
</ResponseField>

<ResponseField name="items[].looks[].previewImage" type="string">
  URL to static preview image (.webp format)
</ResponseField>

<ResponseField name="items[].looks[].previewVideo" type="string">
  URL to blurred preview video (.webm format) showing the avatar in action
</ResponseField>

***

## Code Examples

<Tip>
  Replace `YOUR_API_KEY` with your actual API key
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.pictory.ai/pictoryapis/v1/avatars' \
    --header 'Authorization: YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.pictory.ai/pictoryapis/v1/avatars', {
    method: 'GET',
    headers: {
      'Authorization': 'YOUR_API_KEY'
    }
  });

  const data = await response.json();
  console.log('Avatar groups:', data.items.length);
  console.log('Next page key:', data.nextPageKey);
  ```

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

  response = requests.get(
      'https://api.pictory.ai/pictoryapis/v1/avatars',
      headers={
          'Authorization': 'YOUR_API_KEY'
      }
  )

  data = response.json()
  print(f"Avatar groups: {len(data['items'])}")
  print(f"Next page key: {data['nextPageKey']}")
  ```
</CodeGroup>

***

## Response Example

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "items": [
      {
        "id": "e0e84faea390465896db75a83be45085",
        "name": "Annie",
        "gender": "Female",
        "looks": [
          {
            "id": "Annie_expressive12_public",
            "name": "Annie in Tan Jacket",
            "previewImage": "https://pictory-static.pictorycontent.com/avatars/preview/e0e84faea390465896db75a83be45085/Annie_expressive12_public/previewImage.webp",
            "previewVideo": "https://pictory-static.pictorycontent.com/avatars/preview/e0e84faea390465896db75a83be45085/Annie_expressive12_public/previewVideo_blurred.webm"
          },
          {
            "id": "Annie_expressive2_public",
            "name": "Annie in Blue Casual",
            "previewImage": "https://pictory-static.pictorycontent.com/avatars/preview/e0e84faea390465896db75a83be45085/Annie_expressive2_public/previewImage.webp",
            "previewVideo": "https://pictory-static.pictorycontent.com/avatars/preview/e0e84faea390465896db75a83be45085/Annie_expressive2_public/previewVideo_blurred.webm"
          }
        ]
      },
      {
        "id": "d08c85e6cff84d78b6dc41d83a2eccce",
        "name": "Brandon",
        "gender": "Male",
        "looks": [
          {
            "id": "Brandon_expressive2_public",
            "name": "Brandon in Grey Suit",
            "previewImage": "https://pictory-static.pictorycontent.com/avatars/preview/d08c85e6cff84d78b6dc41d83a2eccce/Brandon_expressive2_public/previewImage.webp",
            "previewVideo": "https://pictory-static.pictorycontent.com/avatars/preview/d08c85e6cff84d78b6dc41d83a2eccce/Brandon_expressive2_public/previewVideo_blurred.webm"
          }
        ]
      }
    ],
    "nextPageKey": null
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Unauthorized"
  }
  ```
</ResponseExample>

***

## Pagination

The API returns results in pages. Use the `nextPageKey` to fetch subsequent pages:

```javascript theme={null}
// Fetch first page
let response = await fetch('https://api.pictory.ai/pictoryapis/v1/avatars', {
  headers: { 'Authorization': 'YOUR_API_KEY' }
});
let data = await response.json();
let allAvatars = [...data.items];

// Fetch remaining pages
while (data.nextPageKey) {
  response = await fetch(`https://api.pictory.ai/pictoryapis/v1/avatars?nextPageKey=${encodeURIComponent(data.nextPageKey)}`, {
    headers: { 'Authorization': 'YOUR_API_KEY' }
  });
  data = await response.json();
  allAvatars.push(...data.items);
}

console.log('Total avatar groups:', allAvatars.length);
```

***

## Usage Example

Here's how to fetch avatars and use them in video creation:

```javascript theme={null}
// Step 1: Get available avatars
const avatarsResponse = await fetch('https://api.pictory.ai/pictoryapis/v1/avatars', {
  headers: { 'Authorization': 'YOUR_API_KEY' }
});

const avatarsData = await avatarsResponse.json();

// Step 2: Find an avatar group by name
const annieGroup = avatarsData.items.find(group => group.name === 'Annie');

// Step 3: Select a specific look
const selectedLook = annieGroup.looks.find(look => look.name.includes('Tan Jacket'));

console.log('Selected avatar:');
console.log('  avatarId:', selectedLook.id);
console.log('  Preview:', selectedLook.previewVideo);

// Step 4: Create video with the selected avatar
const videoResponse = await fetch('https://api.pictory.ai/pictoryapis/v2/video/storyboard', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    videoName: 'my_avatar_video',
    language: 'en',
    videoWidth: 1920,
    videoHeight: 1080,
    voiceOver: {
      enabled: true,
      aiVoices: [{
        speaker: 'Matthew',
        speed: 100
      }]
    },
    avatar: {
      avatarId: selectedLook.id,           // "Annie_expressive12_public"
      position: 'bottom-right',
      width: '20%'
    },
    scenes: [{
      story: 'Welcome to my video!',
      createSceneOnEndOfSentence: true,
      minimumDuration: 4
    }]
  })
});

const videoData = await videoResponse.json();
console.log('Video job created:', videoData.data.jobId);
```

***

## Filtering and Selecting Avatars

You can filter avatars based on your requirements:

```javascript theme={null}
const avatarsData = await getAvatars();

// Filter by gender
const femaleAvatars = avatarsData.items.filter(group => group.gender === 'Female');
const maleAvatars = avatarsData.items.filter(group => group.gender === 'Male');

// Get all looks for female avatars
const femaleLooks = femaleAvatars.flatMap(group =>
  group.looks.map(look => ({
    avatarId: look.id,
    lookName: look.name,
    gender: group.gender
  }))
);

// Find specific avatar by name
const caroline = avatarsData.items.find(group => group.name === 'Caroline');
const carolineLooks = caroline ? caroline.looks : [];

// Search for looks by outfit
const suitLooks = avatarsData.items.flatMap(group =>
  group.looks.filter(look => look.name.toLowerCase().includes('suit'))
);

console.log('Female avatars:', femaleAvatars.length);
console.log('Male avatars:', maleAvatars.length);
console.log('Suit looks:', suitLooks.length);
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Cache Avatar List">
    **Recommendation:** Cache the avatar list to reduce API calls

    The avatar list does not change frequently, so you can cache it:

    * Store the response locally or in your database
    * Refresh the cache periodically (e.g., daily or weekly)
    * Reduce latency and API calls in your application
    * Remember to handle pagination when caching
  </Accordion>

  <Accordion title="Handle Pagination Properly">
    **Recommendation:** Fetch all pages for complete avatar list

    The API returns paginated results:

    * Check `nextPageKey` for additional pages
    * Continue fetching until `nextPageKey` is `null`
    * Combine results from all pages
    * Cache the complete list after fetching all pages
  </Accordion>

  <Accordion title="Preview Before Selection">
    **Recommendation:** Show preview videos to users

    Use the `previewVideo` and `previewImage` URLs to:

    * Display avatar previews in your UI
    * Let users see avatar appearance and style
    * Show different looks for the same avatar person
    * Help users make informed selections
  </Accordion>

  <Accordion title="Validate Avatar Availability">
    **Recommendation:** Check avatar availability before creating videos

    Before hardcoding avatar IDs:

    * Fetch the latest avatar list
    * Verify the look ID exists
    * Handle cases where a look might be deprecated
    * Provide fallback options
  </Accordion>

  <Accordion title="Understand Avatar Structure">
    **Recommendation:** Group vs Look distinction matters

    Remember the hierarchy:

    * **Avatar Group** (`items[]`): The avatar person (e.g., "Annie")
    * **Avatar Look** (`items[].looks[]`): A specific style/outfit (e.g., "Annie in Tan Jacket")
      * Use `items[].looks[].id` as `avatarId` in video creation

    One avatar person can have multiple looks to choose from.
  </Accordion>
</AccordionGroup>

***

## Error Handling

<AccordionGroup>
  <Accordion title="401 - Unauthorized">
    ```json theme={null}
    {
      "message": "Unauthorized"
    }
    ```

    **Solution:** Check your API key is valid and correctly formatted in the Authorization header.
  </Accordion>

  <Accordion title="Invalid Page Key">
    **Issue:** Providing an invalid or expired `nextPageKey` parameter

    **Solution:**

    * Only use `nextPageKey` values returned from previous API responses
    * Do not manually construct or modify page keys
    * If pagination fails, restart from the first page
  </Accordion>

  <Accordion title="Network Error">
    **Issue:** Request fails or times out

    **Solution:**

    * Check network connectivity
    * Verify the endpoint URL is correct
    * Implement retry logic with exponential backoff
    * Handle timeout errors gracefully
  </Accordion>
</AccordionGroup>

***

## Related Resources

<CardGroup cols={2}>
  <Card title="Create Storyboard Preview" icon="video" href="/api-reference/videos/create-storyboard-preview">
    Create presenter-style videos with avatars
  </Card>

  <Card title="Create Avatar Video Guide" icon="book" href="/guides/video-with-avatar/create-avatar-video">
    Step-by-step guide to creating avatar videos
  </Card>

  <Card title="Avatar Positioning" icon="location-dot" href="/guides/video-with-avatar/avatar-positioning">
    Learn to position avatars in videos
  </Card>

  <Card title="Get Voiceover Tracks" icon="microphone" href="/api-reference/voiceovers/get-voiceover-tracks">
    Get available AI voices for avatar narration
  </Card>
</CardGroup>