Atmee.aiDocs
APIAPI referenceAvatars

Replace the avatar's portrait

PUT
/v1/avatars/{avatarId}/appearance

One image (jpg, png or webp, <= 10 MB) as the file part. A good portrait is front-facing, head and shoulders with some margin around the head (a face that fills the frame cannot be animated), the face at least about a third of the frame, in even light, with the lips slightly parted as if about to speak: a v2 avatar animates its first moments from the portrait itself, so a closed mouth usually makes the first second of speech fail (the lips stay still). The build refuses a clearly bad portrait at the appearance stage with a portrait_* reason in userFeedback (no face, face too small, lips closed). Or, on an instance that keeps uploads (where POST /v1/uploads answers), application/json: {"image": "<https URL | upload:<uploadId>>"}, the portrait by URL (downloaded like a JSON create's) or by a portrait upload from POST /v1/uploads, consumed when the replacement succeeds. Re-runs only the build stages that depend on this part; poll GET /v1/avatars/{avatarId} for progress. Requires avatars:write. A draft is given its portrait this way; on v2 it captures the first candidate once the voice is there too.

Authorization

headerX-Api-Key<token>

Secret embed API key (sk_atmee_...; keys minted before 2026-09 carry sk_live_...), held by the customer's own backend and never sent to a browser. Format: X-Api-Key: sk_atmee_....

Path Parameters

avatarId*string
Formatuuid

Request Body

  1. body
file*file
Formatbinary

Response Body

Accepted; the affected build stages re-run.

application/json
  1. response
avatarId*string
Formatuuid
status*"building"
Value in"building"
Example Request
curl -X PUT 'https://api.atmanity.us/v1/avatars/497f6eca-6276-4993-bfeb-53cbbbba6f08/appearance' \  -H 'Content-Type: application/json' \  -d '{  "image": "string"}'
Example Response
{  "avatarId": "ac572b6e-802b-4b9e-a602-0786d4441e67",  "status": "building"}
Replace the avatar's portrait — Atmee Docs