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://example.com/avatar-preview.mp4?X-Amz-Signature=...", "createdAt": "2026-04-20T10:00:00.000Z", "updatedAt": "2026-04-20T10:00:00.000Z", "createdByOrganizationId": null, "availableVersions": [ "cara-3" ], "activeVersion": "cara-3" }

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.

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.

landscapeImageUrl

string<uri> | null

Preview image cropped exactly as the engine frames landscape (1152x768) output. Use this when displaying the avatar at a landscape aspect ratio. For avatars with legacy landscape source images this is the same as imageUrl.

portraitImageUrl

string<uri> | null

Preview image cropped exactly as the engine frames portrait (768x1152) output. Use this when starting a session with portrait videoWidth/videoHeight. null when the avatar cannot render portrait output.

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

Avatar models this avatar can be used with. Pass one of these values as avatarModel when creating a persona or starting a session.

activeVersion

string | null

Avatar model used by default when no explicit avatarModel is requested.