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 '{}'
{
  "success": true,
  "preview_url": "https://cdn.agenthuman.com/avatars/avat_01J8ZK4R2N5M6P7Q8W4T/preview",
  "image_url": "https://cdn.agenthuman.com/avatars/avat_01J8ZK4R2N5M6P7Q8W4T/image",
  "avatar_id": "avat_01J8ZK4R2N5M6P7Q8W4T"
}
What This Does: Validates that the uploaded photo 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.

​
Body

​
file
file
required
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.

​
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_01J8ZK4R2N5M6P7Q8W4T/preview",
  "image_url": "https://cdn.agenthuman.com/avatars/avat_01J8ZK4R2N5M6P7Q8W4T/image",
  "avatar_id": "avat_01J8ZK4R2N5M6P7Q8W4T"
}