# Avatar X

> The Avatar X API offers access to Mirage's most advanced generation model yet, delivering
industry-leading identity preservation and expressivity in AI video


## Overview

- **Endpoint**: `https://fal.run/mirage-api/avatar-x/text-to-video`
- **Model ID**: `mirage-api/avatar-x/text-to-video`
- **Category**: text-to-video
- **Kind**: inference
**Tags**: avatar, lipsync, talking-head



## Pricing

- **Price**: $0.3 per seconds

For more details, see [fal.ai pricing](https://fal.ai/pricing).

## API Information

This model can be used via our HTTP API or more conveniently via our client libraries.
See the input and output schema below, as well as the usage examples.


### Input Schema

The API accepts the following input parameters:


- **`script`** (`string`, _required_):
  Use 50 to 1,500 characters. The 50-character minimum typically produces about four seconds of speech. Generated speech must be 180 seconds or shorter; speaking pace may cause shorter scripts to exceed this limit.
  - Examples: "Put in a script, and Mirage Avatar X turns it into a clear, expressive video. Let’s bring your next idea to life."

- **`avatar`** (`Enum`, _optional_):
  Stock visual and voice. Browse the [avatar catalog](https://captions.ai/help/docs/api/actor-catalog) to preview every available avatar and copy the exact Avatar value. Select None to send no avatar. When video_reference_url and audio_reference_url are both supplied, the references replace the avatar entirely and it may be omitted. Default value: `Jasmine`
  - Default: `"Jasmine"`
  - Options: `"None"`, `"Ayesha"`, `"Ayesha (16:9)"`, `"Farhan"`, `"Farhan (16:9)"`, `"Giulia"`, `"Giulia (16:9)"`, `"Jasmine"`, `"Jasmine (16:9)"`, `"Luke"`, `"Luke (16:9)"`, `"Maya"`, `"Maya (16:9)"`, `"Michael"`, `"Michael (16:9)"`, `"Neha"`, `"Neha (16:9)"`, `"Tariq"`, `"Tariq (16:9)"`, `"Valerie"`, `"Valerie (16:9)"`

- **`video_reference_url`** (`string`, _optional_):
  Publicly fetchable HTTPS URL of a reference video. When supplied, audio_reference_url is also required and the selected avatar is ignored; no cookies or authorization headers. Supports H.264, H.265/HEVC, or ProRes in .mp4, .mov, or .m4v and VP8 or VP9 in .webm, from 1 to 120 seconds and up to 1 GiB, with a 9:16 or 16:9 display aspect ratio (within 5%). Any audio track is ignored.

- **`audio_reference_url`** (`string`, _optional_):
  Publicly fetchable HTTPS URL of a voice reference. When supplied, video_reference_url is also required and the selected avatar is ignored; no cookies or authorization headers. Supports MP3, PCM WAV or AIFF, AAC or ALAC, Opus or Vorbis, and FLAC audio from 10 to 180 seconds and up to 64 MiB, with one mono or stereo stream sampled from 8 to 48 kHz. Only the first 60 seconds are used.



**Required Parameters Example**:

```json
{
  "script": "Put in a script, and Mirage Avatar X turns it into a clear, expressive video. Let’s bring your next idea to life."
}
```

**Full Example**:

```json
{
  "script": "Put in a script, and Mirage Avatar X turns it into a clear, expressive video. Let’s bring your next idea to life.",
  "avatar": "Jasmine"
}
```


### Output Schema

The API returns the following output format:

- **`video`** (`Video`, _required_)
  - Examples: {"url":"https://v3b.fal.media/files/b/0aa596e6/n-l_tkXZNWU4rdTylTkMX_mirage-avatar-x-jasmine-text-to-video-demo.mp4","content_type":"video/mp4","file_name":"mirage-avatar-x-jasmine-text-to-video-demo.mp4","file_size":7338484}



**Example Response**:

```json
{
  "video": {
    "url": "https://v3b.fal.media/files/b/0aa596e6/n-l_tkXZNWU4rdTylTkMX_mirage-avatar-x-jasmine-text-to-video-demo.mp4",
    "content_type": "video/mp4",
    "file_name": "mirage-avatar-x-jasmine-text-to-video-demo.mp4",
    "file_size": 7338484
  }
}
```


## Usage Examples

### cURL

```bash
curl --request POST \
  --url https://fal.run/mirage-api/avatar-x/text-to-video \
  --header "Authorization: Key $FAL_KEY" \
  --header "Content-Type: application/json" \
  --data '{
     "script": "Put in a script, and Mirage Avatar X turns it into a clear, expressive video. Let’s bring your next idea to life."
   }'
```

### Python

Ensure you have the Python client installed:

```bash
pip install fal-client
```

Then use the API client to make requests:

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "mirage-api/avatar-x/text-to-video",
    arguments={
        "script": "Put in a script, and Mirage Avatar X turns it into a clear, expressive video. Let’s bring your next idea to life."
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

### JavaScript

Ensure you have the JavaScript client installed:

```bash
npm install --save @fal-ai/client
```

Then use the API client to make requests:

```javascript
import { fal } from "@fal-ai/client";

const result = await fal.subscribe("mirage-api/avatar-x/text-to-video", {
  input: {
    script: "Put in a script, and Mirage Avatar X turns it into a clear, expressive video. Let’s bring your next idea to life."
  },
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS") {
      update.logs.map((log) => log.message).forEach(console.log);
    }
  },
});
console.log(result.data);
console.log(result.requestId);
```


## Additional Resources

### Documentation

- [Model Playground](https://fal.ai/models/mirage-api/avatar-x/text-to-video)
- [API Documentation](https://fal.ai/models/mirage-api/avatar-x/text-to-video/api)
- [OpenAPI Schema](https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=mirage-api/avatar-x/text-to-video)

### fal.ai Platform

- [Platform Documentation](https://fal.ai/docs/documentation)
- [Python Client](https://fal.ai/docs/api-reference/client-libraries/python)
- [JavaScript Client](https://fal.ai/docs/api-reference/client-libraries/javascript)

### Other agent-readable surfaces

This file covers one model. To find anything else:

- [Platform overview](https://fal.ai/llms.txt): Entry points and representative endpoint IDs
- [Documentation index](https://fal.ai/docs/llms.txt): Every documentation page
- [Full documentation text](https://fal.ai/docs/llms-full.txt): The whole documentation inlined
- Any other model: `https://fal.ai/models/<endpoint-id>/llms.txt`