# Update name, description, visibility, language or preview message

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

`PATCH /v1/avatars/{avatarId}`

Persona edits (whoPrompt, whatPrompt, greeting, self-introduction,
guardrails, habits, aliases, name) rebuild the persona in the
background. A v1 avatar is briefly not ready; a v2 avatar stays
`ready` and keeps serving its current config while `stages.persona`
shows the rebuild, and serves the new persona a few seconds after
that stage completes. A persona edit captures nothing, so
`rebuilding` (which is about candidates) does not change. Every
persona edit is moderated again, on both engines: a `clean` avatar
reads `moderationState: unmoderated` until the new check passes. Meanwhile a v2
rebuild already under way waits: its candidates stay queued and
are not captured until the check passes; the serving candidate
keeps serving.
On v2, a changed `previewMessage`, portrait or voice captures new
candidates.

Send only the fields to change: an absent or `null` field is left
unchanged. To remove a value, send it empty: `""` for description,
greeting, preferredAlias and spokenName, `[]` for guardrails and
knownAliases, `{}` for conversationalHabits, and `""` for
`previewMessage` to go back to the default sentence. whoPrompt,
whatPrompt and selfIntroduction cannot be emptied: `""` fails the
schema (`422`), and so does blank selfIntroduction text under 51
characters; other blank text is `400 invalid_manifest`.

`personality` and `scenario` are older names of `whoPrompt` and
`whatPrompt` and still accepted, nested in `persona` or at the top
level. A field given twice (under both names, or both at the top
level and in `persona`) is `400 invalid_body`.

`previewMessage` on a v2 avatar is at most 60 Unicode code points
(`400 preview_message_too_long`); changing it captures new
candidates. Sending the current `previewMessage` again is no
rebuild, and `""` (the default sentence) rebuilds only when a custom
line was set.

`blackoutRecovery` and `runtimeSeed` change only how the next v2
sessions render: nothing is rebuilt or captured, and the serving
candidate stays. They are ignored for v1 avatars (the settings exist
only on the v2 renderer).

`resolution` (v2 only; `400 invalid_input` for a v1 avatar) changes
the frame size: it is a build input, so a new size builds a new
version (new candidates, as a new portrait does) while the serving
candidate keeps serving; the current size sent again builds nothing.

`knowledge.facts` replaces the avatar's knowledge text (at most
32,000 characters; `""` removes it), on either engine, as Creator
Studio's "Facts with context" box does: the text and its knowledge
file, which the knowledge stage processes again. Other knowledge
files stay. Nothing is captured.

`knowledge.questionnaire` replaces the answers to Creator Studio's
knowledge questionnaire, question to answer, as Studio's Knowledge
step saves them: the answers and their knowledge file, which the
knowledge stage processes again (answers equal to the current ones
change nothing). `{}` removes them. The questions are the `questions`
of `GET /v1/avatars/{avatarId}/knowledge`; another question, or a
blank answer or one over 2,000 characters, is `400 invalid_manifest`.

The share fields are what Creator Studio's "Share to community" card
edits, written as Studio writes them and with its limits, on either
engine (nothing is rebuilt): `title` (at most 100 characters),
`subtitle` (200), `description` (280), `tags` (the whole set: at
most 5 after trimming and dropping case-insensitive duplicates, each
with a letter or digit; an existing tag of the same name is reused)
and `socialLinks` (the whole set: instagram, tiktok, facebook,
twitter or youtube, each at most once, with an https URL of at most
500 characters). `""` clears title and subtitle, `[]` clears tags
and socialLinks. A field Studio's rules refuse is
`400 invalid_body` naming it. The Explore thumbnail has its own
route (`PUT /v1/avatars/{avatarId}/thumbnail`).

`visibility` follows Studio's rules: making an avatar `public` needs
a title, a tag, a subtitle, a description and a thumbnail (`409
public_requirements_missing`, with the `missing` fields), checked on
the state after the rest of the request. On an avatar already
public, only clearing one of them is refused (the same error, with
the cleared fields as `missing`); its other edits, and `public`
sent again, pass. Making it `public` or `unlisted` passes the
moderation publish gate (`409 moderation_blocked` while the avatar
is held or not yet checked, when the gate is enforced). A value
equal to the stored one is no change.

`statementType` records who the avatar depicts, as Studio's
verification dialog does; `""` resets it (null leaves it unchanged).
It cannot change while the avatar is monetized (`409
avatar_is_earning`; turn monetization off in the same request
first), and changing or resetting it clears `verified`. The identity
check that verifies a self or representative statement runs in
Creator Studio only.

