Generate Your First Avatar
Generating avatar images is one of the most exciting features of Mirako. You can describe the appearance you want in natural language, and let Mirako's AI service generate a realistic avatar.
As with any AI-generated content, the quality of the output may varies and may not always match your expectations. You are suggest to experiment with multiple trials with the same prompt, or try tweaking the prompt to get the desired results.
Quick Start
You can start generating avatars right away using the Mirako CLI tool in your local terminal.
mirako avatar generate -p "A realistic photo of an Asian woman with long black hair, wearing blue business attire, almond-shaped brown eyes, against a clean white background" -o ./avatar.jpg
The -p flag specifies the text prompt describing the avatar appearance. The CLI waits while the image is generated, then saves it to your current directory. We recommend passing -o/--output as above so you know the exact file path — you will need it in the next step, Build Avatar. Other useful flags are -n/--no-save (skip saving the image), -i/--poll-interval (status polling interval in seconds, default 2). Run mirako avatar generate --help for the full list. Do not pass --seed; avatar generation no longer supports seeds.
If the CLI reports an error while checking the task status, do not immediately submit another generation — generation is a paid request, and your original task may still complete. Note the task ID and check it again with the status command described in Checking Generation Status.
Image Format
Mirako returns a 1280 × 720 JPEG image, matching the 16:9 portrait and video dimensions used during avatar building.
Note: Generating again with the same prompt can produce a different image. The current avatar generation model does not support seeds. Omit
seedin API requests; nonzero values are rejected.
Generate Avatar Using API
You can also integrate avatar generation into your applications using the Mirako API. The Python examples on this page use the requests library — install it first with pip install requests if you don't have it.
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 generate_avatar(prompt):
"""Generate an avatar from a text prompt"""
payload = {
"prompt": prompt
}
response = requests.post(
f"{BASE_URL}/v1/avatar/async_generate",
headers=headers,
json=payload
)
if response.status_code == 200:
result = response.json()['data']
task_id = result['task_id']
status = result['status']
print(f"✅ Avatar generation started")
print(f"📋 Task ID: {task_id}")
print(f"📊 Status: {status}")
return task_id
else:
print(f"❌ Error starting avatar generation: {response.status_code}")
print(response.text)
return None
# Generate your first avatar
task_id = generate_avatar(
"A realistic photo of Asian woman with long black hair, "
"round-shaped eyes, wearing a professional blue blazer, "
"standing against a clean white background"
)
Checking Generation Status
Like many other Mirako generative API, Avatar generation is an asynchronous process - you'll submit a generation request, receive a task ID, and then poll for the results. This allows you to generate multiple avatars simultaneously and check their progress.
In a recent production test, generation completed in about 21 seconds. This is a measured example, not a guaranteed completion time; server load can increase the wait. Keep your task ID so you can retrieve the result without paying for another generation.
From the CLI, check a task at any time with:
mirako avatar status <TASK_ID>
From the API, poll the status endpoint until the task reaches a terminal state. The task returns IN_PROGRESS while generating and COMPLETED on success or FAILED on failure.
def wait_for_avatar_generation(task_id, timeout_seconds=300, poll_interval=5):
"""Poll an avatar generation task until it completes, fails, or times out."""
deadline = time.time() + timeout_seconds
while time.time() < deadline:
response = requests.get(
f"{BASE_URL}/v1/avatar/async_generate/{task_id}/status",
headers=headers
)
if response.status_code != 200:
# A failed status check is not a failed generation. Wait and
# retry instead of submitting (and paying for) a new task.
print(f"⚠️ Status check failed: {response.status_code}, retrying...")
time.sleep(poll_interval)
continue
result = response.json()['data']
status = result['status']
print(f"📊 Status: {status}")
if status == "COMPLETED":
image_b64 = result.get('image')
if image_b64:
print(f"✅ Avatar generated successfully!")
print(f"📸 Image data: {len(image_b64)} characters (base64)")
return result
if status == "FAILED":
raise RuntimeError(f"Avatar generation failed: {result}")
if status not in ("IN_QUEUE", "IN_PROGRESS"):
raise RuntimeError(f"Unexpected task status: {status}")
time.sleep(poll_interval)
raise TimeoutError(
f"Generation did not complete within {timeout_seconds}s. "
f"Keep task ID {task_id} and check its status again later "
"instead of submitting a new generation."
)
# Wait for the generation started above
if task_id:
status_result = wait_for_avatar_generation(task_id)
Using Webhook
Alternatively, you can setup webhook to receive notifications when the avatar generation is complete.
def generate_avatar_with_webhook(prompt):
webhook_url = "https://mydomain.com/webhook" # Replace with your actual webhook URL
auth_token = "your_auth_token_here" # Optional auth token used for webhook authentication
payload = {
"prompt": prompt,
"webhook": {
"url": webhook_url,
"auth_token": auth_token
}
}
response = requests.post(
f"{BASE_URL}/v1/avatar/async_generate",
headers=headers,
json=payload
)
# read the response like before
Going Next
To generate an avatar that matches your preferences might take some experimentation with different prompts and parameters. Once you have obtained a satisfactory avatar, you can proceed with building it.