Avatars

The avatar system serves two distinct use cases:

1. Human Avatars: Transform team photos into consistent, stylized portraits
2. Agent Avatars: Generate visual representations for AI assistants and bots

Both types maintain Ontopix brand consistency through shared prompt styles and visual language.

Human Avatars

Multi-Reference System

Human avatars use a multi-reference approach for improved accuracy:

• Primary image (.1): Controls pose and composition
• Reference images (.2, .3, etc.): Improve facial feature accuracy

Photos are grouped by subject using the naming pattern: firstname.lastname.N.ext

Generation Process

1. Place original photos in brand/avatars/originals/
2. Name files following the pattern (e.g., john.doe.1.jpg, john.doe.2.jpg)
3. Run stylebook avatars humans generate
4. Find outputs in output/avatars/humans/

AI Agent Avatars

Agent Definitions

AI agents are defined in brand/avatars/agents.yaml with:

• Identity: Name, role, and description
• Personality: Traits and communication style
• Appearance: Physical characteristics for visualization
• Tags: Categories for filtering and organization

Generation Process

1. Define agents in brand/avatars/agents.yaml
2. Run stylebook avatars agents generate
3. Filter by agent: --agent oracle
4. Filter by tags: --tags core,knowledge

Prompt System

Prompt Structure

Prompts are organized in folders under brand/avatars/prompts/:

prompts/
├── humans/
│   └── ontopix/
│       ├── prompt.md      # Main prompt text
│       ├── examples/      # Reference images (optional)
│       └── positions.jpeg # Position guide (optional)
└── agents/
    └── ontopix/
        ├── prompt.md
        └── examples/

Prompt Components

• prompt.md: Main generation instructions (Jinja2 template)
• examples/: Reference images for style consistency
• positions.jpeg: Visual guide for pose/composition

Prompts support Jinja2 templating for dynamic content based on subject/agent data.

AI Models

Supported Models

Configuration

Models are configured in brand/avatars/config.yaml with:

• Quality settings (high, medium, low)
• Background handling (transparent, opaque)
• Aspect ratio (1:1 for avatars)
• Provider-specific options

Usage Guidelines

Photo Requirements (Humans)

For best results, source photos should:

• Be well-lit with neutral background
• Show clear facial features
• Have consistent lighting across references
• Be at least 512x512 pixels

Avatar Sizes

Generated avatars are 1024x1024 pixels by default. Use these sizes:

• Profile pictures: 256x256 or 512x512
• Thumbnails: 64x64 or 128x128
• Full display: 1024x1024

Consistency Tips

• Use the same prompt style across all avatars
• Maintain consistent model settings
• Review examples in the prompt folder for style guidance

Quick Links

• Team Avatars - Avatars for Ontopix team members
• AI Agent Avatars - Avatars for AI assistants
• Generating Avatars - CLI commands for avatar generation