# Capture more candidates

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

`POST /v1/avatars/{avatarId}/candidates`

Captures `count` more candidates from the avatar's current bundle and
prime clip without re-running preprocessing. Captures are free for now
but count against the account's limit: at most 10 queued or running
(`X-RateLimit-Limit`, `X-RateLimit-Remaining`).

## Parameters

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

## Request body

- `application/json`: `CandidateCreateRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `count` | integer | yes |  |

## Responses

| Status | Description | Schema |
| --- | --- | --- |
| `202` | Accepted; the new candidates start as `pending`. | `CandidateListResponse` |
| `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 | none |
| `409` | not_v2_avatar \| bundle_not_ready \| account_ambiguous (a user token of several accounts without X-Account-Id) | none |
| `429` | rate_limited -- the captures do not fit the account's limit of queued or running captures. Where the database applies a v2 create or input change as a whole (the default once it is migrated), nothing the request asked for was applied (its uploads stay usable, the avatar keeps its inputs and its candidates), so the same request can be sent again once captures finish; on a database that does not yet, the uploads were used and the new input was saved without being built, and sending the request again builds it. | `RateLimitedResponse` |
| `503` | engine_unavailable | none |

## `202` response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of `Candidate` | yes |  |
| `versions` | array of `CandidateVersion` | no | Every version, oldest first. |
| `servingCandidateId` | string | no |  |
| `selectedCandidateId` | string | no | The picked candidate. The avatar serves it once its config is built, a few seconds after the pick. |
| `generation` | integer | yes | The generation of the current version's takes (informational). |
| `seedSelection` | string (`auto`, `manual`) | yes |  |
| `selectionRequired` | boolean | yes | Manual mode and a completed candidate of the current version is waiting to be promoted. |
| `rebuilding` | boolean | yes | A candidate serves while a newer version is still being built. |
| `warning` | string | no | Set when many candidates have been tried for one image and voice pair; usually the pair itself does not work. |