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.

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 with filter[avatar_type]=stock to discover the current stock catalog:

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

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, POST /v2/ai/assistants/{assistant_id}, replacing the example avatar_id with the returned ID:

{
  "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 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, GET /v2/ai/avatars, returns stock avatars and custom avatars belonging to the authenticated organization. To list only custom avatars:

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 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, PATCH /v2/ai/avatars/{avatar_id}, changes its name:

{
  "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, 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.

{
  "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
background_id	See avatar_settings.background_id in Update an assistant 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. 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.
2. Create a WebRTC call 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 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 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 for configuration requirements. Over WebRTC, send the camera track 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:

{
  "avatar_settings": null
}

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