Controls and formats

Configuration controls#

All configuration fields are optional; omitted fields use the defaults below. Unknown fields are rejected.

format defaults to svg, and size defaults to 256. SVG and PNG accept integer sizes from 32 to 512. For GIF, explicitly set size between 32 and 128:

{
  "format": "gif",
  "size": 128,
  "config": { "accessory": "wizard", "expression": "happy" }
}

MCP GIFs contain 12 looping blink frames at 100 ms per frame, with a light background and reduced color palette. SVG and PNG have transparent backgrounds by default; set presentation.background for a solid background.

Use artifacts in your application#

The result's structuredContent includes the normalized configuration, format, size, MIME type, byte count, and SHA-256 checksum. The artifact is returned in content:

• SVG: embedded resource with the SVG string in resource.text.
• PNG: image block with base64 data in data.
• GIF: embedded resource with base64 data in resource.blob.

Decode the returned data and save it through your application's authorized storage layer. Retain the normalized configuration to regenerate the avatar later. An avatar://generated/... resource URI identifies the returned artifact; it is not a hosted download URL or a stored resource to fetch. The MCP server does not save files.

See the MCP guide for more details and the example client configuration.

Complete control API (npm 0.2.0+)#

import { configureAvatar, exportAvatar, avatarActions } from '@ai-calypse/avatar-studio';

// Attach the component before configuring it.
configureAvatar(avatar, {
  appearance: { bodyShape: 'random', shapeSeed: 42, antenna: true,
    accessory: 'headphones', matchEyes: true, eyes: '#dbf59d' },
  behavior: { pointerFollow: true, antennaFlash: true, loop: true,
    pressSqueeze: true, antennaDrag: true, motion: 'auto',
    wakeOn: 'interaction', autoSleep: 60000 },
  action: 'waiting-wrap'
});
const gif = await exportAvatar(avatar, { format: 'gif', size: 128,
  frames: 12, delay: 100,
  presentation: { frame: 'circle', status: 'online', padding: 4 } });
// Returns a Blob. Your app owns saving or uploading it.
console.log(avatarActions); // Every public action and alias.

configureAvatar accepts partial appearance/behavior updates and preserves previous settings. Antenna visibility is an appearance field; headwear can hide the antenna. Behavior switches default to pointer following and gestures enabled, antenna flash and expression looping disabled. Motion supports auto, reduce, full; wake policy supports activity, interaction, manual; auto-sleep is 0–86400000 ms (0 disables it). Looping waiting uses continuous waiting; other actions repeat after completing. Reset/cancellation clears queued repeats. Disconnecting prevents a queued repeat from starting. Explicit actions start asynchronously after runtime policies are applied.

exportAvatar supports SVG/PNG at 32–512 pixels and GIF at 32–256 pixels, 2–48 frames, 20–500 ms per frame. PNG keeps transparency by default; GIF uses a light background. Presentation supports background hex/transparent, none/circle/rounded framing, padding 0–24%, and none/online/away/busy/offline badges. background is a shorthand for a solid presentation background. GIF records the current live component; its image loop is independent of the expression-loop switch. No files, uploads, or network access are performed by these helpers.

Interactive movement and full action lifecycles run in a live browser component. An image file cannot follow a cursor. MCP's create_avatar_component returns validated npm integration code and normalized settings for those interactive use cases; it executes no code on the server. Website language selection affects the interface, not avatar geometry.