> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom AI avatars

> Create private avatars from a photo or webcam.

In the widget editor, choose **Avatar → Choose avatar → My avatars → Create custom avatar**. Enter a name and upload a photo or use your webcam.

Use a sharp square JPEG, PNG or WebP image up to **4.5 MB**, ideally at least **1152 × 1152** pixels, with room around the head and shoulders. Confirm that you have the rights and permission to use it.

Creation has a **one-time credit price**, shown before confirmation. Credits are reserved while processing and charged once after success. Definite failures release the reservation. An uncertain result stays in processing while it is checked; reuse the same request ID instead of starting another paid creation. If no result can be confirmed within 24 hours, the reservation is released and any late result is deleted. Stored avatars have no recurring storage charge. Live avatar usage is billed separately.

If credits are insufficient, an enabled saved automatic top-up rule is tried using its existing payment terms. Otherwise choose **Add credits**, then refresh the balance and retry. A top-up payment must be credited to the workspace before creation can proceed.

New custom avatars are private to the workspace that creates them. The shared avatar library shows the avatars available to your workspace. In **My avatars**, select a ready avatar and confirm with **Use avatar**, just like in the avatar library. To delete an avatar, use the trash icon on its picture, after selecting another avatar in every widget using it. Deletion does not refund creation credits.

In **Choose avatar**, use the **Style** filter to narrow the avatar library. Select **Custom** or choose a named style available to your workspace.

## API, MCP, CLI and SDK

The catalog returns `styles` on every page. Pass an exact value from that list as `style` to filter the next request.

REST: `GET /api/v1/avatars/capability`, `POST /api/v1/avatars/uploads`, `POST /api/v1/avatars`, `GET /api/v1/avatars`, `GET /api/v1/avatars/{id}`, `DELETE /api/v1/avatars/{id}`, `GET /api/v1/avatars/catalog`.

MCP: `get_avatar_capability`, `create_avatar_upload`, `submit_avatar`, `list_avatars`, `get_avatar`, `delete_avatar`, `list_avatar_catalog`.

```bash theme={null}
famulor get-avatar-capability
famulor create-avatar-upload --name "My avatar" --style custom \
  --content-type image/jpeg --size-bytes 123456
# Upload the photo to the returned upload_url before submitting.
famulor submit-avatar --id <prepared-id> --consent true --expected-credits <quoted-price>
famulor get-avatar <prepared-id>
famulor list-avatars
famulor list-avatar-catalog --style custom
famulor delete-avatar <avatar-id>
```

```typescript theme={null}
import { Famulor } from "famulor-sdk";
import { readFile } from "node:fs/promises";
const photo = new Blob([new Uint8Array(await readFile("photo.jpg"))], { type: "image/jpeg" });
const client = new Famulor({ apiKey: process.env.FAMULOR_API_KEY! });
const quote = await client.avatars.capability();
const upload = await client.avatars.prepareUpload({
  name: "My avatar", style: "custom",
  content_type: "image/jpeg", size_bytes: photo.size,
});
const form = new FormData();
form.append("", photo, "photo.jpg");
form.append("cacheControl", "0");
const uploaded = await fetch(upload.data.upload_url, {
  method: "PUT", headers: { "x-upsert": "false" }, body: form,
});
if (!uploaded.ok) throw new Error("Photo upload failed");
const avatar = await client.avatars.submit({
  id: upload.data.id, consent: true,
  expected_credits: quote.data.creation_credits,
});
const status = await client.avatars.get(avatar.data.id);
const catalog = await client.avatars.catalog({ style: "custom" });
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.