Skip to main content

​
Overview

Mirage Video is a video model purpose-built for human realism. Given a single image and an audio clip, Mirage can create expressive, lifelike videos that capture subtle facial motion, emotion, and speech synchronization with remarkable fidelity. Trained on diverse human imagery, Mirage understands how faces move, how voices shape expression, and how small details make people feel real on screen. The Mirage Video API exposes this capability to developers via simple endpoints:
  • Create video — Start a new video generation from an image and audio pair.
  • Retrieve video — Retrieve the current state of a video generation job and track its progress.
  • Retrieve video content — Fetch the final MP4 once the job is complete.
  • List videos — Access your recent video generations.

​
Prerequisites

Create an API key in the platform dashboard.

​
1) Create a Video

Provide a portrait image (JPEG/PNG) and speech audio (WAV/MP3). 
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-video-1-latest"
}

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-video-1-latest",
  "progress": 100,
  "status": "COMPLETE",
  "error": null
}

​
2) Check Job Status

Poll until status becomes COMPLETE. 
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. 
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