> ## 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. # Create a custom avatar > 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. ## OpenAPI ````yaml /openapi/source/external/inference/inference-embedding.json post /ai/avatars openapi: 3.1.0 info: version: 2.0.0 title: Telnyx API x-latency-category: responsive x-endpoint-cost: light description: SIP trunking, SMS, MMS, Call Control and Telephony Data Services. contact: email: support@telnyx.com servers: - url: https://api.telnyx.com/v2 description: Version 2.0.0 of the Telnyx API security: - bearerAuth: [] tags: - name: Chat description: Generate text with LLMs - name: Assistants description: Configure AI assistant specifications - name: Avatars description: Create and manage real-time AI avatars - name: Conversations description: Manage historical AI assistant conversations - name: File-based Text-to-Speech description: Turn audio into text or text into audio. - name: Embeddings description: Embed documents and perform text searches - name: Clusters description: Identify common themes and patterns in your embedded documents - name: Fine Tuning description: Customize LLMs for your unique needs - name: OpenAI Embeddings description: >- OpenAI-compatible embeddings endpoints for generating vector representations of text paths: /ai/avatars: post: tags: - Avatars summary: Create a custom avatar description: >- 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. operationId: create_avatar_public_avatars_post requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/CreateAvatarRequest' example: image_file: string($binary) name: Customer portrait responses: '201': description: The custom avatar was validated, stored, and created. content: application/json: schema: $ref: '#/components/schemas/AvatarResponse' example: data: id: avatar_0123456789abcdef0123456789abcdef name: Customer portrait provider: telnyx avatar_type: custom hosted: true image_url: https://example.com/avatar.png image_url_expires_at: '2026-10-13T15:00:00Z' content_type: image/png size_bytes: 248512 width_px: 1920 height_px: 1080 created_at: '2026-10-13T14:00:00Z' updated_at: '2026-10-13T14:00:00Z' '400': $ref: '#/components/responses/AvatarRequestValidationErrorResponse' '422': $ref: '#/components/responses/AvatarValidationErrorResponse' '503': $ref: '#/components/responses/AvatarServiceUnavailableResponse' x-codeSamples: - lang: JavaScript source: |- import Telnyx from 'telnyx'; const client = new Telnyx({ apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted }); const Avatar = await client.ai.avatars.create(); console.log(Avatar.data); - lang: Python source: | import os from telnyx import Telnyx client = Telnyx( api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted ) avatar = client.ai.avatars.create() print(avatar.data) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tavatar, err := client.AI.Avatars.New(\n\t\tcontext.TODO(),\n\t\ttelnyx.AIAvatarNewParams{\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", avatar.Data)\n}\n" - lang: Java source: |- package com.telnyx.sdk.example; import com.telnyx.sdk.client.TelnyxClient; import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient; import com.telnyx.sdk.models.ai.avatars.AvatarCreateParams; public final class Main { private Main() {} public static void main(String[] args) { TelnyxClient client = TelnyxOkHttpClient.fromEnv(); AvatarCreateParams params = AvatarCreateParams.builder() .build(); var response = client.ai().avatars().create(params); } } - lang: Ruby source: |- require "telnyx" telnyx = Telnyx::Client.new(api_key: "My API Key") avatar = telnyx.ai.avatars.create puts(avatar) - lang: PHP source: >- ai->avatars->create(); var_dump($avatar); } catch (APIException $e) { echo $e->getMessage(); } - lang: CLI source: |- telnyx ai:avatars create \ --api-key 'My API Key' components: schemas: CreateAvatarRequest: type: object additionalProperties: false required: - image_file - name properties: image_file: type: string format: binary description: JPEG, PNG, or WebP image file. The maximum file size is 10 MiB. name: type: string minLength: 1 maxLength: 255 description: Customer-facing name of the custom avatar. example: Customer portrait AvatarResponse: type: object additionalProperties: false required: - data properties: data: $ref: '#/components/schemas/Avatar' Avatar: type: object additionalProperties: false required: - id - name - provider - avatar_type - hosted - image_url properties: id: $ref: '#/components/schemas/AvatarId' name: type: string minLength: 1 maxLength: 255 description: Customer-facing avatar name. example: Customer portrait provider: type: string const: telnyx description: Avatar provider. The first release supports Telnyx avatars. example: telnyx avatar_type: $ref: '#/components/schemas/AvatarType' hosted: type: boolean const: true description: >- Indicates that avatar rendering runs on Telnyx-operated infrastructure. example: true image_url: type: string format: uri pattern: ^https:// description: >- HTTPS image URL suitable for an avatar selection thumbnail. If the URL expires, list or retrieve the avatar again to refresh it. example: https://example.com/avatar.png image_url_expires_at: type: string format: date-time description: >- Expiration time of `image_url`. Omitted when the URL does not expire. example: '2026-10-13T15:00:00Z' content_type: $ref: '#/components/schemas/AvatarContentType' size_bytes: type: integer minimum: 1 maximum: 10485760 description: Size of a custom avatar image in bytes. example: 248512 width_px: type: integer minimum: 256 maximum: 8192 description: Decoded width of a custom avatar image. example: 1920 height_px: type: integer minimum: 256 maximum: 8192 description: Decoded height of a custom avatar image. example: 1080 created_at: type: string format: date-time description: Time when the custom avatar was created. example: '2026-10-13T14:00:00Z' updated_at: type: string format: date-time description: Time when the custom avatar was last updated. example: '2026-10-13T14:00:00Z' AvatarErrorResponse: type: object required: - errors properties: errors: type: array minItems: 1 items: $ref: '#/components/schemas/AvatarError' AvatarId: oneOf: - title: Stock avatar ID type: string enum: - elena - ben - jordan - lin - avery - raphael - title: Custom avatar ID type: string pattern: ^avatar_[a-z0-9][a-z0-9._:-]{0,120}$ minLength: 8 maxLength: 128 description: >- Stable identifier of a Telnyx stock avatar or an organization-owned custom avatar. Custom avatar IDs are returned by the Avatars API and use the `avatar_` prefix. example: avatar_0123456789abcdef0123456789abcdef AvatarType: type: string enum: - stock - custom description: >- Whether the avatar is provided by Telnyx or was uploaded by the authenticated organization. AvatarContentType: type: string enum: - image/jpeg - image/png - image/webp description: MIME type of a custom avatar image. AvatarError: type: object additionalProperties: true required: - code - title - detail - meta properties: code: type: string description: Telnyx error code. example: '10015' title: type: string description: Short description of the error. example: Bad Request detail: type: string description: Human-readable details about the error. example: The request failed because it was not well-formed. source: $ref: '#/components/schemas/AvatarErrorSource' meta: $ref: '#/components/schemas/AvatarErrorMeta' AvatarErrorSource: type: object additionalProperties: true properties: pointer: type: string description: Location of the invalid request value. example: /image_file AvatarErrorMeta: type: object additionalProperties: true required: - url properties: url: type: string format: uri description: Link to the Telnyx error-code documentation. example: https://developers.telnyx.com/docs/overview/errors/10027 responses: AvatarRequestValidationErrorResponse: description: The request body, path parameter, or query parameter failed validation. content: application/json: schema: $ref: '#/components/schemas/AvatarErrorResponse' example: errors: - code: '10015' title: Bad Request detail: The request contains invalid avatar parameters. meta: url: https://developers.telnyx.com/docs/overview/errors/10015 AvatarValidationErrorResponse: description: >- The request, uploaded image, or organization quota failed validation. Uploaded images must not exceed 10 MiB. content: application/json: schema: $ref: '#/components/schemas/AvatarErrorResponse' example: errors: - code: '10027' title: Unprocessable Entity detail: The image must be between 256 and 8192 pixels on each side. meta: url: https://developers.telnyx.com/docs/overview/errors/10027 AvatarServiceUnavailableResponse: description: Avatar storage is temporarily unavailable. Retry the operation. content: application/json: schema: $ref: '#/components/schemas/AvatarErrorResponse' example: errors: - code: '10037' title: Service unavailable detail: Avatar storage is temporarily unavailable. Try again. meta: url: https://developers.telnyx.com/docs/overview/errors/10037 securitySchemes: bearerAuth: type: http scheme: bearer ````