Create an avatar

Everything you can do in Studio's Create flow is also an API call. An avatar made through the API shows up in Studio and starts sessions with POST /v1/sessions like any other.

There are two ways to create one. Both build either model and end the same way.

Before you startCopy Anchor Link

• A key with avatars:write, account-wide: an avatar-scoped key can't create avatars. Add generation:write to generate a portrait or a voice. See API keys.
• A portrait: jpg, png or webp, up to 10 MB. See Avatar 101: Negative examples for the photos that animate badly.
• A voice sample: 10 to 60 seconds of one person speaking clearly, up to 12 MB: mp3, wav, m4a, aac, ogg, flac, opus or webm. An Atmee V2 avatar's voice is cloned from it.
• Permission: if the portrait or the voice is a real person other than you, have that person's permission first.
• The model: set engine to v2 or v1 on every create. Without it the API builds Atmee V1. Atmee V2 is invite only for now (403 v2_access_required without access).

Create with JSONCopy Anchor Link

Send a manifest that points at your files. Atmee downloads them, checks them and starts the build.

curl -X POST https://api.atmanity.us/v1/uploads \
  -H "X-Api-Key: $ATMEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "portrait" }'

curl -X PUT "<uploadUrl>" -H "Content-Type: image/jpeg" --data-binary @portrait.jpg

curl -X POST https://api.atmanity.us/v1/avatars \
  -H "X-Api-Key: $ATMEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schemaVersion": 1,
    "name": "Val",
    "engine": "v2",
    "language": "en",
    "visibility": "private",
    "previewMessage": "Hi! I am Val. What can I help you find today?",
    "assets": {
      "image": { "url": "https://cdn.example.com/val/portrait.jpg" },
      "voice": { "url": "upload:6f1c2d34-8b7a-4e19-9c5d-0a2b3c4d5e6f" }
    }
  }'

{
  "avatarId": "56cc8fdd-ba78-4d48-a210-16cf80c3f5f5",
  "status": "building",
  "statusUrl": "/v1/avatars/56cc8fdd-ba78-4d48-a210-16cf80c3f5f5"
}

curl https://api.atmanity.us/v1/avatars/56cc8fdd-ba78-4d48-a210-16cf80c3f5f5 \
  -H "X-Api-Key: $ATMEE_API_KEY"

curl https://api.atmanity.us/v1/avatars/56cc8fdd-ba78-4d48-a210-16cf80c3f5f5/candidates \
  -H "X-Api-Key: $ATMEE_API_KEY"

Create with a zipCopy Anchor Link

Put the manifest and the files in one zip, and send it in one request.

my-avatar.zip
├── avatar.json          # the manifest (required)
├── image/portrait.jpg   # exactly one image
├── voice/sample.wav     # exactly one sample; leave out for a render-only avatar
├── prompt/prompt.txt    # optional: what the avatar does with the visitor, as text
└── knowledge/           # optional: up to 20 files (pdf, docx, doc, txt, md, html, csv), 50 MB each

{
  "schemaVersion": 1,
  "name": "Grand Valley Concierge",
  "engine": "v1",
  "language": "en",
  "visibility": "private",
  "persona": {
    "preferredAlias": "Val",
    "whoPrompt": "A warm, endlessly patient concierge who knows the resort inside out.",
    "greeting": "Hi, I'm Val. How can I help?",
    "guardrails": ["Never quote prices that aren't in the knowledge base"]
  },
  "knowledge": { "descriptions": { "pricing.pdf": "2026 rate card" } }
}

curl -X POST https://api.atmanity.us/v1/avatars \
  -H "X-Api-Key: $ATMEE_API_KEY" \
  -F "file=@my-avatar.zip"

Render-only avatars. A zip without a voice, or a multipart request with only an image (file) and a name, makes a render-only avatar: 201, ready at once, for use with your own voice agent in Avatar mode. Add a voice later with PUT /v1/avatars/{avatarId}/voice to make it talk on its own.

Manifest fieldsCopy Anchor Link

personality and scenario still work as older names of whoPrompt and whatPrompt; a field given under both names is 400 invalid_manifest.

Start with only a name. The portrait and the voice are optional on both paths. An avatar created without them is a draft (status: draft, with missingInputs naming what it lacks). Add them with PUT /appearance and PUT /voice, in either order, and the build carries on. An Atmee V2 draft captures one take, picked automatically.

Build statusCopy Anchor Link

The answer also has stages: appearance, voice, persona, knowledge and previews, each moving through waiting, pending, processing and completed, skipped when it doesn't apply (such as previews when you didn't ask for them), or failed with a userFeedback message. A clearly bad portrait fails appearance with a portrait_* reason (portrait_no_face, portrait_face_too_small, portrait_mouth_closed); replace the portrait to fix it.

If a create fails on the network, list your avatars before you send it again: a repeated create makes a second avatar.

Takes and versionsCopy Anchor Link

Atmee V2 only. Lip sync and motion vary from take to take, and the inputs don't tell you which will be best, so watch them.

• List with GET /v1/avatars/{avatarId}/candidates. Each item has a status and a previewUrl (an mp4, valid about an hour), and serving marks the take the avatar talks with.
• Capture more with POST /v1/avatars/{avatarId}/candidates and { "count": 3 }. New takes come from the current portrait, voice and preview message, and never change the serving take. An account can have at most 10 captures queued or running (429 rate_limited beyond that).
• Pick one with PUT /v1/avatars/{avatarId}/selected_candidate and its candidateId. Only a completed take can be picked; it serves a few seconds later.

A version is one set of capture inputs: the portrait, the voice sample and the preview message. Changing any of them starts a new version with new takes, and the old take serves until a new one goes live. Picking a take of an older version goes back to that version's inputs, with nothing captured again. DELETE /v1/avatars/{avatarId}/versions/{versionId} removes an older version; the current one, or one holding the serving take, can't be deleted (version_in_use).

Update it afterwardsCopy Anchor Link

• The character and the text fields: PATCH /v1/avatars/{avatarId} with only the fields to change, such as persona, knowledge.facts, name, language, visibility or previewMessage. Send an empty value ("", [], {}) to clear one. Every persona edit is moderated again.
• The portrait or the voice: PUT /appearance or PUT /voice. Only the stages that depend on it run again. On Atmee V2 this starts a new version.
• The knowledge files: PUT /knowledge replaces the whole set.
• An agenda (Atmee V2): PUT /conductor.
• Delete it: DELETE /v1/avatars/{avatarId}.

No portrait or voice yet?Copy Anchor Link

Generate them. Each call needs a key with generation:write and avatars:write, and an Idempotency-Key header with a new UUID, so a retry never charges twice.

Each output comes back as upload:<uploadId>: pass it straight to assets.image.url, assets.voice.url, or a /appearance or /voice replace. You're charged only when at least one output comes back. Never generate a real person's likeness from a description; for a real person, enhance their own photo, with their permission.

ErrorsCopy Anchor Link

A create that can't start answers 400 with an error and a message naming the problem:

The full list is in the API reference.