> ## 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.

Custom avatars belong to the active workspace. Team members in that workspace can use them; other workspaces cannot browse or select them. Stock avatars remain shared. In **My avatars**, select **Use avatar** once it is ready. To delete an avatar, first select another avatar in every widget using it. Deletion does not refund creation credits.

## API, MCP, CLI and SDK

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 realistic
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);
```


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