Avatars

Create a custom avatar

Changed on

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.

post/ai/avatars

Request

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

Request body multipart/form-data

image_filestring binary required

JPEG, PNG, or WebP image file. The maximum file size is 10 MiB.

namestring required

Customer-facing name of the custom avatar.

Example request

{
  "name": "Customer portrait"
}

Response

The custom avatar was validated, stored, and created.

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

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

    • 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