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

> Create expressive short-form talking-head videos from a portrait image and audio clip using the Mirage Video 1 generation API for lifelike human realism.

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

## 1) Create a video

Provide a portrait image (JPEG/PNG) and speech audio (WAV/MP3).

<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-video-1-latest"
  }

  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-video-1-latest");
  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-video-1-latest \
    --form image_reference=@portrait.jpg \
    --form audio_reference=@voice.mp3
  ```
</CodeGroup>

**Response (example)**

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

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