Skip to main content
POST
/
v1
/
avatars
/
upload-face
Upload Face Avatar
curl --request POST \
  --url https://api.agenthuman.com/v1/avatars/upload-face \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "image_url": "<string>",
  "image_base64": "<string>"
}
'
{
  "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"
}
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.

​
Input Methods

Supply the image using exactly one of the following options:
MethodContent-TypeField
File uploadmultipart/form-datafile
Image URLapplication/json or multipart/form-dataimage_url
Base64 stringapplication/json or multipart/form-dataimage_base64

​
Body

​
file
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.
​
image_url
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.
​
image_base64
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.

​
Response

​
success
boolean
Whether the upload and face alignment succeeded.
​
preview_url
string
Signed URL of the aligned avatar at 500×500 px, suitable for display in the UI.
​
image_url
string
Signed URL of the full-resolution aligned avatar (capped at 1200 px wide).
​
avatar_id
string
The avatar ID (format: avat_<ULID>). Use this as the avatar_id when calling Preview Avatar or as the avatar_image_url in session and agent payloads.
{
  "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"
}