Update an avatar
Changes an avatar's settings, persona, knowledge or share card, and
returns the avatar. Send only the fields to change: an absent or null
field stays as it is, and an empty value ("", [] or {}) clears an
optional one.
- Persona edits rebuild the persona in the background and are moderated again. A v1 avatar is briefly not ready; a v2 avatar keeps serving until the new persona is live.
- v2 build inputs: a new
previewMessageorresolutionbuilds a new version with new candidates, like a new portrait or voice, while the serving candidate keeps serving.blackoutRecoveryandruntimeSeedapply from the next session and rebuild nothing. - Knowledge: knowledge files stay; replace them with
PUT /v1/avatars/{avatarId}/knowledge. - Visibility:
publicneeds a title, a tag, a subtitle, a description and a thumbnail (409 public_requirements_missinglists what is missing).publicandunlistedmust pass moderation (409 moderation_blocked). - Atomicity: every field is checked first. The name, description, share fields, statement, monetization and visibility are written together, and a refusal of any of them writes nothing. The rest is written after, so after a later error, send the same request again to retry.
| Field | Rule |
|---|---|
name | At most 100 characters once trimmed, counted in UTF-16 units (400 name_invalid). |
whoPrompt, whatPrompt, selfIntroduction | Cannot be emptied: "" is 422, and so is a blank selfIntroduction under 51 characters. Other blank text is 400 invalid_manifest. |
personality, scenario | Older names of whoPrompt and whatPrompt, at the top level or in persona. A field given twice is 400 invalid_body. |
previewMessage | "" goes back to the default sentence. On v2 at most 300 Unicode code points (400 preview_message_too_long). |
knowledge.facts | Replaces the knowledge text, at most 32,000 characters; "" removes it. |
knowledge.questionnaire | Replaces Creator Studio's questionnaire answers, question to answer; {} removes them. An unknown question, or a blank answer or one over 2,000 characters, is 400 invalid_manifest. |
title, subtitle, description | Share card text, at most 100, 200 and 280 characters; "" clears it. |
tags, socialLinks | Whole sets; [] clears them. At most 5 tags, each with a letter or digit. Each platform's link at most once, an https URL of at most 500 characters. |
statementType | Who the avatar depicts; "" resets it. It cannot change while the avatar is monetized (409 avatar_is_earning), and changing it clears verified. |
monetization | enabled turns monetization on or off. On needs a verified avatar or the fictional statement, verified payouts, the 30-day eligibility and room under the plan's cap (each a 409), and confirmSponsorWithdrawal: true when the sponsor pool holds credits, which turning it on withdraws to the account. Off always works. |
X-Api-Key<token>Your secret API key (sk_atmee_...; older keys start sk_live_),
sent as X-Api-Key. Keep it on your server and never send it to a
browser.
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 v2 avatar's frame size in pixels: 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.
Default 512 x 512 (square). A deployment offers only some sizes
(512 x 512 always; GET /v1/account limits.v2Resolutions lists
them): 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).
Atmee V2 HD is for Enterprise customers on custom plans; contact us for access. A v2hd avatar has its own rule and sizes: at most 414,720 pixels
(864 x 480), default 640 x 640, and only the sizes
limits.v2ProResolutions lists (640 x 640 always; e.g. 864 x 480,
480 x 864, 736 x 544, 544 x 736); 512 x 512 and the other v2 sizes
are not V2 HD sizes.
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. More values may be added: treat an
unknown one as building.
building: a build step is queued or running.ready: it serves a build andreadyToChatis true. A v2 avatar staysreadywhile a newer version builds or waits for a pick (rebuilding,selectionRequired).awaiting_selection(v2, manual selection): every take of the current version finished and nothing serves yet; select one.failed: a stage failed and nothing serves; seelatestFailure.moderation_hold: held for moderation review. Visitors cannot open it; the account can still start sessions whenreadyToChatis true.stalled: the build has made no progress for a long time (stallsays since when, and which stage). It will not finish by waiting: replace that stage's input or contact support.draft: created without its portrait or voice;missingInputsnames what to add withPUT /v1/avatars/{avatarId}/appearanceorPUT /v1/avatars/{avatarId}/voice.
"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, the original renderer, or v2, which serves a
selected candidate (see GET /v1/avatars/{avatarId}/candidates).
Atmee V2 HD is for Enterprise customers on custom plans; contact us for access. Or v2hd (Atmee V2 HD), a larger v2 model on its own GPU pool: it
builds, previews and serves exactly like v2 (candidates, versions,
conductor, seeds) at larger frame sizes (resolution, 640 x 640 by
default; GET /v1/account limits.v2ProResolutions), at its own
per-minute rates (GET /v1/account pricing,
sessionV2HdPerMinuteMicrocredits and the like). Creating v2hd needs Atmee V2
access and V2 HD on the account (Enterprise; 403 v2_pro_not_in_plan;
limits.v2Pro), and is
offered only where limits.v2Pro is reported (elsewhere 503 engine_unavailable).
"v1""v2""v2hd"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 made no progress for a long time: on a
stalled avatar, or on a ready or held avatar with a stage queued or
running for 6 hours (the avatar keeps serving). Never on a failed or
awaiting_selection avatar. For information only.
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 (automatic, or with PUT /v1/avatars/{avatarId}/selected_candidate). It becomes servingCandidateId once
built, a few seconds later; meanwhile rebuilding is true if
another candidate still serves. A pick made before a voice
replacement is served once the new voice is ready, and not at
all if that fails (the serving candidate stays).
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*The build stages. On v2, appearance is the portrait check and
preprocessing, voice is voice cloning, and previews is
candidate capture. The portrait check fails a portrait with no
face, a face too small or closed lips, and userFeedback says
which (portrait_no_face, portrait_face_too_small,
portrait_mouth_closed).
latestFailure?The failure that still applies: the first stage, in build order
(appearance, voice, persona, knowledge, previews), that is
failed now; absent once none is. userFeedback is the reason.
It can appear on a ready v2 avatar whose new portrait or voice
failed while the previous take keeps serving. A portrait_*
reason needs a new portrait: front-facing, the face at least a
third of the frame, lips slightly parted (PUT /v1/avatars/{avatarId}/appearance).
previewUrls?Presigned mp4 URLs of the finished preview clips, valid for
about an hour (see expiresAt); get the avatar again to refresh
them. Only on GET /v1/avatars/{avatarId}, once a clip is done.
blackoutRecovery?v2 only. The blackout recovery a session started now would use: each setting as set on the avatar, else from its rendering config, else the default. A change applies from the next session.
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 }}
