---
title: "List Voice Avatars"
method: GET
path: "/voice/avatars"
tags: ["Voice Agents"]
---

# List Voice Avatars

`GET /voice/avatars`

## Request

- Base URL: `https://api.speakai.co/v1`
- URL: `https://api.speakai.co/v1/voice/avatars`
- Auth: API key in header `x-speakai-key` and API key in header `x-access-token`

### List Avatars

Returns the shared system avatar catalog plus any avatars your company has uploaded, newest first. Another company's private uploads are never included.

## Response `200`

OK

- object
  - `status` 'success'
  - `data` object
    - `avatars` object[]
      - `avatarId` string: Server-generated UUID on create. Immutable.
      - `companyId` string, nullable: Absent on a shared system-catalog avatar, which every company can read but only Speak can write. Present on a company's own uploaded avatar.
      - `name` string: Required on create.
      - `provider` 'bey' | 'tavus' | 'heygen' | 'synthesia' | 'd-id': Required on create.
      - `imageUrl` string
      - `videoUrl` string
      - `localImagePath` string: Local file path used by internal upload flows.
      - `localVideoPath` string: Local file path used by internal upload flows.
      - `tavus` object: Set when provider is tavus.
        - `faceId` string: Required within this object if tavus is sent at all.
        - `palId` string
        - `status` 'started' | 'completed' | 'error'
        - `isRecommended` boolean
        - `trainingProgress` string
        - `faceType` 'user' | 'system'
        - `modelType` string
      - `bey` object: Set when provider is bey.
        - `avatarId` string: Required within this object if bey is sent at all.
        - `gender` string
        - `ethnicity` string
        - `voiceId` string
        - `ageRange` string
        - `style` string
        - `isDefault` boolean
        - `languageCode` string
      - `custom` object: Set when provider is a custom/self-hosted avatar.
        - `uploadedBy` string
        - `originalFileName` string
        - `fileSize` number
        - `mimeType` string
      - `category` 'professional' | 'casual' | 'stock' | 'custom' | 'premium': Defaults to professional if not sent.
      - `tags` string[]
      - `isPremium` boolean: Defaults to false.
      - `status` 'active' | 'inactive' | 'processing' | 'error': Defaults to active.
      - `isPublic` boolean: Defaults to true.
      - `description` string
      - `metadata` object: Arbitrary metadata object. Shape is not validated.
      - `createdBy` string: Id of the user who created this avatar.
      - `lastSyncedAt` string, date-time: Set by the system-catalog sync job for shared avatars.
      - `createdAt` string, date-time
      - `updatedAt` string, date-time

---

[API](https://skmtc.dev/speakai/apis/speak-ai-api.md) · [All operations](https://skmtc.dev/speakai/apis/speak-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/speakai/apis/speak-ai-api/revisions/52d777e6d46e?raw)