> ## Documentation Index
> Fetch the complete documentation index at: https://captions.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://platform.mirage.app/).

## 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

<CodeGroup>
  ```python Python theme={"system"}
  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())
  ```

  ```typescript TypeScript theme={"system"}
  const formData = new FormData();
  formData.append("model", "mirage-avatar-x");
  formData.append("image_reference", await fs.readFile("portrait.jpg"));
  formData.append("audio_reference", await fs.readFile("voice.mp3"));

  const response = await fetch("https://api.mirage.app/v1/videos", {
    method: "POST",
    headers: {
      "x-api-key": "<api-key>"
    },
    body: formData
  });

  const data = await response.json();
  console.log(data);
  ```

  ```bash cURL theme={"system"}
  curl --request POST \
    --url https://api.mirage.app/v1/videos \
    --header 'Content-Type: multipart/form-data' \
    --header 'x-api-key: <api-key>' \
    --form model=mirage-avatar-x \
    --form image_reference=@portrait.jpg \
    --form audio_reference=@voice.mp3
  ```
</CodeGroup>

### Video reference

<CodeGroup>
  ```python Python theme={"system"}
  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())
  ```

  ```typescript TypeScript theme={"system"}
  const formData = new FormData();
  formData.append("model", "mirage-avatar-x");
  formData.append("video_reference", await fs.readFile("reference.mp4"));
  formData.append("audio_reference", await fs.readFile("voice.mp3"));

  const response = await fetch("https://api.mirage.app/v1/videos", {
    method: "POST",
    headers: {
      "x-api-key": "<api-key>"
    },
    body: formData
  });

  const data = await response.json();
  console.log(data);
  ```

  ```bash cURL theme={"system"}
  curl --request POST \
    --url https://api.mirage.app/v1/videos \
    --header 'Content-Type: multipart/form-data' \
    --header 'x-api-key: <api-key>' \
    --form model=mirage-avatar-x \
    --form video_reference=@reference.mp4 \
    --form audio_reference=@voice.mp3
  ```
</CodeGroup>

**Response (example)**

```json theme={"system"}
{
  "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`.

<CodeGroup>
  ```python Python theme={"system"}
  import requests

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

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

  ```typescript TypeScript theme={"system"}
  const response = await fetch(`https://api.mirage.app/v1/videos/${videoId}`, {
    method: "GET",
    headers: {
      "x-api-key": "<api-key>"
    }
  });

  const data = await response.json();
  ```

  ```bash cURL theme={"system"}
  curl --request GET \
    --url https://api.mirage.app/v1/videos/{video_id} \
    --header 'x-api-key: <api-key>'
  ```
</CodeGroup>

**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.

<CodeGroup>
  ```python Python theme={"system"}
  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)
  ```

  ```typescript TypeScript theme={"system"}
  const response = await fetch(`https://api.mirage.app/v1/videos/${videoId}/content`, {
    method: "GET",
    headers: {
      "x-api-key": "<api-key>"
    },
    redirect: "follow"
  });
  ```

  ```bash cURL theme={"system"}
  curl --request GET \
    --url https://api.mirage.app/v1/videos/{video_id}/content \
    --header 'x-api-key: <api-key>' \
    --location \
    --output output.mp4
  ```
</CodeGroup>

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**](https://help.mirage.app/api-reference/videos/create-video)
* [**Retrieve Video**](https://help.mirage.app/api-reference/videos/retrieve-video)
* [Retrieve Video Content](https://help.mirage.app/api-reference/videos/retrieve-video-content)
* [**List Videos**](https://help.mirage.app/api-reference/videos/list-videos)