Atmee.aiDocs
APIAPI referenceAvatars

List the candidates and versions of a v2 avatar

GET
/v1/avatars/{avatarId}/candidates

v2 (engine: v2) avatars only. A candidate (a take) is one capture: a sink latent that decides lip sync and motion for this image and voice pair, plus a ~3 s talking preview of the avatar saying the preview message. Candidates are identified by candidateId; the seed is informational (the same seed does not reproduce a capture). Promote one with PUT /selected_candidate; with seedSelection: auto the first completed candidate of the current version is promoted for you.

A version is one set of capture inputs: the portrait, the voice sample and the preview message. Replacing any of them starts a new version; the takes of older versions are kept. versions always lists every version (oldest first) with what going back to it brings back. items lists the takes of the current version, plus the serving take if it is older; pass versions=all for the takes of every version.

Authorization

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

Path Parameters

avatarId*string
Formatuuid

Query Parameters

versions?string

Which takes items lists. current (the default) is the current version's takes and the serving one; all adds every older version's.

Default"current"
Value in"current""all"

Response Body

The candidates, oldest first, with presigned preview URLs.

application/json
  1. response
items*array<>
versions?array<>

Every version, oldest first.

servingCandidateId?string
Formatuuid
selectedCandidateId?string

The picked candidate. The avatar serves it once its config is built, a few seconds after the pick.

Formatuuid
generation*integer

The generation of the current version's takes (informational).

seedSelection*string
Value in"auto""manual"
selectionRequired*boolean

Manual mode and a completed candidate of the current version is waiting to be promoted.

rebuilding*boolean

A candidate serves while a newer version is still being built.

warning?string

Set when many candidates have been tried for one image and voice pair; usually the pair itself does not work.

Example Request
curl -X GET 'https://api.atmanity.us/v1/avatars/497f6eca-6276-4993-bfeb-53cbbbba6f08/candidates'
Example Response
{  "items": [    {      "candidateId": "10f4deb6-fd4e-4907-a47e-355caf6e449d",      "generation": 0,      "versionId": "string",      "current": true,      "restorable": true,      "seed": 0,      "status": "pending",      "serving": true,      "previewUrl": "http://example.com",      "previewExpiresAt": "2019-08-24T14:15:22Z",      "userFeedback": "string",      "createdAt": "2019-08-24T14:15:22Z"    }  ],  "versions": [    {      "versionId": "string",      "current": true,      "serving": true,      "restorable": true,      "takes": 0,      "createdAt": "2019-08-24T14:15:22Z",      "portraitUrl": "http://example.com",      "voiceSampleUrl": "http://example.com",      "previewMessage": "string",      "language": "string"    }  ],  "servingCandidateId": "908e27ac-861b-45dc-ab30-d9e3b56dc291",  "selectedCandidateId": "ecabe377-180f-4e15-820f-e34d12b31008",  "generation": 0,  "seedSelection": "auto",  "selectionRequired": true,  "rebuilding": true,  "warning": "string"}

Upload status GET

pending until the file arrives, then uploaded (usable once), consumed once a create or replace used it, or expired an hour after it was created.

Capture more candidates POST

Captures count more candidates from the avatar's current bundle and prime clip without re-running preprocessing.

List the candidates and versions of a v2 avatar — Atmee Docs