> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boson.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload an avatar

> Upload a face image to use as an avatar. Send it inline: a file in `multipart/form-data`, or base64 or a `data:` URI in JSON; URLs are not accepted. The image (PNG, JPEG or WebP, up to 10 MB, at least 256 px on each edge) is rotated upright by its EXIF orientation, converted to RGB and scaled down if an edge is over 2048 px, then checked before it is stored. Uploading an image your account already has returns the existing avatar. Use the returned `avatar_id` in `POST /v1/avatar/sessions`.



## OpenAPI

````yaml /openapi.json post /v1/avatars
openapi: 3.0.3
info:
  title: Boson AI API
  description: REST API for Boson AI audio models.
  version: 1.0.0
  license:
    name: Proprietary
servers:
  - url: https://api.boson.ai
security:
  - bearerAuth: []
paths:
  /v1/avatars:
    post:
      tags:
        - Avatar Realtime
      summary: Upload an avatar
      description: >-
        Upload a face image to use as an avatar. Send it inline: a file in
        `multipart/form-data`, or base64 or a `data:` URI in JSON; URLs are not
        accepted. The image (PNG, JPEG or WebP, up to 10 MB, at least 256 px on
        each edge) is rotated upright by its EXIF orientation, converted to RGB
        and scaled down if an edge is over 2048 px, then checked before it is
        stored. Uploading an image your account already has returns the existing
        avatar. Use the returned `avatar_id` in `POST /v1/avatar/sessions`.
      operationId: uploadAvatar
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAvatarRequest'
          multipart/form-data:
            schema:
              type: object
              required:
                - image
              properties:
                image:
                  type: string
                  format: binary
                  description: 'The image file: PNG, JPEG or WebP, up to 10 MB.'
                name:
                  type: string
                  maxLength: 256
                  description: A name for the avatar.
      responses:
        '200':
          description: The uploaded (or existing) avatar.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Avatar'
        '400':
          description: >-
            Missing or unreadable image (`missing_required_field`,
            `invalid_field_value`, `invalid_image`, `invalid_image_format`,
            `image_too_small`, `image_too_large`), or the image was refused by
            the content check (`content_policy_violation`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Your account already has the maximum number of avatars
            (`quota_exceeded`). Delete one to add another.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: The image is larger than 10 MB (`payload_too_large`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Temporarily unavailable (`service_unavailable`); retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CreateAvatarRequest:
      type: object
      required:
        - image
      additionalProperties: false
      properties:
        image:
          type: string
          description: >-
            The image as base64 or a `data:` URI: PNG, JPEG or WebP, up to 10
            MB. URLs are not accepted.
        name:
          type: string
          nullable: true
          maxLength: 256
          description: A name for the avatar.
    Avatar:
      type: object
      properties:
        avatar_id:
          type: string
          description: Pass this as `avatar_id` when creating a session.
          example: builtin_claire_v1
        object:
          type: string
          enum:
            - avatar
          default: avatar
        name:
          type: string
          example: Claire
        width:
          type: integer
          description: Reference image width in pixels.
        height:
          type: integer
          description: Reference image height in pixels.
        is_public:
          type: boolean
          description: >-
            `true` for a Boson preset, `false` for one of your account's
            avatars.
        created_at:
          type: string
          format: date-time
          nullable: true
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Human-readable error message.
            type:
              type: string
              description: Error category.
            code:
              type: string
              nullable: true
              description: Machine-readable cause within `type`.
            param:
              type: string
              nullable: true
              description: The offending parameter, if any.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your Boson API key, sent as `Authorization: Bearer $BOSON_API_KEY`.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.