Mirako

Build Avatar

After you have successfully generated an avatar image, it's time to build a custom avatar model using the image.

Mirako prepares a 1280 × 720 portrait and generates two animation clips: idle for the avatar's resting motion and base for lip-sync animation. The current build does not generate listening or thinking clips.

Overview

Avatar building is an asynchronous process where you provide a clear portrait image as input. You can use the generated avatar image from the Generate Avatar guide. Mirako creates a custom avatar model that can be used for:

  • Image and video generation with consistent appearance
  • Interactive agents with personalized characters

Quality Guidelines

Input images must meet the following quality requirements to ensure the best results:

  • Clear frontal face: Subject looking directly at camera
  • Good lighting: Even lighting without harsh shadows
  • Minimal background: Simple, uncluttered background
  • Single person: Only one face in the image
  • High resolution: Sharp, not blurry or pixelated

❌ Avoid:

  • Multiple people in frame
  • Side profiles or angled faces
  • Heavy makeup or face paint
  • Sunglasses or face coverings
  • Dark or heavily shadowed images

Building Your First Avatar

To build your avatar, you can use the Mirako CLI tool:

sh
mirako avatar build -i path/to/your/portrait.jpg --name "My Custom Avatar"

Note: A recent two-clip build reached READY in about 11 minutes. This is a measured example, not a guaranteed completion time; server load affects the wait. The build runs on Mirako servers, so you can stop the CLI and check progress later without restarting it.

You can check the build status using the CLI:

sh
mirako avatar view <avatar_id>
# or use the list command to see all avatars
mirako avatar list

Avatar Status

Avatars go through different states during creation and processing:

  • PENDING: Avatar creation request has been received
  • BUILDING: Avatar is being processed and built
  • READY: Avatar is complete and ready to use
  • ERROR: Something went wrong during avatar creation

Avatar creation is an asynchronous process. Newly created avatars will start in PENDING status and transition to BUILDING, then READY when complete.

Using API

Alternatively, you can build avatars using the Mirako API.

The API requires you to upload the image to our server, encoded in Base64 format for transport.

Below shows a complete example of how to build an avatar using the API.

python
import base64
import requests
import time

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

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

def build_avatar(name, image_data):
    """Start avatar building process"""
    
    payload = {
        "name": name,
        "image": image_data # std Base64 encoded image data
    }
    
    response = requests.post(
        f"{BASE_URL}/v1/avatar/async_build",
        headers=headers,
        json=payload
    )
    
    if response.status_code == 200:
        result = response.json()
        avatar_id = result['data']['avatar_id']
        print(f"✅ Avatar build started!")
        print(f"Avatar ID: {avatar_id}")
        return avatar_id
    else:
        print(f"❌ Error: {response.status_code}")
        print(response.text)
        return None

# Read a JPEG or PNG portrait and encode it for the request
with open("portrait.jpg", "rb") as portrait:
    image_data = base64.b64encode(portrait.read()).decode("ascii")

# Start building
avatar_id = build_avatar("My Custom Avatar", image_data)

Monitor progress until the avatar reaches READY or ERROR; the build-time example above is not a timeout limit:

python
def check_avatar_status(avatar_id):
    """Check avatar building status"""
    
    response = requests.get(
        f"{BASE_URL}/v1/avatar/{avatar_id}",
        headers=headers
    )
    
    if response.status_code == 200:
        avatar = response.json()['data']
        status = avatar['status']
        
        print(f"Avatar Status: {status}")
        
        if status == "READY":
            print("🎉 Avatar is ready!")
            print(f"Name: {avatar['name']}")
            print(f"Created: {avatar['created_at']}")
            return {"status": "ready", "avatar": avatar}
        
        elif status == "BUILDING":
            print("🔨 Avatar is being built...")
            return {"status": "building"}
        
        elif status == "PENDING":
            print("⏳ Avatar is in queue...")
            return {"status": "pending"}
        
        elif status == "ERROR":
            print("❌ Avatar build failed")
            return {"status": "error"}
        
        else:
            print(f"Unknown status: {status}")
            return {"status": "unknown"}
    else:
        print(f"Error checking status: {response.status_code}")
        return {"status": "error"}

def wait_for_avatar_completion(avatar_id, max_wait_time=3600):
    """Wait for avatar to complete building"""
    
    start_time = time.time()
    
    while time.time() - start_time < max_wait_time:
        result = check_avatar_status(avatar_id)
        
        if result["status"] == "ready":
            return result["avatar"]
        elif result["status"] == "error":
            return None
        
        # Wait 10 seconds before next check
        time.sleep(10)
    
    print("⏰ Timeout: Avatar didn't complete within time limit")
    return None

# Wait for completion
if avatar_id:
    avatar = wait_for_avatar_completion(avatar_id)
    
    if avatar:
        print("Avatar built successfully!")
        print(f"Themes available: {len(avatar.get('themes', []))}")
    else:
        print("Avatar build failed or timed out")

Using Custom Portrait Images

You can also build avatars from your own portrait images.

  • Formats: JPG, PNG
  • Minimum size: 512x512 pixels
  • Maximum file size: 10MB
  • Recommended framing: Landscape 16:9, with the entire head visible and space above the hair
  • Prepared portrait and video size: 1280 × 720 pixels

Mirako resizes and center-crops your image to 1280 × 720. Square or portrait images lose part of the top and bottom, so check that the face and hair fit within a landscape crop before submitting.

Note: Make sure you have the rights to use the image for avatar building, and it meets all the requirements as stated in our terms. Our team will review any built models to ensure the compliance with our policies, and take down any models that violate our terms.

Going Next

Now you have successfully built your first avatar! You can now explore the possibilities of using your avatar in various applications.

Dive Deeper

Previous
Generate Avatar
Next
Manage Your Avatars