Manage Your Avatars

In case you would like to programmatically manage your avatars, this guide will illustrate how you can list, view, and delete your avatars using the Mirako API.

Listing Your Avatars

python

import requests

# API configuration
API_KEY = "your_api_key_here"
BASE_URL = "https://mirako.co"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

def list_avatars():
    """List all avatars for the current user"""
    
    response = requests.get(
        f"{BASE_URL}/v1/avatar/list",
        headers=headers
    )
    
    if response.status_code == 200:
        result = response.json()['data']
        
        if not result:
            print("📭 No avatars found. Create your first avatar to get started!")
            return []
        
        print(f"🎭 Found {len(result)} avatar(s):")
        
        for avatar in result:
            print(f"\n👤 Avatar: {avatar['name']}")
            print(f"   ID: {avatar['id']}")
            print(f"   Status: {avatar['status']}")
            print(f"   Created: {avatar['created_at']}")
            
            # Show available themes
            themes = avatar.get('themes', [])
            if themes:
                print(f"   Themes: {len(themes)} available")
                for i, theme in enumerate(themes):
                    print(f"     - {theme.get('name', f'Theme {i+1}')}")
            else:
                print(f"   Themes: No themes available")
        
        return result
    else:
        print(f"❌ Error listing avatars: {response.status_code}")
        print(response.text)
        return None

# List your avatars
avatars = list_avatars()

Getting a Specific Avatar

Once you have avatars, you can retrieve detailed information about a specific avatar:

python

def get_avatar_by_id(avatar_id):
    """Get detailed information about a specific avatar"""
    
    response = requests.get(
        f"{BASE_URL}/v1/avatar/{avatar_id}",
        headers=headers
    )
    
    if response.status_code == 200:
        avatar = response.json()['data']
        
        print(f"👤 Avatar Details:")
        print(f"   Name: {avatar['name']}")
        print(f"   ID: {avatar['id']}")
        print(f"   Status: {avatar['status']}")
        print(f"   Created: {avatar['created_at']}")
        
        # Display theme information with URLs
        themes = avatar.get('themes', [])
        if themes:
            print(f"\n🎨 Available Themes ({len(themes)}):")
            for theme in themes:
                print(f"   Theme: {theme.get('name', 'Default')}")
                if theme.get('key_image'):
                    print(f"     Portrait: {theme['key_image']}")
                if theme.get('live_video'):
                    print(f"     Live Video: {theme['live_video']}")
        
        return avatar
    else:
        print(f"❌ Error getting avatar: {response.status_code}")
        print(response.text)
        return None

# Get specific avatar details
# avatar_details = get_avatar_by_id("your_avatar_id_here")

Working with Avatar Themes

Each avatar can have multiple themes that represent different visual styles:

python

def display_avatar_themes(avatar_id):
    """Display all themes for an avatar with their assets"""
    
    avatar = get_avatar_by_id(avatar_id)
    
    if avatar and avatar.get('themes'):
        themes = avatar['themes']
        
        print(f"\n🎨 Avatar Themes for '{avatar['name']}':")
        
        for i, theme in enumerate(themes):
            theme_name = theme.get('name', f'Theme {i+1}')
            print(f"\n   Theme: {theme_name}")
            
            # Key portrait image
            if theme.get('key_image'):
                print(f"   📸 Portrait Image: {theme['key_image']}")
            
            # Live video for animations
            if theme.get('live_video'):
                print(f"   🎬 Live Video: {theme['live_video']}")
    else:
        print("No themes available for this avatar")

# Display themes for an avatar
# display_avatar_themes("your_avatar_id_here")

Note: Currently the Avatar theme system is under internal testing. Until it is fully released, you may see a default theme foreach avatar, which is the key portrait image and live video.

Deleting Avatars

When you no longer need an avatar, you can delete it permanently:

python

def delete_avatar(avatar_id):
    """Delete an avatar permanently"""
    
    response = requests.delete(
        f"{BASE_URL}/v1/avatar/{avatar_id}",
        headers=headers
    )
    
    if response.status_code == 204:
        print(f"✅ Avatar {avatar_id} deleted successfully")
        return True
    else:
        print(f"❌ Error deleting avatar: {response.status_code}")
        print(response.text)
        return False

# Delete an avatar (be careful - this is permanent!)
# success = delete_avatar("avatar_id_to_delete")

Dive Deeper

API Reference - Avatar