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

# Update a custom avatar

> Updates the customer-facing name of a custom avatar owned by the authenticated organization. Stock avatars cannot be modified. To replace the image, create a new custom avatar so existing references keep their original content.



## OpenAPI

````yaml /openapi/source/external/inference/inference-embedding.json patch /ai/avatars/{avatar_id}
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/{avatar_id}:
    patch:
      tags:
        - Avatars
      summary: Update a custom avatar
      description: >-
        Updates the customer-facing name of a custom avatar owned by the
        authenticated organization. Stock avatars cannot be modified. To replace
        the image, create a new custom avatar so existing references keep their
        original content.
      operationId: update_avatar_public_avatars__avatar_id__patch
      parameters:
        - $ref: '#/components/parameters/AvatarId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAvatarRequest'
            example:
              name: Updated portrait
      responses:
        '200':
          description: The custom avatar was updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvatarResponse'
        '400':
          $ref: '#/components/responses/AvatarMutationBadRequestResponse'
        '404':
          $ref: '#/components/responses/AvatarNotFoundResponse'
        '422':
          $ref: '#/components/responses/AvatarValidationErrorResponse'
        '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
            });

            const Avatar = await client.ai.avatars.update('avatar_id', {
              name: 'Updated portrait',
            });

            console.log(Avatar.data);
        - 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
            )
            avatar = client.ai.avatars.update(
                avatar_id="avatar_id",
                name="Updated portrait",
            )
            print(avatar.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\tavatar, err := client.AI.Avatars.Update(\n\t\tcontext.TODO(),\n\t\t\"avatar_id\",\n\t\ttelnyx.AIAvatarUpdateParams{\n\t\t\tName: \"Updated portrait\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", avatar.Data)\n}\n"
        - lang: Java
          source: |-
            package com.telnyx.sdk.example;

            import com.telnyx.sdk.client.TelnyxClient;
            import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
            import com.telnyx.sdk.models.ai.avatars.AvatarUpdateParams;

            public final class Main {
                private Main() {}

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

                    AvatarUpdateParams params = AvatarUpdateParams.builder()
                        .name("Updated portrait")
                        .build();
                    var response = client.ai().avatars().update("avatar_id", params);
                }
            }
        - lang: Ruby
          source: >-
            require "telnyx"


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


            avatar = telnyx.ai.avatars.update("avatar_id", name: "Updated
            portrait")


            puts(avatar)
        - 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 {
              $avatar = $client->ai->avatars->update(
                'avatar_id',
                name: 'Updated portrait',
              );

              var_dump($avatar);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: CLI
          source: |-
            telnyx ai:avatars update \
              --api-key 'My API Key' \
              --avatar-id avatar_id \
              --name 'Updated portrait'
components:
  parameters:
    AvatarId:
      name: avatar_id
      in: path
      required: true
      description: >-
        Stable identifier of a Telnyx stock avatar or an organization-owned
        custom avatar.
      schema:
        $ref: '#/components/schemas/AvatarId'
  schemas:
    UpdateAvatarRequest:
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: New customer-facing name of the custom avatar.
          example: Updated portrait
    AvatarResponse:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/Avatar'
    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
    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'
    AvatarErrorResponse:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/AvatarError'
    AvatarType:
      type: string
      enum:
        - stock
        - custom
      description: >-
        Whether the avatar is provided by Telnyx or was uploaded by the
        authenticated organization.
    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:
    AvatarMutationBadRequestResponse:
      description: >-
        The avatar identifier is malformed, or the operation targets a Telnyx
        stock avatar, which is read-only.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AvatarErrorResponse'
          example:
            errors:
              - code: '10015'
                title: Bad Request
                detail: Telnyx stock avatars cannot be modified.
                meta:
                  url: https://developers.telnyx.com/docs/overview/errors/10015
    AvatarNotFoundResponse:
      description: >-
        The avatar does not exist or is not available to the authenticated
        organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AvatarErrorResponse'
          example:
            errors:
              - code: '10005'
                title: Resource not found
                detail: Avatar avatar_0123456789abcdef0123456789abcdef does not exist.
                meta:
                  url: https://developers.telnyx.com/docs/overview/errors/10005
    AvatarValidationErrorResponse:
      description: >-
        The request, uploaded image, or organization quota failed validation.
        Uploaded images must not exceed 10 MiB.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AvatarErrorResponse'
          example:
            errors:
              - code: '10027'
                title: Unprocessable Entity
                detail: The image must be between 256 and 8192 pixels on each side.
                meta:
                  url: https://developers.telnyx.com/docs/overview/errors/10027
    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

````