Get started with avatar generation using Avatar X

Generate lifelike avatar videos from audio with the Mirage Avatar X API. Send an audio clip and reference image to get 720p MP4 output in minutes.

Overview

Avatar X is Mirage’s avatar generation model, built for identity preservation and expressivity. Send audio and an optional visual reference to a single multipart endpoint, and get back a video of that person speaking.

It’s designed for the details that usually break in avatar video: keeping a face and likeness recognizably consistent across a full segment, not just a few seconds, while carrying the emotion, laughter, micro-expressions, and subtle nonverbal movement that make someone feel real.

Driving audio is 1–60 seconds per request. Output is a 720p MP4 in 9:16 or 16:9, with most generations completing in under two minutes. For longer videos, developers can generate multiple segments and join them together.

Every output includes non-removable provenance metadata. Reference media is used only for that request and is not retained as a reusable identity.

Prerequisites

Create an API key in the platform dashboard.

1) Create a video

Use one of these input modes:

• Provide image_reference with audio_reference.
• Provide video_reference with audio_reference. Image and video references are mutually exclusive.

Image reference

Python

import requests

url = "https://api.mirage.app/v1/videos"
headers = {
    "x-api-key": "<api-key>"
}
files = {
    "image_reference": open("portrait.jpg", "rb"),
    "audio_reference": open("voice.mp3", "rb")
}
data = {
    "model": "mirage-avatar-x"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

Video reference

Python

import requests

url = "https://api.mirage.app/v1/videos"
headers = {
    "x-api-key": "<api-key>"
}
files = {
    "video_reference": open("reference.mp4", "rb"),
    "audio_reference": open("voice.mp3", "rb")
}
data = {
    "model": "mirage-avatar-x"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

Response (example)

{
  "id": "video_abc123def456",
  "object": "video",
  "completed_at": 1730822520,
  "created_at": 1730822400,
  "model": "mirage-avatar-x",
  "progress": 100,
  "status": "COMPLETE",
  "error": null
}

2) Check job status

Poll until status becomes COMPLETE.

Python

import requests

url = f"https://api.mirage.app/v1/videos/{video_id}"
headers = {
    "x-api-key": "<api-key>"
}

response = requests.get(url, headers=headers)

Status values

• PROCESSING
• COMPLETE
• FAILED
• CANCELLED

3) Download the video (follow redirect)

Once a video status is COMPLETE, it is available for download. The content endpoint returns an HTTP redirect to the final video URL.

Python

import requests

url = f"https://api.mirage.app/v1/videos/{video_id}/content"
headers = {
    "x-api-key": "<api-key>"
}

response = requests.get(url, headers=headers, allow_redirects=True)

with open("output.mp4", "wb") as f:
    f.write(response.content)

Your generated video is now saved as output.mp4.

Tips for best results

• Use a clear, front-facing portrait with good lighting and a single subject. Make sure the face is clear, mouth is open, and the subject is oriented in a close to medium shot to ensure natural alignment with the voice.
• Avoid images with closed mouths or multiple people in the frame.
• Use expressive, realistic, sounding audio. Results tend to look worse if the audio is audibly “AI”.

API reference

• Create video
• Retrieve Video
• Retrieve Video Content
• List Videos