`monetization.enabled` turns monetization on or off with Studio's
switch's preconditions: a verified avatar or the fictional
statement (`409 statement_required` / `identity_not_verified`), a
verified payout account (`409 payouts_not_ready`; payouts are set up
in Creator Studio, see `payouts` on `GET /v1/account`), the 30-day
eligibility (`409 monetization_eligibility_not_met`) and room under
the plan's cap (`409 monetization_limit_reached`); an avatar whose
sponsor pool holds credits needs `confirmSponsorWithdrawal: true`
(`409 sponsor_pool_not_empty`), and turning it on then withdraws the
pool to the account. Turning it off always works.

`name` and `description` are written with these fields, under the
same rules (`name` at most 100 characters once trimmed, counted in
UTF-16 units as Studio counts them; `description` at most 280).

Every field of the request is checked before anything is written.
Then the name, description, share fields, statement, monetization
and visibility are written first, in one write: a refusal of any of
them (`400 invalid_body`, `400 name_invalid` or one of the `409`s)
leaves the whole request unwritten, including the persona, preview
message, knowledge and settings, and starts no rebuild. The rest is
written after it, so a later failure (a rebuild refused with `429`,
an outage) answers an error with that first write already made;
sending the same request again writes it as no change and retries
the rest.

## Parameters

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

## Request body

- `application/json`: `AvatarUpdateRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no |  |
| `description` | string | no |  |
| `visibility` | string (`private`, `unlisted`, `public`) | no |  |
| `language` | string (`en`, `zh-TW`, `zh-CN`, `ja`, `ko`, `fr`, `vi`, `es`, `de`, `hi`, `ru`) | no |  |
| `previews` | boolean | no | Turn preview clip generation on (`true`) for an avatar created without it -- the preview stages then build and `previewUrls` appear on GET once finished -- or off (`false`) to stop rebuilding them. Omit to leave it unchanged. |
| `previewMessage` | string | no |  |
| `personality` | string | no | The main character description (who the avatar is). |
| `scenario` | string | no | What the avatar is doing with the visitor. |
| `whoPrompt` | string | no |  |
| `whatPrompt` | string | no |  |
| `greeting` | string | no |  |
| `selfIntroduction` | string | no |  |
| `guardrails` | array of string | no |  |
| `conversationalHabits` | object | no |  |
| `preferredAlias` | string | no |  |
| `spokenName` | string | no |  |
| `knownAliases` | array of string | no |  |
| `blackoutRecovery` | `BlackoutRecovery` | no | Blackout recovery of the v2 renderer. While the avatar listens, it screens each generated chunk for a fade to black (or fully black frames) and shows a healthy listening clip in place of a failed one, returning to live frames on the first healthy chunk. On by default. Send only the settings to change; an absent or null one keeps its current value (on create: its default). Ignored for v1 avatars (the setting exists only on the v2 renderer): nothing is stored and the rest of the request behaves as without it. It changes how sessions render, never the avatar's build: no candidate is captured or cancelled. A change applies from the next session. |
| `runtimeSeed` | `RuntimeSeed` | no | The v2 renderer's runtime seed: it seeds a session's noise and motion after the first chunk, so another seed gives the same avatar different movement; the serving candidate stays the same. Default 42 (the renderer default; send 42 to go back to it). Absent or null keeps the current value (on create: the default). Ignored for v1 avatars: nothing is stored and the rest of the request behaves as without it. It is no build input: nothing is captured or rebuilt, and a change applies from the next session. |
| `resolution` | `RenderResolution` | no | A frame size in pixels for the v2 renderer: width and height are each a multiple of 32 from 256 to 1024, and width x height is at most 262,144 (512 x 512); a larger frame is `400 invalid_manifest` on an avatar, `400 invalid_input` on a clip. Default 512 x 512 (square). Common shapes: square 512 x 512, portrait 384 x 672, landscape 672 x 384. A deployment offers only some sizes (512 x 512 always; `GET /v1/account` `pricing.generation.clipResolutions` lists them where clips are offered): another is `400 invalid_input` ("resolution WxH is not offered; offered: ..."). On an avatar it is a build input of v2 avatars only (`400 invalid_input` for a v1 avatar): the portrait is preprocessed at that size, so a change on PATCH builds a new version with new candidates, like a new portrait; sending the current size again builds nothing. Absent or null keeps the current size (on create: the default). |
| `title` | `AvatarShareTitle` | no | The display title on Explore (Creator Studio's share card); `""` clears it, and the card shows the preferred alias, then the name. |
| `subtitle` | `AvatarShareSubtitle` | no | The line under the title on Explore; `""` clears it. |
| `tags` | `AvatarShareTags` | no | The avatar's tags, the whole set (`[]` clears them); at most 5 once trimmed and with case-insensitive duplicates dropped. |
| `socialLinks` | `AvatarShareSocialLinks` | no | The avatar's social links, the whole set (`[]` removes them all); a platform left out has no link. |
| `statementType` | `AvatarStatementType` | no | Who the avatar depicts (the avatar's creator, someone they represent, or a fictional character); `""` resets it. |
| `monetization` | `AvatarMonetizationEdit` | no | Turn monetization on or off, as Creator Studio's switch does. |
| `persona` | object | no |  |
| `knowledge` | object | no |  |

## Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Updated; returns the detail. | `AvatarDetail` |
| `400` | Validation failure, e.g. preview_message_too_long (v2 previewMessage over 60 characters), name_invalid (a blank name, or one over 100 characters), or invalid_body for a share field Studio's rules refuse | 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` | public_requirements_missing (`missing` lists them) \| moderation_blocked \| avatar_is_earning \| statement_required \| identity_not_verified \| payouts_not_ready \| monetization_eligibility_not_met \| monetization_limit_reached \| sponsor_pool_not_empty \| account_ambiguous (a user token of several accounts without X-Account-Id) | `ProfileRefusal` |
| `422` | Request body failed schema validation (e.g. an empty whoPrompt). | none |

