Atmee.aiDocs
APIAPI referenceAvatars

Update an avatar

PATCH
/v1/avatars/{avatarId}

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 previewMessage or resolution builds a new version with new candidates, like a new portrait or voice, while the serving candidate keeps serving. blackoutRecovery and runtimeSeed apply from the next session and rebuild nothing.
  • Knowledge: knowledge files stay; replace them with PUT /v1/avatars/{avatarId}/knowledge.
  • Visibility: public needs a title, a tag, a subtitle, a description and a thumbnail (409 public_requirements_missing lists what is missing). public and unlisted must 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.
FieldRule
nameAt most 100 characters once trimmed, counted in UTF-16 units (400 name_invalid).
whoPrompt, whatPrompt, selfIntroductionCannot be emptied: "" is 422, and so is a blank selfIntroduction under 51 characters. Other blank text is 400 invalid_manifest.
personality, scenarioOlder 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.factsReplaces the knowledge text, at most 32,000 characters; "" removes it.
knowledge.questionnaireReplaces 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, descriptionShare card text, at most 100, 200 and 280 characters; "" clears it.
tags, socialLinksWhole 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.
statementTypeWho the avatar depicts; "" resets it. It cannot change while the avatar is monetized (409 avatar_is_earning), and changing it clears verified.
monetizationenabled 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.

Authorization

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

Path Parameters

avatarId*string
Formatuuid

Request Body

application/json
  1. body
Properties1 <= properties
name?string
Length1 <= length <= 100
description?string
Lengthlength <= 280
visibility?string
Value in"private""unlisted""public"
language?string
Value in"en""zh-TW""zh-CN""ja""ko""fr""vi""es""de""hi""ru"
previews?boolean

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
Lengthlength <= 500
personality?string

The main character description (who the avatar is).

Length1 <= length <= 10000
scenario?string

What the avatar is doing with the visitor.

Length1 <= length <= 10000
whoPrompt?string
Length1 <= length <= 10000
whatPrompt?string
Length1 <= length <= 10000
greeting?string
Lengthlength <= 500
selfIntroduction?string
Length51 <= length <= 2000
guardrails?array<>
Itemsitems <= 20
conversationalHabits?
preferredAlias?string
Lengthlength <= 100
spokenName?string
Lengthlength <= 100
knownAliases?array<>
Itemsitems <= 20
blackoutRecovery?

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

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.

Range0 <= value <= 2147483647
resolution?

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?AvatarShareTitle

The display title on Explore (Creator Studio's share card); "" clears it, and the card shows the preferred alias, then the name.

Lengthlength <= 100
subtitle?AvatarShareSubtitle

The line under the title on Explore; "" clears it.

Lengthlength <= 200
tags?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?AvatarStatementType

Who the avatar depicts (the avatar's creator, someone they represent, or a fictional character); "" resets it.

Value in"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?

Response Body

Updated; returns the detail.

application/json
  1. response
id*string
Formatuuid
links?

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
kind*AvatarKind

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.

Value in"conversational""render_only"
visibility*string
Value in"private""unlisted""public"
moderationState?string
creationSource?string

Set to api for avatars created through this API.

status*string

What 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 and readyToChat is true. A v2 avatar stays ready while 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; see latestFailure.
  • moderation_hold: held for moderation review. Visitors cannot open it; the account can still start sessions when readyToChat is true.
  • stalled: the build has made no progress for a long time (stall says 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; missingInputs names what to add with PUT /v1/avatars/{avatarId}/appearance or PUT /v1/avatars/{avatarId}/voice.
Value in"building""ready""failed""moderation_hold""awaiting_selection""stalled""draft"
missingInputs?array<>

The inputs a draft still lacks; absent on every other status.

engine?AvatarEngine

Render 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).

Value in"v1""v2""v2hd"
thumbnailUrl?string

Presigned image (Studio's custom thumbnail, else the portrait), valid about one hour; re-GET to refresh.

Formaturi
selectionRequired?boolean

v2 only. True while a completed candidate waits to be promoted (manual mode).

readyToChat*boolean

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?

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*string
Formatdate-time
updatedAt*string
Formatdate-time
description?string
language?string

The language set on the avatar (language); null when none was set, which reads as English.

previews?boolean

Whether preview clips are made (previews).

previewMessage?string

The 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?string

v2 only. The candidate the avatar renders with; null until one is promoted.

Formatuuid
selectedCandidateId?string

v2 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).

Formatuuid
rebuilding?boolean

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

v2 only.

Value in"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?integer

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?

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.

Example Request
curl -X PATCH 'https://api.atmanity.us/v1/avatars/497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "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  }}