Avatars

List avatars

Changed on

Returns a paginated list of the Telnyx stock avatars and custom avatars available to the authenticated organization. Custom avatars owned by other organizations are never returned. The image_url value is suitable for displaying a thumbnail and may be refreshed by listing or retrieving the avatar again. suggested_voice_id recommends a compatible Telnyx voice for stock avatars and is an empty string for custom avatars; it does not change an AI Assistant's voice automatically.

get/ai/avatars

Request

  • Base URL: https://api.telnyx.com/v2
  • URL: https://api.telnyx.com/v2/ai/avatars
  • Auth: HTTP bearer

Query parameters

page[size]integer

Number of avatars to return per page.

page[number]integer

Page number to retrieve, starting at 1.

filter[name]string

Return avatars whose names contain this value, using case-insensitive matching.

filter[id]string

Stable identifier returned by the Avatars API. Discover available stock IDs with GET /v2/ai/avatars and filter[avatar_type]=stock rather than maintaining a fixed list. Custom avatar IDs use the avatar_ prefix and must belong to the authenticated organization. The service validates that the selected avatar is available.

Example:avatar_0123456789abcdef0123456789abcdef

Return the avatar with this exact ID.

filter[avatar_type]'stock' | 'custom'

Whether the avatar is provided by Telnyx or was uploaded by the authenticated organization.

Return only stock or custom avatars.

Response

A page of available avatars.

Example response

{
  "data": [
    {
      "id": "avatar_0123456789abcdef0123456789abcdef",
      "name": "Customer portrait",
      "provider": "telnyx",
      "hosted": true,
      "image_url": "https://example.com/avatar.png",
      "image_url_expires_at": "2026-10-13T15:00:00Z",
      "suggested_voice_id": "Telnyx.Ultra.db6b0ed5-d5d3-463d-ae85-518a07d3c2b4",
      "size_bytes": 248512,
      "width_px": 1920,
      "height_px": 1080,
      "created_at": "2026-10-13T14:00:00Z",
      "updated_at": "2026-10-13T14:00:00Z"
    }
  ],
  "meta": {
    "total_pages": 1,
    "total_results": 1,
    "page_number": 1,
    "page_size": 20
  }
}

Changes

  • e33b4a326ddaRevision changes
    • breaking

      for the query request parameter filter[id], the minLength was increased from 0 to 1

    • breaking

      added the pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$ to the query request parameter filter[id]

    • breaking

      the // response's property type changed from no type to string for status

    • warning

      for the query request parameter filter[id], the maxLength was set to 128

    • info

      for the query request parameter filter[id], the type was generalized from no type to string

    • info

      added the optional property // to the response with the status

    • info

      removed subschema #1: Stock avatar ID subschema #2: Custom avatar ID from the // response property oneOf list for the response status

    • info

      the // response's property pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$ was added for the status

  • da303e40b51eRevision changes
    • info

      endpoint added