Update an avatar

PUT

avatars

{id}

Update an avatar

curl --request PUT \
  --url https://api.facemode.io/api/avatars/{id} \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-key: <api-key>' \
  --form image=@example-file \
  --form 'name=<string>' \
  --form 'config=<string>'

const form = new FormData();
form.append('image', '<string>');
form.append('name', '<string>');
form.append('config', '<string>');

const options = {method: 'PUT', headers: {'x-api-key': '<api-key>'}};

options.body = form;

fetch('https://api.facemode.io/api/avatars/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.facemode.io/api/avatars/{id}"

files = { "image": ("example-file", open("example-file", "rb")) }
payload = {
    "name": "<string>",
    "config": "<string>"
}
headers = {"x-api-key": "<api-key>"}

response = requests.put(url, data=payload, files=files, headers=headers)

print(response.text)

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "source": "DEFAULT",
  "style": "REALISM",
  "image_url": "<string>",
  "image_version": 123,
  "idle_video_status": "<string>",
  "config": {},
  "isActive": true,
  "isOwned": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "ROOM_INVALID",
    "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily",
    "details": {}
  },
  "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
}

{
  "error": {
    "code": "ROOM_INVALID",
    "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily",
    "details": {}
  },
  "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
}

{
  "error": {
    "code": "ROOM_INVALID",
    "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily",
    "details": {}
  },
  "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
}

{
  "error": {
    "code": "ROOM_INVALID",
    "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily",
    "details": {}
  },
  "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
}

{
  "error": {
    "code": "ROOM_INVALID",
    "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily",
    "details": {}
  },
  "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
}

{
  "error": {
    "code": "ROOM_INVALID",
    "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily",
    "details": {}
  },
  "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
}

Multipart fields - all optional, send only what changes:

Field	Type	Description
`image`	file	Replacement image (`image/*`, max 5 MB). Replacing it bumps `image_version` and re-queues idle avatar video rendering.
`name`	string	New display name.
`config`	string	JSON-encoded configuration object.
`isActive`	string	`"true"`/`"false"`. Inactive avatars cannot start sessions.

curl -X PUT https://api.facemode.io/api/avatars/6ba7b810-9dad-11d1-80b4-00c04fd430c8 \
  -H "x-api-key: fm_your_key_here" \
  -F "name=Support Agent v2" \
  -F "image=@/path/to/new-headshot.jpg"

Replacing the source image updates image_url and increments image_version. If replacement fails, the previous image remains usable. Renaming or changing metadata alone does not increment image_version. If another image update completes first, the request returns 409 AVATAR_IMAGE_CONFLICT. Reload the avatar and retry rather than overwriting the newer image. Only avatars your account owns can be updated (AVATAR_NOT_FOUND otherwise). Rate limited to 5 requests per minute per key.

Authorizations

x-api-key

string

header

required

FaceMode API key (fm_...).

Path Parameters

string<uuid>

required

Avatar ID (UUID).

Body

multipart/form-data

image

file

Replacement source image (image/*, max 5 MB). Replacing the image re-queues idle video generation.

name

string

config

string

Optional JSON-encoded configuration object.

isActive

enum<string>

Available options:

true,

false

Response

Updated avatar record.

Avatar record with its source image and render readiness.

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>

API Reference

Sessions

Avatars

API Keys

Authorizations

Path Parameters

Body

Response