Atmee.aiDocs
APIAPI referenceAvatars

Duplicate an avatar

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 Creating Atmee V2 HD avatars needs Growth and up; V2 HD avatars you already have keep working. See pricing. or V2 HD 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 Creating Atmee V2 HD avatars needs Growth and up; V2 HD avatars you already have keep working. See pricing. or v2hd; absent keeps the source's. Any engine may be asked for, an older model included (a v2 Creating Atmee V2 HD avatars needs Growth and up; V2 HD avatars you already have keep working. See pricing. or V2 HD avatar onto v1Creating Atmee V2 HD avatars needs Growth and up; V2 HD avatars you already have keep working. See pricing. , a V2 HD avatar onto v2). 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.

Authorization

headerX-Api-Key<token>

Your secret API key (sk_atmee_...; older keys start sk_live_), sent as X-Api-Key. Keep it on your server and never send it to a browser.

Path Parameters

avatarId*string
Formatuuid

Request Body

application/json
  1. body
name?string

The copy's name; absent keeps the source's.

Length1 <= length <= 100
engine?string

The copy's engine; absent keeps the source's. Any engine, an older model included. Creating Atmee V2 HD avatars needs Growth and up; V2 HD avatars you already have keep working. See pricing. v2pro is V2 HD's former name, read as v2hd.

Value in"v1""v2""v2hd""v2pro"

Response Body

Created and ready; a render-only v1 copy has nothing to build.

application/json
  1. response
avatarId*string
Formatuuid
kind*AvatarKind

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.

Value in"conversational""render_only"
status*string

ready for a render-only avatar (nothing to build), draft for one created without its portrait or voice, building otherwise.

Value in"building""ready""draft"
missingInputs?array<>

What a draft was created without; absent otherwise.

statusUrl*string
engine?AvatarEngine

Render engine: v1, the original renderer, or v2, which serves a selected candidate (see GET /v1/avatars/{avatarId}/candidates). Creating Atmee V2 HD avatars needs Growth and up; V2 HD avatars you already have keep working. See 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).

Value in"v1""v2""v2hd"
sponsor?
Example Request
curl -X POST 'https://api.atmanity.us/v1/avatars/497f6eca-6276-4993-bfeb-53cbbbba6f08/duplicate' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "avatarId": "ac572b6e-802b-4b9e-a602-0786d4441e67",  "kind": "conversational",  "status": "building",  "missingInputs": [    "image"  ],  "statusUrl": "string",  "engine": "v1",  "sponsor": {    "transferredMicrocredits": 0,    "replayed": true,    "error": "string"  }}