## `200` response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `links` | `AvatarLinks` | no | The avatar's pages on the Atmee website, ready to hand to a person: give these rather than building URLs. Absent when this deployment does not know the website's address. A private avatar's pages open only for its owner, signed in. |
| `name` | string | yes |  |
| `kind` | `AvatarKind` | yes | `conversational` avatars have a voice and a persona and can run a full Atmanity session once built. `render_only` avatars have a portrait only: they are ready immediately and render video for an external agent, but `readyToChat` stays false until a voice is added via `PUT /voice`. |
| `visibility` | string (`private`, `unlisted`, `public`) | yes |  |
| `moderationState` | string | no |  |
| `creationSource` | string | no | Set to api for avatars created through this API. |
| `status` | string (`building`, `ready`, `failed`, `moderation_hold`, `awaiting_selection`, `stalled`, `draft`) | yes | What the avatar is doing now; the set may grow (treat unknown values as `building`). - `building`: a build step is queued or running. - `ready`: the avatar serves a build and `readyToChat` is true. A v2 avatar stays `ready` while a newer version builds or waits for a pick (`rebuilding` / `selectionRequired`): it keeps chatting with the serving take until a new one is selected. - `awaiting_selection` (v2, manual selection): nothing serves yet, every take of the current version has finished and one must be selected (`selectionRequired: true`). - `failed`: a stage failed and nothing serves; `latestFailure` names the first failed stage and why. - `moderation_hold`: held for moderation review (`moderationState` on_hold, pending_review or confirmed_unsafe). Visitors -- public and unlisted links, Explore -- cannot open it. The account itself can still start sessions on it when `readyToChat` is true, as session start allows the owning account. - `stalled`: still unfinished, but the build has recorded no progress (no build step started, finished or wrote a file) for a long time: 30 minutes with nothing queued or running and a stage waiting, or 6 hours with a step -- including moderation or the final configuration, which have no stage of their own -- still queued or running. `stall` says since when and which stage. It will not finish by waiting; replace the input of that stage or contact support. - `draft`: created without its portrait or voice; `missingInputs` names what it lacks. Nothing that needs them builds until they are given (`PUT /appearance`, `PUT /voice`); it will not finish by waiting. |
| `missingInputs` | array of string | no | The inputs a `draft` still lacks; absent on every other status. |
| `engine` | `AvatarEngine` | no | Render engine. `v1` is the original renderer. `v2` is built from a bundle plus a promoted candidate; see `/candidates`. |
| `thumbnailUrl` | string | no | Presigned image (Studio's custom thumbnail, else the portrait), valid about one hour; re-GET to refresh. |
| `selectionRequired` | boolean | no | v2 only. True while a completed candidate waits to be promoted (manual mode). |
| `readyToChat` | boolean | yes | A session can be started on the avatar now (it serves a finished build). This holds during a moderation hold too, for the owning account only. |
| `stall` | `AvatarStall` | no | Present when the build has recorded no progress for a long time: with status `stalled` (see `status`), or on a `ready` or held avatar one of whose stages has been queued or running for 6 hours with no progress -- the avatar keeps serving and its status is unchanged. Never on a `failed` or `awaiting_selection` avatar. Reporting only; the API never changes the build because of it. The list and the detail report the same stall for the same avatar. |
| `createdAt` | string | yes |  |
| `updatedAt` | string | yes |  |
| `description` | string | no |  |
| `language` | string | no | The language set on the avatar (`language`); null when none was set, which reads as English. |
| `previews` | boolean | no | Whether preview clips are made (`previews`). |
| `previewMessage` | string | no | The preview message as set (`previewMessage`); null for the default sentence. |
| `persona` | `AvatarPersona` | no | Who the avatar is and how it talks, as set on create (`persona`), by PATCH or in Creator Studio, as it was set: a field never set is null (a list set empty is []). PATCH takes the same shape (AvatarPersonaEdit); send only the fields to change. |
| `knowledge` | `AvatarKnowledgeSummary` | no | What the avatar knows: the facts as set with `knowledge.facts`, the questionnaire answers, and the knowledge files (GET /v1/avatars/{avatarId}/knowledge links to them). |
| `voice` | `AvatarVoiceSettings` | no |  |
| `profile` | `AvatarProfile` | no | How the avatar is shown on its public page, as set in Creator Studio or by PATCH and the thumbnail route. |
| `studio` | `AvatarStudioChoices` | no | What was picked in Creator Studio's editor (read only here): how the portrait and the voice were made, and the persona presets the whoPrompt and whatPrompt texts started from. Null when never picked (an API avatar). |
| `servingCandidateId` | string | no | v2 only. The candidate the avatar renders with; null until one is promoted. |
| `selectedCandidateId` | string | no | v2 only. The picked candidate (auto or `PUT /selected_candidate`). It becomes `servingCandidateId` once its config is built, a few seconds later; until then `rebuilding` is true if another candidate still serves. The config is built with the current voice, so a pick made before a voice replacement is served once the new voice is cloned, and not at all if cloning fails (the serving candidate stays). Such a pick does not hold `rebuilding`, which then follows the new version. |
| `rebuilding` | boolean | no | v2 only. True while a newer version (new candidates, for a changed portrait, voice or preview message) builds behind the serving candidate. A persona edit is no new version and is followed on `stages.persona` instead. |
| `seedSelection` | string (`auto`, `manual`) | no | v2 only. |
| `stages` | object | yes | For v2 avatars `appearance` is image check plus preprocessing, `voice` is voice cloning plus the prime clip, and `previews` is candidate capture (see `GET /candidates`). The appearance check fails a portrait with no face, a face too small (under about a fifth of the shorter side once centre-cropped) or closed lips; its `userFeedback` says which (`portrait_no_face`, `portrait_face_too_small`, `portrait_mouth_closed`) and asks for a front-facing photo with the lips slightly parted. |
| `latestFailure` | object | no | The failure that still applies: the first stage, in build order (appearance, voice, persona, knowledge, previews), whose status is `failed` now. Absent once no stage is failed, so an old failure that a later build fixed is never reported. A failed avatar always has one; `userFeedback` is the reason, or a generic message for the stage when the pipeline recorded none. It can be present on a `ready` v2 avatar whose new voice or portrait failed while the previous take keeps serving. An `appearance` failure with a `portrait_*` reason (no face, face too small, lips closed) wants a new portrait: front-facing, face at least about a third of the frame, lips slightly parted, sent with `PUT /v1/avatars/{avatarId}/appearance`. |
| `previewUrls` | object | no | Pre-signed download URLs (mp4) of the finished preview clips, valid for about one hour from `expiresAt` backwards; re-GET the avatar to refresh them. Present on GET only, once at least one clip is completed. Absent while previews are still building, when they are disabled for this avatar, and on the list and PATCH responses. |
| `blackoutRecovery` | object | no | v2 only (absent on v1 avatars and on list rows). The blackout recovery a session started now would run with: each setting is the value set on this avatar, else the one its rendering config carries, else the default. A change applies from the next session; a running session keeps the settings it started with. |
| `runtimeSeed` | integer | no | v2 only (absent on v1 avatars and on list rows). The runtime seed a session started now would run with: the value set on this avatar, else the one its rendering config carries, else 42. A change applies from the next session. |
| `resolution` | object | no | v2 only (absent on v1 avatars, on list rows, and when the avatar's settings could not be read). The frame size the avatar's takes, previews and sessions render at: the one set on create or with PATCH, else 512 x 512. |
| `conductor` | object | no | v2 only (absent on v1 avatars and on list rows). Whether a graph conductor is set (`PUT /v1/avatars/{avatarId}/conductor`) and its node count; `GET /conductor` returns the graph. |