Build Avatar
After you have successfully generated an avatar image, it's time to build a custom avatar model using the image.
For those who familiar with image generation model, the avatar buliding process is kind of a model fine-tuning process. Mirako API took further steps to forge various dataset during the process to improve the quality of output generated from the model.
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 sessions with personalized characters (currently in beta)
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:
mirako avatar build -i path/to/your/portrait.jpg --name "My Custom Avatar"
The whole process will take substantial time, typically around 45 minutes. While the CLI tool will run until the avatar is built, the whole building process is run on Mirako servers, so you can stop the process at any time.
You can check the build status using the CLI:
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.
# 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
# Start building
avatar_id = build_avatar("My Custom Avatar", image_data)
Avatar building typically takes 2-5 minutes. Monitor progress by checking the avatar status:
import time
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=600):
"""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
- Aspect ratio: Wide 16:9 (to be compatible with Interative) or Square
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.
- Generating Images - Use your avatar to generate images with consistent appearance.
- Generating Talking Avatars - Create talking videos with your avatar.
- Create Interactive Session - Use your avatar in real-time interactive chat.