Update name, description, visibility, language or preview message
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 409s)
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.
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*stringuuidapplication/json- body
1 <= propertiesname?string1 <= length <= 100description?stringlength <= 280visibility?string"private""unlisted""public"language?string"en""zh-TW""zh-CN""ja""ko""fr""vi""es""de""hi""ru"previews?booleanTurn 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?stringlength <= 500personality?stringThe main character description (who the avatar is).
1 <= length <= 10000scenario?stringWhat the avatar is doing with the visitor.
1 <= length <= 10000whoPrompt?string1 <= length <= 10000whatPrompt?string1 <= length <= 10000greeting?stringlength <= 500selfIntroduction?string51 <= length <= 2000guardrails?array<>items <= 20conversationalHabits?preferredAlias?stringlength <= 100spokenName?stringlength <= 100knownAliases?array<>items <= 20blackoutRecovery?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?RuntimeSeedThe 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.
0 <= value <= 2147483647resolution?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?AvatarShareTitleThe display title on Explore (Creator Studio's share card); "" clears it, and the card shows the preferred alias, then the name.
length <= 100subtitle?AvatarShareSubtitleThe line under the title on Explore; "" clears it.
length <= 200tags?array<string>The avatar's tags, the whole set ([] clears them); at most 5 once trimmed and with case-insensitive duplicates dropped.
socialLinks?array<>The avatar's social links, the whole set ([] removes them all); a platform left out has no link.
statementType?AvatarStatementTypeWho the avatar depicts (the avatar's creator, someone they represent, or a fictional character); "" resets it.
"self_verification""representative_verification""fictional_verification"""monetization?Turn monetization on or off, as Creator Studio's switch does.
persona?The persona fields to change (the shape GET answers in persona);
an absent or null field stays unchanged.
knowledge?Updated; returns the detail.
application/json- response
id*stringuuidlinks?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*stringkind*AvatarKindconversational 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.
"conversational""render_only"visibility*string"private""unlisted""public"moderationState?stringcreationSource?stringSet to api for avatars created through this API.
status*stringWhat 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 andreadyToChatis true. A v2 avatar staysreadywhile 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;latestFailurenames the first failed stage and why.moderation_hold: held for moderation review (moderationStateon_hold, pending_review or confirmed_unsafe). Visitors -- public and unlisted links, Explore -- cannot open it. The account itself can still start sessions on it whenreadyToChatis 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.stallsays 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;missingInputsnames what it lacks. Nothing that needs them builds until they are given (PUT /appearance,PUT /voice); it will not finish by waiting.
"building""ready""failed""moderation_hold""awaiting_selection""stalled""draft"missingInputs?array<>The inputs a draft still lacks; absent on every other status.
engine?AvatarEngineRender engine. v1 is the original renderer. v2 is
built from a bundle plus a promoted candidate; see /candidates.
"v1""v2"thumbnailUrl?stringPresigned image (Studio's custom thumbnail, else the portrait), valid about one hour; re-GET to refresh.
uriselectionRequired?booleanv2 only. True while a completed candidate waits to be promoted (manual mode).
readyToChat*booleanA 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?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*stringdate-timeupdatedAt*stringdate-timedescription?stringlanguage?stringThe language set on the avatar (language); null when none was set, which reads as English.
previews?booleanWhether preview clips are made (previews).
previewMessage?stringThe preview message as set (previewMessage); null for the default sentence.
persona?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?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?profile?How the avatar is shown on its public page, as set in Creator Studio or by PATCH and the thumbnail route.
studio?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?stringv2 only. The candidate the avatar renders with; null until one is promoted.
uuidselectedCandidateId?stringv2 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.
uuidrebuilding?booleanv2 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?stringv2 only.
"auto""manual"stages*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?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?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?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?integerv2 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?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?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.
curl -X PATCH 'https://api.atmanity.us/v1/avatars/497f6eca-6276-4993-bfeb-53cbbbba6f08' \ -H 'Content-Type: application/json' \ -d '{}'{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "links": { "chat": "http://example.com", "profile": "http://example.com", "studio": "http://example.com" }, "name": "string", "kind": "conversational", "visibility": "private", "moderationState": "string", "creationSource": "string", "status": "building", "missingInputs": [ "image" ], "engine": "v1", "thumbnailUrl": "http://example.com", "selectionRequired": true, "readyToChat": true, "stall": { "since": "2019-08-24T14:15:22Z", "stage": "appearance", "reason": "string" }, "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "description": "string", "language": "string", "previews": true, "previewMessage": "string", "persona": { "whoPrompt": "string", "whatPrompt": "string", "greeting": "string", "selfIntroduction": "string", "guardrails": [ "string" ], "conversationalHabits": { "property1": "CONVERSATIONAL_HABIT_SCALE_LOW", "property2": "CONVERSATIONAL_HABIT_SCALE_LOW" }, "preferredAlias": "string", "spokenName": "string", "knownAliases": [ "string" ] }, "knowledge": { "facts": "string", "questionsAnswered": 0, "questionnaire": { "property1": "string", "property2": "string" }, "integrationIds": [ "string" ], "factsChars": 0, "files": [ { "id": "string", "name": "string", "description": "string", "sizeBytes": 0 } ] }, "voice": { "ttsProvider": "chatterbox_v3" }, "profile": { "title": "string", "subtitle": "string", "tags": [ "string" ], "socialLinks": [ { "type": "string", "url": "string" } ], "monetizationEnabled": true, "verified": true, "statementType": "string", "thumbnailSource": "auto" }, "studio": { "creationMethod": "string", "voiceType": "string", "whoAreYou": "string", "scenario": "string" }, "servingCandidateId": "908e27ac-861b-45dc-ab30-d9e3b56dc291", "selectedCandidateId": "ecabe377-180f-4e15-820f-e34d12b31008", "rebuilding": true, "seedSelection": "auto", "stages": { "appearance": { "status": "waiting", "userFeedback": "string" }, "voice": { "status": "waiting", "userFeedback": "string" }, "persona": { "status": "waiting", "userFeedback": "string" }, "knowledge": { "status": "waiting", "userFeedback": "string" }, "previews": { "status": "waiting", "userFeedback": "string" } }, "latestFailure": { "stage": "appearance", "userFeedback": "string" }, "previewUrls": { "idle": "http://example.com", "talking": "http://example.com", "expiresAt": "2019-08-24T14:15:22Z" }, "blackoutRecovery": { "enabled": true, "detection": "tiles", "tileThreshold": 0.1, "regionThreshold": 0.1 }, "runtimeSeed": 0, "resolution": { "width": 256, "height": 256 }, "conductor": { "configured": true, "nodes": 0 }}