# Duplicate an avatar

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

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

Creates a new avatar from this one, optionally on another engine: the
way to move an avatar to Atmee V2<!-- v2pro --> Creating Atmee V2 HD avatars needs Growth and up; V2 HD avatars you already have keep working. See [pricing](https://www.atmee.ai/pricing). or V2 HD<!-- /v2pro -->
without giving its persona, knowledge, portrait and voice again. The
source is left as it is.

- **Copied**: the name and description (`name` renames the copy), the
  language, the persona (`whoPrompt`, `whatPrompt`, `preferredAlias`,
  `spokenName`, `knownAliases`, `selfIntroduction`, `guardrails`,
  `conversationalHabits`; `greeting` only onto a v1 copy), the preview
  message and `previews`, the knowledge (`knowledge.facts`, the
  questionnaire answers and every knowledge file with its
  description), the portrait and the voice sample. A voice picked
  from Creator Studio's premade voices is kept as that pick: its
  recording is the voice sample. A portrait cropped in Creator
  Studio keeps its crop record, with the uncropped original, so the
  copy can be re-cropped. The files are copied
  inside storage; nothing is uploaded again. A v2 source's
  `blackoutRecovery` and `runtimeSeed` are kept on a v2-family copy.
  Its shape is kept too: a copy on the same engine keeps its
  `resolution` (a legacy 384x640 or 640x384 moves to 384x672 or
  672x384); any other copy takes the target engine's size nearest
  its portrait's shape (the creator's crop, else the image).
- **Card**: the share card (title, subtitle, tags, social links) and
  the Explore thumbnail, uploaded or automatic, are copied too, the
  thumbnail inside storage, once the copy is made. A part that can no longer be copied, such as a
  thumbnail gone from storage, is left out without failing the
  duplicate.
- **Not copied**: anything about publishing or money. The copy is
  `private`, not monetized, with no sponsor pool, statement,
  integrations or graph conductor; v2 takes and versions are not
  copied either, the copy captures its own.
