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

# Upload Face Avatar

> Upload a portrait photo to create a face-aligned avatar image

<Note>
  **What This Does:** Validates that the image contains exactly one prominent face, automatically detects the image orientation (landscape, portrait, or square), aligns the face to the appropriate avatar profile, and stores the result. Returns a preview URL, a full-resolution image URL, and an avatar ID for use in sessions.
</Note>

### Input Methods

Supply the image using **exactly one** of the following options:

| Method        | Content-Type                                | Field          |
| ------------- | ------------------------------------------- | -------------- |
| File upload   | `multipart/form-data`                       | `file`         |
| Image URL     | `application/json` or `multipart/form-data` | `image_url`    |
| Base64 string | `application/json` or `multipart/form-data` | `image_base64` |

### Body

<ParamField body="file" type="file">
  Portrait photo to process. Accepted formats: `jpeg`, `jpg`, `png`, `gif`, `webp`. Maximum size: **10 MB**.
  The image must contain exactly one clearly visible, prominent face.
  Send as `multipart/form-data`.
</ParamField>

<ParamField body="image_url" type="string">
  Publicly accessible URL of a portrait photo. The server fetches the image directly.
  Accepted formats: `jpeg`, `jpg`, `png`, `gif`, `webp`. Maximum size: **10 MB**.
  Can be sent as JSON (`application/json`) or as a text field in `multipart/form-data`.
</ParamField>

<ParamField body="image_base64" type="string">
  Base64-encoded portrait photo. A data URI prefix (e.g. `data:image/jpeg;base64,`) is accepted but not required.
  Maximum decoded size: **10 MB**.
  Can be sent as JSON (`application/json`) or as a text field in `multipart/form-data`.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the upload and face alignment succeeded.
</ResponseField>

<ResponseField name="preview_url" type="string">
  Signed URL of the aligned avatar at 500×500 px, suitable for display in the UI.
</ResponseField>

<ResponseField name="image_url" type="string">
  Signed URL of the full-resolution aligned avatar (capped at 1200 px wide).
</ResponseField>

<ResponseField name="avatar_id" type="string">
  The avatar ID (format: `avat_<ULID>`). Use this as the `avatar_id` when calling [Preview Avatar](/api-reference/endpoints/preview-avatar) or as the `avatar_image_url` in session and agent payloads.
</ResponseField>

<ResponseExample>
  ```json 201 - Success theme={null}
  {
    "success": true,
    "preview_url": "https://cdn.agenthuman.com/avatars/avat_01KMZHXFPBVCXA5ATK85HCP8G1/preview",
    "image_url": "https://cdn.agenthuman.com/avatars/avat_01KMZHXFPBVCXA5ATK85HCP8G1/image",
    "avatar_id": "avat_01KMZHXFPBVCXA5ATK85HCP8G1"
  }
  ```

  ```json 400 - No Image Provided theme={null}
  {
    "success": false,
    "error": {
      "message": "No image provided",
      "suggestion": "Supply an image via: file upload (\"file\" field in multipart/form-data), URL (\"image_url\"), or base64 string (\"image_base64\")"
    }
  }
  ```

  ```json 400 - URL Fetch Failed theme={null}
  {
    "success": false,
    "error": {
      "message": "Failed to fetch image from URL (HTTP 403)",
      "suggestion": "Check that the URL is publicly accessible"
    }
  }
  ```

  ```json 400 - No Face Detected theme={null}
  {
    "success": false,
    "error": {
      "message": "No face detected in the image",
      "suggestion": "Upload a clear portrait photo with one visible face"
    }
  }
  ```

  ```json 400 - Multiple Faces theme={null}
  {
    "success": false,
    "error": {
      "message": "Multiple faces detected",
      "suggestion": "Upload a photo with only one person"
    }
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "success": false,
    "error": {
      "message": "Unauthorized"
    }
  }
  ```
</ResponseExample>