create avatar

Display name for the avatar (1+ characters)

URL of the image to create the avatar from (JPEG, PNG, or WebP, max 4.5MB). The image will be downloaded, processed, and stored permanently.

auto crops and may outpaint the image. preserve uses the source pixels without resizing, cropping, padding, outpainting or alignment/refinement. Requires an opaque, static, 8-bit RGB or RGBA PNG of exactly 1152x1152 pixels, at most 4.5MB, with no EXIF metadata. RGBA alpha must be fully opaque. Cannot be combined with zoomOutPercent. Moderation, quotas and facial compatibility checks still apply. Character animation quality varies with human-like facial features. Output video still uses the normal landscape or portrait crop; sourceImageUrl returns the square source. Animation frames may change.

Avatar model for creation. Defaults to cara-4.1-express. Cara 2 and Cara 3 creation are not supported.

Unique identifier for the avatar.

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

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

Still image of the avatar, framed exactly like videoUrl, idleVideoUrl and a landscape session (the default). Use it as the thumbnail, poster or loading image wherever a preview video or the live stream replaces it, and give the image and the video the same box, object-fit and object-position so the avatar doesn't move when they swap. For Cara 4 avatars this is the 1152x768 landscape crop (the same image as landscapeImageUrl). Cara 4 avatars used to return their square source image here; that image is now sourceImageUrl. Empty when the avatar has no image yet.

The image the avatar was created from. For Cara 4 avatars it is square (1152x1152) and shows more of the scene than the 1152x768 crop that preview videos and sessions use, so the avatar appears to zoom in when a video or call replaces it. Don't use it as a thumbnail, poster or loading image next to videoUrl or a session; use imageUrl, landscapeImageUrl or portraitImageUrl. For legacy avatars it is the same landscape image as imageUrl.

Still image cropped exactly as the engine frames landscape (1152x768) output, which is also the framing of videoUrl and idleVideoUrl. Use it with landscape sessions (the default) and preview videos. For avatars with legacy landscape source images this is the source image.

Still image cropped exactly as the engine frames portrait (768x1152) output. Use it as the poster for a session started with portrait videoWidth/videoHeight. Preview videos are landscape, so don't swap this image for videoUrl. null when the avatar cannot render portrait output.

Signed URL for a verified muted MP4 preview of the avatar. Uses the idle loop if the talking preview is unavailable. Landscape (1152x768 for Cara 4 avatars, 720x480 for legacy avatars) and framed exactly like imageUrl, so pair it with imageUrl or landscapeImageUrl, not sourceImageUrl. The URL expires after 1 hour; re-fetch the avatar to get a fresh URL. null when the preview is unavailable or still generating.

Signed URL for a muted idling-loop MP4 of the avatar, if one exists. Landscape and framed exactly like imageUrl, like videoUrl. The URL expires after 1 hour; re-fetch the avatar to get a fresh URL. null when unavailable or still generating.

Timestamp when the avatar was created.

Timestamp when the avatar was last updated.

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.

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

AI-generated description of the avatar's appearance, setting, and style. null if metadata generation has not completed.

Render style of the avatar. unknown covers custom avatars and avatars whose metadata has not yet been generated.