- **Engine**: `engine` is `v1` or `v2`<!-- v2pro --> Creating Atmee V2 HD avatars needs Growth and up; V2 HD avatars you already have keep working. See [pricing](https://www.atmee.ai/pricing). or `v2hd`<!-- /v2pro -->;
  absent keeps the source's. Any engine may be asked for, an older
  model included (a v2<!-- v2pro --> Creating Atmee V2 HD avatars needs Growth and up; V2 HD avatars you already have keep working. See [pricing](https://www.atmee.ai/pricing). or V2 HD<!-- /v2pro --> avatar onto v1<!-- v2pro -->Creating Atmee V2 HD avatars needs Growth and up; V2 HD avatars you already have keep working. See [pricing](https://www.atmee.ai/pricing). , a V2 HD avatar onto v2<!-- /v2pro -->).
  When the portrait's shape isn't exactly the copy's frame (square on
  v1), the portrait is cut again from the uncropped original: the
  largest rectangle of the frame's ratio inside the creator's crop.
  For a v1 copy it sits around the face: the largest one detected in
  the crop, else where the source's last build framed it, else the
  centre; any other copy is centred. Its crop record names that
  rectangle, so it can be moved. An image too large to cut is copied
  as it is.
  It is checked as on `POST /v1/avatars`:
  the same `402`, `403` and `503` answers for an engine the account or
  this server cannot use. A preview message longer than a v2 take
  speaks (300 characters) is left out of a v2 copy, which then speaks
  the default line.
- **Build**: the copy builds as a create with those inputs would
  (`202 building`; follow it with `GET /v1/avatars/{avatarId}`),
  knowledge base included. A v1 source with a portrait and no voice
  copies to a ready render-only v1 avatar (`201`) or a v2 `draft`
  missing its voice. A v2 copy's captures count against the limit
  of 10 queued or running, as on a create (`X-RateLimit-*`, `429`).
- **Files**: only the source's own files are copied. A file whose
  stored link points elsewhere, or that is no longer in storage, is
  `409 source_file_missing` (the message names it): replace it on the
  source and try again. A refused duplicate leaves no avatar behind.
- **Scopes**: `avatars:read` and `avatars:write`. An avatar-scoped key
  cannot duplicate.

## Parameters

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

## Request body

- `application/json`: `AvatarDuplicateRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | The copy's name; absent keeps the source's. |
| `engine` | string (`v1`, `v2`, `v2hd`, `v2pro`) | no | The copy's engine; absent keeps the source's. Any engine, an older model included.<!-- v2pro --> Creating Atmee V2 HD avatars needs Growth and up; V2 HD avatars you already have keep working. See [pricing](https://www.atmee.ai/pricing). `v2pro` is V2 HD's former name, read as `v2hd`.<!-- /v2pro --> |

## Responses

| Status | Description | Schema |
| --- | --- | --- |
| `201` | Created and ready; a render-only v1 copy has nothing to build. | `AvatarCreateResponse` |
| `202` | Accepted; the copy exists and is building (or is a `draft`). | `AvatarCreateResponse` |
| `400` | invalid_body (not JSON) \| invalid_manifest (`/name` or `/engine`) | `ApiErrorResponse` |
| `401` | Missing or invalid API key, or a user token that is invalid, anonymous or of a user who may act for no account (`invalid_login`). | none |
| `402` | insufficient_v2_credits (no longer sent; kept for older billing. Creating an Atmee V2 avatar below Pro answers `403 v2_access_required`) | `ApiErrorResponse` |
| `403` | insufficient_scope \| avatar_not_allowed (avatar-scoped key) \| account_not_allowed (`X-Account-Id` names an account the user may not act for) \| v2_access_required (a `v2` copy, a new V2 avatar, on an account below Pro)<!-- v2pro --> Creating Atmee V2 HD avatars needs Growth and up; V2 HD avatars you already have keep working. See [pricing](https://www.atmee.ai/pricing). \| v2hd_access_required (a `v2hd` copy, a new V2 HD avatar, on an account below Growth)<!-- /v2pro --> | `ApiErrorResponse` |
| `404` | avatar_not_found | `ApiErrorResponse` |
| `409` | source_file_missing \| avatar_limit_reached \| account_ambiguous (a user of several accounts sent no `X-Account-Id`) | `ApiErrorResponse` |
| `422` | A body that fails schema validation. | `ApiErrorResponse` |
| `429` | `rate_limited`: the captures do not fit the account's limit of queued or running captures. Send the same request again once some finish. | `RateLimitedResponse` |
| `503` | avatar_import_disabled \| engine_unavailable (the engine asked for is not offered on this server) | `ApiErrorResponse` |

## `201` response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `avatarId` | 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`. |
| `status` | string (`building`, `ready`, `draft`) | yes | `ready` for a render-only avatar (nothing to build), `draft` for one created without its portrait or voice, `building` otherwise. |
| `missingInputs` | array of string | no | What a `draft` was created without; absent otherwise. |
| `statusUrl` | string | yes |  |
| `engine` | `AvatarEngine` | no | Render engine: `v1`, the original renderer, or `v2`, which serves a selected candidate (see `GET /v1/avatars/{avatarId}/candidates`).<!-- v2pro --> Creating Atmee V2 HD avatars needs Growth and up; V2 HD avatars you already have keep working. See [pricing](https://www.atmee.ai/pricing). 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 a `v2hd` avatar needs Growth and up (`limits.v2Pro`; otherwise `403 v2hd_access_required`). Anyone can talk to a `v2hd` avatar, and an existing one keeps chatting, sharing and embedding on every plan. Its new takes and rebuilds need Growth and up where the account is under the Atmee V2 access rules (`limits.v2Trial` is reported) (otherwise `403 v2hd_view_only`), and are open on any plan elsewhere. Offered only where `limits.v2Pro` is reported (elsewhere `503 engine_unavailable`).<!-- /v2pro --> |
| `sponsor` | `SponsorGrantResponse` | no |  |

## `202` response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `avatarId` | 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`. |
| `status` | string (`building`, `ready`, `draft`) | yes | `ready` for a render-only avatar (nothing to build), `draft` for one created without its portrait or voice, `building` otherwise. |
| `missingInputs` | array of string | no | What a `draft` was created without; absent otherwise. |
| `statusUrl` | string | yes |  |
| `engine` | `AvatarEngine` | no | Render engine: `v1`, the original renderer, or `v2`, which serves a selected candidate (see `GET /v1/avatars/{avatarId}/candidates`).<!-- v2pro --> Creating Atmee V2 HD avatars needs Growth and up; V2 HD avatars you already have keep working. See [pricing](https://www.atmee.ai/pricing). 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 a `v2hd` avatar needs Growth and up (`limits.v2Pro`; otherwise `403 v2hd_access_required`). Anyone can talk to a `v2hd` avatar, and an existing one keeps chatting, sharing and embedding on every plan. Its new takes and rebuilds need Growth and up where the account is under the Atmee V2 access rules (`limits.v2Trial` is reported) (otherwise `403 v2hd_view_only`), and are open on any plan elsewhere. Offered only where `limits.v2Pro` is reported (elsewhere `503 engine_unavailable`).<!-- /v2pro --> |
| `sponsor` | `SponsorGrantResponse` | no |  |
