Avatars

Get an avatar

Changed on

Returns a Telnyx stock avatar or a custom avatar owned by the authenticated organization. A custom avatar belonging to another organization is returned as not found.

get/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

Path parameters

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

Example:avatar_0123456789abcdef0123456789abcdef

Stable identifier of a Telnyx stock avatar or an organization-owned custom avatar.

Response

The avatar.

Example response

{
  "data": {
    "id": "avatar_0123456789abcdef0123456789abcdef",
    "name": "Customer portrait",
    "provider": "telnyx",
    "hosted": true,
    "image_url": "https://example.com/avatar.png",
    "image_url_expires_at": "2026-10-13T15:00:00Z",
    "suggested_voice_id": "Telnyx.Ultra.db6b0ed5-d5d3-463d-ae85-518a07d3c2b4",
    "size_bytes": 248512,
    "width_px": 1920,
    "height_px": 1080,
    "created_at": "2026-10-13T14:00:00Z",
    "updated_at": "2026-10-13T14:00:00Z"
  }
}

Changes

  • e33b4a326ddaRevision changes
    • breaking

      for the path request parameter avatar_id, the minLength was increased from 0 to 1

    • breaking

      added the pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$ to the path request parameter avatar_id

    • breaking

      the / response's property type changed from no type to string for status

    • warning

      for the path request parameter avatar_id, the maxLength was set to 128

    • info

      for the path request parameter avatar_id, the type was generalized from no type to string

    • info

      added the optional property / to the response with the status

    • info

      removed subschema #1: Stock avatar ID subschema #2: Custom avatar ID from the / response property oneOf list for the response status

    • info

      the / response's property pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$ was added for the status

  • da303e40b51eRevision changes
    • info

      endpoint added