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

# Avatars

> Upload and manage custom avatars, assign stock or custom avatars to AI Assistants, and start avatar conversations through the Portal or over WebRTC.

**Beta:** AI Assistant avatars are in beta.

Add an avatar to an existing assistant with `avatar_settings`. The assistant keeps its instructions, voice, tools and transcription configuration. Each WebRTC conversation opts into the saved avatar by offering a video track that can receive it; saving an avatar does not turn every conversation into a video session.

## Voice compatibility

Telnyx avatars support **Telnyx TTS** and **GPT Live speech-to-speech**. For GPT Live, pair a supported GPT Live model with an `OpenAILive.` voice and an OpenAI integration secret; see [GPT Live voice assistants](https://developers.telnyx.com/docs/inference/ai-assistants/gpt-live.md).

When switching an existing assistant to GPT Live, update `model` and `voice_settings.voice` together. For example, pair `openai/gpt-live-1` with `OpenAILive.marin`. Keep `avatar_settings.provider` set to `telnyx` and choose a stock or organization-owned custom avatar. The avatar rendering model remains separate from the GPT Live speaking model.

ElevenLabs and other third-party TTS providers are not supported with Telnyx avatars, including Portal avatar tests.

Configure the voice through `voice_settings`; `avatar_settings.provider` selects the avatar provider, not the TTS provider.

## Pricing

During October 2026, Telnyx avatars are included in AI Assistant call pricing at no additional charge. Starting November 1, 2026, avatar usage costs **\$0.08 USD per minute**, in addition to standard AI Assistant call charges.

The same pricing applies to avatar tests in the Portal.

## Find available stock avatars

Use [List avatars](https://developers.telnyx.com/api-reference/avatars/list-avatars.md) with `filter[avatar_type]=stock` to discover the current stock catalog:

```bash theme={null}
curl --fail-with-body --get https://api.telnyx.com/v2/ai/avatars \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  --data-urlencode 'filter[avatar_type]=stock' \
  --data-urlencode 'page[number]=1' \
  --data-urlencode 'page[size]=100'
```

Each entry in `data` includes its `id`, `name`, `avatar_type`, and preview `image_url`. Follow `meta.total_pages` to load all available stock avatars, and use the chosen entry's `id` as `avatar_settings.avatar_id`. Discover available IDs through the API instead of maintaining a fixed list of avatar names or IDs in your application.

## Create and use a custom avatar

Stock avatars are provided by Telnyx and are read-only. Custom avatars belong to the organization that uploads them and can be reused by its assistants. Creating an avatar stores the image; it does not change an assistant or select a rendering model, background, or voice.

### Prepare the image

[Create a custom avatar](https://developers.telnyx.com/api-reference/avatars/create-a-custom-avatar.md) enforces these upload requirements:

| Property | Requirement |
| - | - |
| File format | JPEG, PNG, or WebP |
| File size | Nonempty, up to 10 MiB |
| Dimensions | 256–8192 pixels on each side |
| Total resolution | At most 40 megapixels |
| Name | 1–255 characters |

For better rendering results:

* Use a 16:9 landscape image, preferably 1920 × 1080 pixels and at least 1280 × 720 pixels.
* Show one centered, front-facing person from the shoulders up. Leave space around the full head and hair.
* Use a sharp, evenly lit image with unobstructed eyes and mouth. Avoid profile views, tight head crops, and group photos.
* Use a transparent PNG or WebP when combining the avatar with a selectable background.

The composition recommendations are separate from the enforced upload requirements. An accepted image is not a guarantee of good animation: the initial release does not validate face count, pose, or image content. Test the avatar in a conversation before using it in an integration.

### Create and assign through the API

Upload the image and name as `multipart/form-data` to `POST /v2/ai/avatars`. Use `image_file` for the file field. Let cURL set the multipart boundary.

```bash theme={null}
curl --fail-with-body https://api.telnyx.com/v2/ai/avatars \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -F "name=Support avatar" \
  -F "image_file=@./support-avatar.png;type=image/png"
```

The successful response contains the new avatar in `data`. Copy `data.id`; use the ID, not `data.image_url`, in the assistant configuration. Image URLs are for previews and may expire.

Send the following body to [Update an assistant](https://developers.telnyx.com/api-reference/assistants/update-an-assistant.md), `POST /v2/ai/assistants/{assistant_id}`, replacing the example `avatar_id` with the returned ID:

```json theme={null}
{
  "avatar_settings": {
    "provider": "telnyx",
    "model": "foxtrot-1",
    "avatar_id": "avatar_0123456789abcdef0123456789abcdef",
    "background_id": "studio"
  }
}
```

Use an assistant in the same organization as the custom avatar. Select the rendering model and background on the assistant, and configure a compatible voice separately. Start an [avatar conversation](#start-an-avatar-conversation) to use the saved avatar.

### Create and assign in the Portal

1. Open **AI Suite → Avatars (Beta)** in the sidebar, below **Tools** and above **Missions**.
2. In **Custom**, choose **Create avatar**, enter a name, and drop or choose an image. Submit with **Create avatar**.
3. Open the assistant's **Avatar** tab, enable avatars, and select the custom avatar. Choose the rendering model and background, then save the assistant.
4. Use **Call your assistant → With avatar (BETA)** to check the result. The **Stock** tab on the Avatars page is a read-only catalog.

### List and manage avatars

[List avatars](https://developers.telnyx.com/api-reference/avatars/list-avatars.md), `GET /v2/ai/avatars`, returns stock avatars and custom avatars belonging to the authenticated organization. To list only custom avatars:

```bash theme={null}
curl --fail-with-body --get https://api.telnyx.com/v2/ai/avatars \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  --data-urlencode 'filter[avatar_type]=custom' \
  --data-urlencode 'page[number]=1' \
  --data-urlencode 'page[size]=20'
```

Follow `meta.total_pages` when loading the full catalog. Filter with `filter[avatar_type]=stock` for stock avatars. Use `image_url` to display previews; list again or [retrieve the avatar](https://developers.telnyx.com/api-reference/avatars/get-an-avatar.md) to refresh an expired URL. Store the avatar ID as the durable reference. Stock avatars may return a recommended Telnyx voice in `suggested_voice_id`. An omitted field or empty string means no recommendation is available; custom avatars have no suggested voice.

[Update a custom avatar](https://developers.telnyx.com/api-reference/avatars/update-a-custom-avatar.md), `PATCH /v2/ai/avatars/{avatar_id}`, changes its name:

```json theme={null}
{
  "name": "Reception avatar"
}
```

Renaming preserves the ID and image, so existing assistant references continue to use the same avatar. In the Portal, use **Rename** on the Custom list.

A per-organization custom-avatar quota applies. When the quota is reached, the create request returns an error and existing avatars remain available. Stock avatars cannot be renamed. To replace an image, create a new custom avatar and update the assistants that should use it. The Avatars API currently has no delete operation; removing an avatar from an assistant does not delete the custom asset or free a quota slot.

## Configure an avatar

Send the following request body to [Update an assistant](https://developers.telnyx.com/api-reference/assistants/update-an-assistant.md), `POST /v2/ai/assistants/{assistant_id}`. The same `avatar_settings` object is accepted when creating an assistant.

`avatar_settings.model` is required. It selects the avatar rendering model, independently of the assistant's top-level LLM `model` and `voice_settings`.

```json theme={null}
{
  "avatar_settings": {
    "provider": "telnyx",
    "model": "foxtrot-1",
    "avatar_id": "elena",
    "background_id": "studio"
  }
}
```

| Setting | Supported values |
| - | - |
| `model` | `foxtrot-1` |
| `avatar_id` | A stock or organization-owned custom avatar ID returned by [List avatars](https://developers.telnyx.com/api-reference/avatars/list-avatars.md) |
| `background_id` | See `avatar_settings.background_id` in [Update an assistant](https://developers.telnyx.com/api-reference/assistants/update-an-assistant.md) for supported values. |

The Portal defaults new avatar configurations to `studio`.

The avatar's appearance and voice are configured separately. Select the voice through `voice_settings`. The Portal may offer a suggested Telnyx Ultra voice for stock avatars. Custom avatars have no suggested voice; selecting an avatar alone does not change the voice.

## Start an avatar conversation

Avatar conversations run over [WebRTC](https://developers.telnyx.com/docs/inference/ai-assistants/webrtc-conversations.md). The browser offers a video m-line that can receive VP8 alongside its microphone; the avatar's synchronized video and voice arrive on the call's video and audio tracks, and conversation events on the `oai-events` data channel.

1. Configure the assistant's `avatar_settings` and a [compatible voice](#voice-compatibility).
2. [Create a WebRTC call](https://developers.telnyx.com/docs/inference/ai-assistants/webrtc-conversations.md#create-the-offer) whose offer includes a `recvonly` (or `sendrecv`, to also send the camera) VP8 video transceiver.
3. Play the received video and audio tracks. The data channel reports `avatar.updated` with `starting`, then `active`.

If the avatar cannot start or stops during the call, `avatar.updated` reports `unavailable` and the conversation continues with the assistant's voice on the same audio track. See [Show an avatar](https://developers.telnyx.com/docs/inference/ai-assistants/webrtc-conversations.md#show-an-avatar) for every state.

## Test and choose a conversation mode

For an assistant with saved avatar settings, **Call your assistant** in the Portal offers **With avatar (BETA)** or **Without avatar**. The avatar option is selected by default. The voice-only option uses the existing voice call test.

For **With avatar (BETA)**, optional dynamic-variable test values apply to that conversation only. Nonempty test values override the same-named variables; blank fields leave saved defaults or webhook values in effect. Testing does not update the assistant configuration.

Avatar tests follow the [avatar pricing](#pricing) above. Phone-call tools such as transfer and DTMF are not supported in avatar conversations. PSTN calls remain voice-only. In a WebRTC client, omit the video m-line, or create the call with `?avatar=false`, to start a conversation without the avatar while keeping the saved avatar configuration.

For a local demo, enable **Record locally** in the call setup controls. After the call, preview and download the recording in the same browser tab before closing or refreshing it. This local recording is separate from the uploaded avatar image.

## Add camera input with vision

Avatar video shows the assistant; the `vision` tool lets the assistant inspect images supplied by the user. Attach the tool and configure either a vision-capable base model or an enabled vision-capable delegation model. For S2S assistants, the delegation model can inspect the frames while the speaking model handles the conversation.

See [Vision model support](https://developers.telnyx.com/docs/inference/ai-assistants/vision.md#model-support) for configuration requirements. Over WebRTC, [send the camera track](https://developers.telnyx.com/docs/inference/ai-assistants/webrtc-conversations.md#send-the-camera) on the same video m-line as the avatar; receiving an avatar alone does not provide camera input.

## Remove the saved avatar

Update the assistant with:

```json theme={null}
{
  "avatar_settings": null
}
```

This removes the assistant's avatar configuration. Omitting `avatar_settings` from an update leaves the current configuration unchanged.