create avatar

Create a new one-shot avatar from an image file or image URL. You can use either multipart/form-data with an image file, or JSON with an image URL.

POST /v1/avatars

create avatar

cURL

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>'

201

{
  "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

multipart/form-dataapplication/json

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

201

application/json

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 muted idling MP4 preview of the avatar, if one exists. The URL expires after 1 hour; re-fetch the avatar to get a fresh URL. null when the preview is unavailable or still generating.

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[]

Internal avatar version identifiers this avatar has generated assets for. Current public model mappings are v1 = cara-2, v2 = cara-3, and cara-4-* = cara-4-latest. Use the public avatarModel request field when selecting a model.

activeVersion · string

Internal avatar version used by default when no explicit avatarModel is requested. Current public model mappings are v1 = cara-2, v2 = cara-3, and cara-4-* = cara-4-latest.