---
title: "Update a custom avatar"
method: PATCH
path: "/ai/avatars/{avatar_id}"
tags: ["Avatars"]
---

# Update a custom avatar

`PATCH /ai/avatars/{avatar_id}`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/ai/avatars/{avatar_id}`
- Auth: HTTP bearer

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.

## Path parameters

- `avatar_id` string, required: 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.

## Request body

- UpdateAvatarRequest
  - `name` string, required: New customer-facing name of the custom avatar.

## Response `200`

The custom avatar was updated.

- AvatarResponse
  - `data` Avatar, required
    - `id` string, required: 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.
    - `name` string, required: Customer-facing avatar name.
    - `provider` 'telnyx', required: Avatar provider. The first release supports Telnyx avatars.
    - `avatar_type` 'stock' | 'custom', required: Whether the avatar is provided by Telnyx or was uploaded by the authenticated organization.
    - `hosted` true, required: Indicates that avatar rendering runs on Telnyx-operated infrastructure.
    - `image_url` string, uri, required: HTTPS image URL suitable for an avatar selection thumbnail. If the URL expires, list or retrieve the avatar again to refresh it.
    - `image_url_expires_at` string, date-time: Expiration time of `image_url`. Omitted when the URL does not expire.
    - `suggested_voice_id` string: 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.
    - `content_type` 'image/jpeg' | 'image/png' | 'image/webp': MIME type of a custom avatar image.
    - `size_bytes` integer: Size of a custom avatar image in bytes.
    - `width_px` integer: Decoded width of a custom avatar image.
    - `height_px` integer: Decoded height of a custom avatar image.
    - `created_at` string, date-time: Time when the custom avatar was created.
    - `updated_at` string, date-time: Time when the custom avatar was last updated.

## Other responses

- `400`: The avatar identifier is malformed, or the operation targets a Telnyx stock avatar, which is read-only.
- `404`: The avatar does not exist or is not available to the authenticated organization.
- `422`: The request, uploaded image, or organization quota failed validation. Uploaded images must not exceed 10 MiB.
- `503`: Avatar storage is temporarily unavailable. Retry the operation.

## Changes

> 152 revisions in range; 1 not diffed.

- **2026-10-15** `e33b4a326dda`: 3 breaking, 1 warning, 4 info
  - for the `path` request parameter `avatar_id`, the minLength was increased from `0` to `1`
  - added the pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$` to the `path` request parameter `avatar_id`
  - the `data/id` response's property type changed from no type to `string` for status `200`
  - for the `path` request parameter `avatar_id`, the maxLength was set to `128`
  - …4 more
- **2026-10-15** `da303e40b51e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/ai/avatars/:avatar_id/patch.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/f82938f53ff4?raw)