# Replace the avatar's portrait

URL: https://www.atmee.ai/docs/v2/api/reference/avatars/replaceAvatarAppearance

`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.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `avatarId` | path | yes |  |

## Request body

- `multipart/form-data`: object
- `application/json`: `AvatarAppearanceJsonRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `image` | `AssetRefString` | yes |  |

## Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Accepted; the affected build stages re-run. | `AvatarPartResponse` |
| `400` | invalid_upload (also a JSON body on an instance without uploads, which takes multipart only) \| invalid_manifest \| invalid_url \| fetch_failed \| upload_not_found \| upload_kind_mismatch | none |
| `401` | Missing or invalid API key -- or a user token that is invalid, anonymous, or of a user who may act for no account (invalid_login) | none |
| `403` | insufficient_scope \| avatar_not_allowed \| account_not_allowed (a user token whose X-Account-Id names an account the user may not act for) \| v2_access_required (engine v2 is invite-only and this account has not been let in yet) | none |
| `404` | avatar_not_found | none |
| `409` | upload_not_ready \| upload_consumed \| upload_expired \| upload_in_use \| account_ambiguous (a user token of several accounts without X-Account-Id) | none |
| `413` | Upload exceeds the size limit | none |

## `200` response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `avatarId` | string | yes |  |
| `status` | string (`building`) | yes |  |