---
title: "Create a custom avatar"
method: POST
path: "/ai/avatars"
tags: ["Avatars"]
---

# Create a custom avatar

`POST /ai/avatars`

## Request

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

Uploads an image, validates its file type, size, safe decoding, and resolution, stores it in Telnyx-managed private storage, and creates an avatar owned by the authenticated organization. Creating an avatar does not update an AI Assistant; use the returned ID separately wherever the avatar is consumed. The avatar image is stored independently from the rendering model and background, which are selected where the avatar is consumed. Supported image types are JPEG, PNG, and WebP. Images may be up to 10 MiB, must be between 256 and 8192 pixels on each side, and may contain at most 40 megapixels. Each organization may have up to 20 custom avatars. For best results, use a 16:9 landscape image, preferably 1920 by 1080 pixels and at least 1280 by 720 pixels. Show one centered, front-facing person from the shoulders up, keep the full head and hair visible with space around it, and use a sharp, evenly lit image with unobstructed eyes and mouth. Use a transparent PNG or WebP when the avatar will be combined with a selectable background. These composition recommendations are not enforced in the first release; the first release does not validate the number of faces, pose, or image content.

## Request body `multipart/form-data`

- CreateAvatarRequest
  - `image_file` string, binary, required: JPEG, PNG, or WebP image file. The maximum file size is 10 MiB.
  - `name` string, required: Customer-facing name of the custom avatar.

## Response `201`

The custom avatar was validated, stored, and created.

- 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 request body, path parameter, or query parameter failed validation.
- `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`: 1 breaking, 3 info
  - the `data/id` response's property type changed from no type to `string` for status `201`
  - added the optional property `data/suggested_voice_id` to the response with the `201` status
  - removed `subschema #1: Stock avatar ID, subschema #2: Custom avatar ID` from the `data/id` response property `oneOf` list for the response status `201`
  - the `data/id` response's property pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$` was added for the status `201`
- **2026-10-15** `da303e40b51e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/ai/avatars/post.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)