Skip to main content
POST
Create an avatar
Multipart form fields:
Returns 201 with the avatar record. image_url identifies its source image. idle_video_status starts as PENDING while the idle clip renders. This endpoint is limited to 5 requests per minute per key.

Authorizations

x-api-key
string
header
required

FaceMode API key (fm_...).

Body

multipart/form-data
image
file

Source image file (image/*, max 5 MB). A clear front-facing headshot works best.

image_url
string

Alternative to image: reference an already hosted image URL.

name
string

Display name.

source
enum<string>

Avatar source; custom uploads are stored as CUSTOM.

Available options:
CUSTOM
config
string

Optional JSON-encoded configuration object.

isActive
enum<string>

Whether the avatar can be used for sessions (default true).

Available options:
true,
false

Response

Avatar created.

Avatar record with its source image and render readiness.

id
string<uuid>
userId
string<uuid> | null

Owner account ID; null for platform defaults.

name
string
source
enum<string>

DEFAULT for platform avatars, CUSTOM for uploads.

Available options:
DEFAULT,
CUSTOM
style
enum<string> | null
Available options:
REALISM,
SEMI_REALISM,
THREE_D_CARTOON,
ANIME_MANGA,
FLAT_VECTOR
image_url
string | null

Source image URL used for avatar rendering and downloads.

image_version
integer

Increments each time the image is replaced.

idle_video_status
string

Idle clip render state, for example PENDING, READY, or FAILED.

config
object

Avatar configuration metadata.

isActive
boolean

Only active avatars can start sessions.

isOwned
boolean

Present on list/get responses: true when the avatar belongs to the caller.

createdAt
string<date-time>
updatedAt
string<date-time>