Avatar detail and build status

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.

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.

Set to api for avatars created through this API.

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.

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

Render engine. v1 is the original renderer. v2 is built from a bundle plus a promoted candidate; see /candidates.

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

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

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.

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.

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

Whether preview clips are made (previews).

The preview message as set (previewMessage); null for the default sentence.

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.

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

How the avatar is shown on its public page, as set in Creator Studio or by PATCH and the thumbnail route.

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

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

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.

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.

v2 only.

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.

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.

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.

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.

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.

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.

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.