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

# List avatars

> 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.



## OpenAPI

````yaml /openapi/source/external/inference/inference-embedding.json get /ai/avatars
openapi: 3.1.0
info:
  version: 2.0.0
  title: Telnyx API
  x-latency-category: responsive
  x-endpoint-cost: light
  description: SIP trunking, SMS, MMS, Call Control and Telephony Data Services.
  contact:
    email: support@telnyx.com
servers:
  - url: https://api.telnyx.com/v2
    description: Version 2.0.0 of the Telnyx API
security:
  - bearerAuth: []
tags:
  - name: Chat
    description: Generate text with LLMs
  - name: Assistants
    description: Configure AI assistant specifications
  - name: Avatars
    description: Create and manage real-time AI avatars
  - name: Conversations
    description: Manage historical AI assistant conversations
  - name: File-based Text-to-Speech
    description: Turn audio into text or text into audio.
  - name: Embeddings
    description: Embed documents and perform text searches
  - name: Clusters
    description: Identify common themes and patterns in your embedded documents
  - name: Fine Tuning
    description: Customize LLMs for your unique needs
  - name: OpenAI Embeddings
    description: >-
      OpenAI-compatible embeddings endpoints for generating vector
      representations of text
paths:
  /ai/avatars:
    get:
      tags:
        - Avatars
      summary: List avatars
      description: >-
        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.
      operationId: list_avatars_public_avatars_get
      parameters:
        - name: page[size]
          in: query
          description: Number of avatars to return per page.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: page[number]
          in: query
          description: Page number to retrieve, starting at 1.
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: filter[name]
          in: query
          description: >-
            Return avatars whose names contain this value, using
            case-insensitive matching.
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 255
        - name: filter[id]
          in: query
          description: Return the avatar with this exact ID.
          required: false
          schema:
            $ref: '#/components/schemas/AvatarId'
        - name: filter[avatar_type]
          in: query
          description: Return only stock or custom avatars.
          required: false
          schema:
            $ref: '#/components/schemas/AvatarType'
      responses:
        '200':
          description: A page of available avatars.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvatarListResponse'
              example:
                data:
                  - id: elena
                    name: Elena
                    provider: telnyx
                    avatar_type: stock
                    hosted: true
                    image_url: https://example.com/avatars/elena.png
                    suggested_voice_id: Telnyx.Ultra.db6b0ed5-d5d3-463d-ae85-518a07d3c2b4
                  - id: avatar_0123456789abcdef0123456789abcdef
                    name: Customer portrait
                    provider: telnyx
                    avatar_type: custom
                    hosted: true
                    image_url: https://example.com/avatar.png
                    image_url_expires_at: '2026-10-13T15:00:00Z'
                    suggested_voice_id: ''
                    content_type: image/png
                    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: 2
                  page_number: 1
                  page_size: 20
        '400':
          $ref: '#/components/responses/AvatarRequestValidationErrorResponse'
        '503':
          $ref: '#/components/responses/AvatarServiceUnavailableResponse'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Telnyx from 'telnyx';

            const client = new Telnyx({
              apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
            });

            // Automatically fetches more pages as needed.
            for await (const response of client.ai.avatars.list()) {
              console.log(response);
            }
        - lang: Python
          source: |
            import os
            from telnyx import Telnyx

            client = Telnyx(
                api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
            )
            page = client.ai.avatars.list()
            print(page.data)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tavatars, err := client.AI.Avatars.List(context.TODO())\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", avatars.Data)\n}\n"
        - lang: Java
          source: |-
            package com.telnyx.sdk.example;

            import com.telnyx.sdk.client.TelnyxClient;
            import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    TelnyxClient client = TelnyxOkHttpClient.fromEnv();

                    var page = client.ai().avatars().list();
                }
            }
        - lang: Ruby
          source: |-
            require "telnyx"

            telnyx = Telnyx::Client.new(api_key: "My API Key")

            page = telnyx.ai.avatars.list

            puts(page)
        - lang: PHP
          source: >-
            <?php


            require_once dirname(__DIR__) . '/vendor/autoload.php';


            use Telnyx\Client;

            use Telnyx\Core\Exceptions\APIException;


            $client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API
            Key');


            try {
              $page = $client->ai->avatars->list();

              var_dump($page);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: CLI
          source: |-
            telnyx ai:avatars list \
              --api-key 'My API Key'
components:
  schemas:
    AvatarId:
      type: string
      minLength: 1
      maxLength: 128
      pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
      description: >-
        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
    AvatarType:
      type: string
      enum:
        - stock
        - custom
      description: >-
        Whether the avatar is provided by Telnyx or was uploaded by the
        authenticated organization.
    AvatarListResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Avatar'
        meta:
          $ref: '#/components/schemas/AvatarListMeta'
    Avatar:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - provider
        - avatar_type
        - hosted
        - image_url
      properties:
        id:
          $ref: '#/components/schemas/AvatarId'
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Customer-facing avatar name.
          example: Customer portrait
        provider:
          type: string
          const: telnyx
          description: Avatar provider. The first release supports Telnyx avatars.
          example: telnyx
        avatar_type:
          $ref: '#/components/schemas/AvatarType'
        hosted:
          type: boolean
          const: true
          description: >-
            Indicates that avatar rendering runs on Telnyx-operated
            infrastructure.
          example: true
        image_url:
          type: string
          format: uri
          pattern: ^https://
          description: >-
            HTTPS image URL suitable for an avatar selection thumbnail. If the
            URL expires, list or retrieve the avatar again to refresh it.
          example: https://example.com/avatar.png
        image_url_expires_at:
          type: string
          format: date-time
          description: >-
            Expiration time of `image_url`. Omitted when the URL does not
            expire.
          example: '2026-10-13T15:00:00Z'
        suggested_voice_id:
          type: string
          minLength: 0
          maxLength: 255
          readOnly: true
          description: >-
            Optional recommended Telnyx text-to-speech voice for this avatar. An
            omitted field or empty string means no recommendation is available.
            Custom avatars have no suggested voice. It is informational and
            selecting the avatar does not automatically change the AI
            Assistant's configured voice.
          example: Telnyx.Ultra.db6b0ed5-d5d3-463d-ae85-518a07d3c2b4
        content_type:
          $ref: '#/components/schemas/AvatarContentType'
        size_bytes:
          type: integer
          minimum: 1
          maximum: 10485760
          description: Size of a custom avatar image in bytes.
          example: 248512
        width_px:
          type: integer
          minimum: 256
          maximum: 8192
          description: Decoded width of a custom avatar image.
          example: 1920
        height_px:
          type: integer
          minimum: 256
          maximum: 8192
          description: Decoded height of a custom avatar image.
          example: 1080
        created_at:
          type: string
          format: date-time
          description: Time when the custom avatar was created.
          example: '2026-10-13T14:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: Time when the custom avatar was last updated.
          example: '2026-10-13T14:00:00Z'
    AvatarListMeta:
      type: object
      required:
        - total_pages
        - total_results
        - page_number
        - page_size
      properties:
        total_pages:
          type: integer
          minimum: 0
          description: Total number of pages for the current filters.
          example: 1
        total_results:
          type: integer
          minimum: 0
          description: Total number of matching avatars.
          example: 1
        page_number:
          type: integer
          minimum: 1
          description: Current page number.
          example: 1
        page_size:
          type: integer
          minimum: 1
          maximum: 100
          description: Maximum number of avatars returned on each page.
          example: 20
    AvatarErrorResponse:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/AvatarError'
    AvatarContentType:
      type: string
      enum:
        - image/jpeg
        - image/png
        - image/webp
      description: MIME type of a custom avatar image.
    AvatarError:
      type: object
      additionalProperties: true
      required:
        - code
        - title
        - detail
        - meta
      properties:
        code:
          type: string
          description: Telnyx error code.
          example: '10015'
        title:
          type: string
          description: Short description of the error.
          example: Bad Request
        detail:
          type: string
          description: Human-readable details about the error.
          example: The request failed because it was not well-formed.
        source:
          $ref: '#/components/schemas/AvatarErrorSource'
        meta:
          $ref: '#/components/schemas/AvatarErrorMeta'
    AvatarErrorSource:
      type: object
      additionalProperties: true
      properties:
        pointer:
          type: string
          description: Location of the invalid request value.
          example: /image_file
    AvatarErrorMeta:
      type: object
      additionalProperties: true
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: Link to the Telnyx error-code documentation.
          example: https://developers.telnyx.com/docs/overview/errors/10027
  responses:
    AvatarRequestValidationErrorResponse:
      description: The request body, path parameter, or query parameter failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AvatarErrorResponse'
          example:
            errors:
              - code: '10015'
                title: Bad Request
                detail: The request contains invalid avatar parameters.
                meta:
                  url: https://developers.telnyx.com/docs/overview/errors/10015
    AvatarServiceUnavailableResponse:
      description: Avatar storage is temporarily unavailable. Retry the operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AvatarErrorResponse'
          example:
            errors:
              - code: '10037'
                title: Service unavailable
                detail: Avatar storage is temporarily unavailable. Try again.
                meta:
                  url: https://developers.telnyx.com/docs/overview/errors/10037
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````