Skip to main content
POST
/
v1
/
avatars
create avatar
curl --request POST \
  --url https://api.anam.ai/v1/avatars \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'displayName=<string>' \
  --form imageFile='@example-file' \
  --form 'imageUrl=<string>' \
  --form 'avatarModel=<string>'
{
  "id": "071b0286-4cce-4808-bee2-e642f1062de3",
  "displayName": "Liv",
  "variantName": "home",
  "imageUrl": "https://lab.anam.ai/persona_thumbnails/liv_home.png",
  "videoUrl": "https://anam-prod.r2.cloudflarestorage.com/avatars/v2/stock/liv_home/idling_video.mp4?X-Amz-Signature=...",
  "createdAt": "2026-04-20T10:00:00.000Z",
  "updatedAt": "2026-04-20T10:00:00.000Z",
  "createdByOrganizationId": null,
  "availableVersions": [
    "v1",
    "v2",
    "cara-4-3"
  ],
  "activeVersion": "v2"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

Source image and display name for the new one-shot avatar. Provide either an uploaded file (multipart/form-data with imageFile) or a URL (application/json with imageUrl) — not both.

​
displayName
string
required

Display name for the avatar (3-50 characters)

​
imageFile
file

Image file to create the avatar from (JPEG, PNG, or WebP, max 4.5MB). Either imageFile or imageUrl must be provided, but not both.

​
imageUrl
string<uri>

URL of the image to create the avatar from (JPEG, PNG, or WebP, max 4.5MB). Either imageFile or imageUrl must be provided, but not both.

​
avatarModel
string

Avatar model to use (e.g. "cara-3", "cara-4-latest"). Defaults to the server default model. Gated models require organization-level access.

Response

Successfully created avatar

A face preset that a persona can use as its visual representation.

​
id
string<uuid>

Unique identifier for the avatar.

​
displayName
string

Human-readable name shown in the Lab and share links.

​
variantName
string

Name of the specific variant (e.g. lighting or pose) within the avatar family.

​
imageUrl
string<uri>

URL of the still image used as a preview of the avatar.

​
videoUrl
string<uri> | null

Signed URL for a short preview video of the avatar, if one exists. The URL is short-lived — re-fetch the avatar to get a fresh one. null when no preview video is available.

​
createdAt
string<date-time>

Timestamp when the avatar was created.

​
updatedAt
string<date-time>

Timestamp when the avatar was last updated.

​
createdByOrganizationId
string | null

ID of the organization that created the avatar, or null for stock avatars. IDs may be either UUIDs or nanoid-style strings depending on when the organization was created.

​
availableVersions
string[]

Public model names this avatar supports (e.g. cara-2, cara-3).

​
activeVersion
string

Public model name currently rendered when no explicit avatarModel is requested.

Last modified on April 22, 2026