# Promote the candidate a v2 avatar renders with

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

`PUT /v1/avatars/{avatarId}/selected_candidate`

Picks a completed candidate. The pick is recorded at once
(`selectedCandidateId`); the avatar serves it once its config is
built, a few seconds later (`servingCandidateId`). The first pick
makes the avatar `ready`; a later one switches without downtime, with
`rebuilding` true until it serves.

A completed candidate of an older version (`current: false`,
`restorable: true`) goes back to that version -- also when it is
still the pick from before an edit: its portrait, voice sample and
preview message, and the language its default sentence speaks,
become the avatar's again, in one step, and every other setting
(persona, greeting, guardrails, knowledge, name) stays as it is now.
Nothing is captured again and nothing is charged: that version's
takes are already built. Takes of the newer version still queued or
being captured are cancelled. Moderation is not run again for
inputs already checked together; a combination never checked (the
old portrait with a name or description edited since) is moderated
like any edit. Re-selecting the current pick is always allowed.
Queued, failed and superseded candidates cannot be selected.

## Parameters

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

## Request body

- `application/json`: `CandidateSelectRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `candidateId` | string | yes |  |

## Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Promoted; returns the detail. | `AvatarDetail` |
| `400` | invalid_body | none |
| `401` | Missing or invalid credentials -- 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 \| candidate_not_found | none |
| `409` | not_v2_avatar \| candidate_not_ready (queued, failed or superseded) \| version_not_restorable (an older version a stored file of which is gone -- its portrait, voice sample, voice clone, prime, bundle or the take's sink; nothing changed) \| account_ambiguous (a user token of several accounts without X-Account-Id) | 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. |