Replace the avatar's portrait
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.
X-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_....
avatarId*stringuuid- body
file*filebinaryAccepted; the affected build stages re-run.
application/json- response
avatarId*stringuuidstatus*"building""building"curl -X PUT 'https://api.atmanity.us/v1/avatars/497f6eca-6276-4993-bfeb-53cbbbba6f08/appearance' \ -H 'Content-Type: application/json' \ -d '{ "image": "string"}'{ "avatarId": "ac572b6e-802b-4b9e-a602-0786d4441e67", "status": "building"}
