Try Seedance 2.5 in fal Agent
Docs
Log-inSign-up

mirage-api/avatar-x/reference-to-video

The Avatar X API offers access to Mirage's most advanced generation model yet, delivering industry-leading identity preservation and expressivity in AI video
Inference
Commercial use
Partner
Schema
LLMs
PlaygroundAPI

Table of contents

About

Create a talking video from a reference visual and driving audio.

Quick start

  1. Upload or paste a public URL into Video reference.
  2. Upload or paste a public URL into Audio.
  3. Select Run. The output follows the audio's words, timing, and performance.
{
"video_reference_url": "https://example.com/reference.mp4",
"audio_url": "https://example.com/dialogue.mp3"
}

Use a reference image or stock avatar instead

To use an image, leave the video reference empty and provide an image reference. If both are supplied, the video reference is used and the image reference is ignored. To use a stock avatar as the visual instead, clear both reference fields and choose Avatar under additional settings. Audio is always required and always supplies the output audio. If an Avatar and an image or video reference are both supplied, the visual reference overrides the Avatar.

{
"image_reference_url": "https://example.com/reference.png",
"audio_url": "https://example.com/dialogue.wav"
}

Supported URL file types

  • Audio: .mp3, .wav, .aif, .aiff, .aifc, .m4a, .mp4, .aac, .ogg, .oga, .opus, .webm, .weba, .flac
  • Images: .jpg, .jpeg, .png, .webp
  • Videos: .mp4, .mov, .m4v, .webm

If an audio file type is not offered in the upload picker, paste a public HTTPS URL instead.

Reference visuals must be close to 9:16 or 16:9. Audio can be 3-180 seconds; video references can be 1-120 seconds.

Common mistakes

  • If Image reference and Video reference are both supplied, the video reference is used and the image reference is ignored.
  • None sends no avatar. If neither visual reference is supplied, choose a stock Avatar under additional settings.
  • An image or video reference takes precedence over Avatar.
  • A video reference's audio track is ignored; Audio is still required.
  • URL inputs must be public HTTPS URLs that work without cookies or request headers.

The result is one lip-synced MP4 video. Its duration follows the driving audio.

1. Calling the API#

Install the client#

The client provides a convenient way to interact with the model API.

npm install --save @fal-ai/client

Setup your API Key#

Set FAL_KEY as an environment variable in your runtime.

export FAL_KEY="YOUR_API_KEY"

Submit a request#

The client API handles the API submit protocol. It will handle the request status updates and return the result when the request is completed.

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

const result = await fal.subscribe("mirage-api/avatar-x/reference-to-video", {
  input: {
    audio_url: "https://v3b.fal.media/files/b/0aa596e6/ko0yoMiCNRRAnMU5PQAHK_mirage-avatar-x-luke-reference-audio.wav"
  },
  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);

2. Authentication#

The API uses an API Key for authentication. It is recommended you set the FAL_KEY environment variable in your runtime when possible.

API Key#

In case your app is running in an environment where you cannot set environment variables, you can set the API Key manually as a client configuration.
import { fal } from "@fal-ai/client";

fal.config({
  credentials: "YOUR_FAL_KEY"
});

3. Queue#

Submit a request#

The client API provides a convenient way to submit requests to the model.

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

const { request_id } = await fal.queue.submit("mirage-api/avatar-x/reference-to-video", {
  input: {
    audio_url: "https://v3b.fal.media/files/b/0aa596e6/ko0yoMiCNRRAnMU5PQAHK_mirage-avatar-x-luke-reference-audio.wav"
  },
  webhookUrl: "https://optional.webhook.url/for/results",
});

Fetch request status#

You can fetch the status of a request to check if it is completed or still in progress.

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

const status = await fal.queue.status("mirage-api/avatar-x/reference-to-video", {
  requestId: "764cabcf-b745-4b3e-ae38-1200304cf45b",
  logs: true,
});

Get the result#

Once the request is completed, you can fetch the result. See the Output Schema for the expected result format.

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

const result = await fal.queue.result("mirage-api/avatar-x/reference-to-video", {
  requestId: "764cabcf-b745-4b3e-ae38-1200304cf45b"
});
console.log(result.data);
console.log(result.requestId);

4. Files#

Some attributes in the API accept file URLs as input. Whenever that's the case you can pass your own URL or a Base64 data URI.

Data URI (base64)#

You can pass a Base64 data URI as a file input. The API will handle the file decoding for you. Keep in mind that for large files, this alternative although convenient can impact the request performance.

Hosted files (URL)#

You can also pass your own URLs as long as they are publicly accessible. Be aware that some hosts might block cross-site requests, rate-limit, or consider the request as a bot.

Uploading files#

We provide a convenient file storage that allows you to upload files and use them in your requests. You can upload files using the client API and use the returned URL in your requests.

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

const file = new File(["Hello, World!"], "hello.txt", { type: "text/plain" });
const url = await fal.storage.upload(file);

Read more about file handling in our file upload guide.

5. Schema#

Input#

audio_url string* required

Publicly fetchable HTTPS URL of the driving audio; no cookies or authorization headers. Supports MP3, PCM WAV or AIFF, AAC or ALAC, Opus or Vorbis, and FLAC audio from 3 to 180 seconds and up to 64 MiB, with one mono or stereo stream sampled from 8 to 48 kHz. The generated video follows this audio.

video_reference_url string

Publicly fetchable HTTPS URL of the reference video; no cookies or authorization headers. Takes precedence over image_reference_url when both are supplied. 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 exactly one video stream and a 9:16 or 16:9 display aspect ratio (within 5%). The video must contain a usable one-second reference window; any audio track is ignored.

avatar Enum

Stock visual that can be used instead of an image or video reference; it does not supply audio. Browse the actor catalog to preview the available visuals and copy the exact Avatar value. Default and None both mean no avatar. Any supplied image or video reference overrides the selection, and audio always comes from audio_url.

Possible enum values: None, Ayesha, Ayesha (16:9), Diane (News), Farhan, Farhan (16:9), Giulia, Giulia (16:9), Jasmine, Jasmine (16:9), Luke, Luke (16:9), Marcus (News), Maya, Maya (16:9), Michael, Michael (16:9), Neha, Neha (16:9), Stephanie (News), Tariq, Tariq (16:9), Tom (News), Valerie, Valerie (16:9)

image_reference_url string

Publicly fetchable HTTPS URL of the reference image; no cookies or authorization headers. Ignored when video_reference_url is also supplied. Supports one static .jpg, .jpeg, .png, or .webp image up to 25 MiB, with a short edge of at least 512 px, no edge over 8192 px, at most 25 megapixels, and a 9:16 or 16:9 aspect ratio (within 5%).

{
  "audio_url": "https://v3b.fal.media/files/b/0aa596e6/ko0yoMiCNRRAnMU5PQAHK_mirage-avatar-x-luke-reference-audio.wav",
  "video_reference_url": "https://v3b.fal.media/files/b/0aa596d5/q8taheXQ-KlmtoC-uKViG_mirage-avatar-x-luke-reference-to-video-demo.mp4"
}

Output#

video Video* required
{
  "video": {
    "file_size": 11833398,
    "content_type": "video/mp4",
    "url": "https://v3b.fal.media/files/b/0aa596d5/q8taheXQ-KlmtoC-uKViG_mirage-avatar-x-luke-reference-to-video-demo.mp4",
    "file_name": "mirage-avatar-x-luke-reference-to-video-demo.mp4"
  }
}

Other types#

Video#

url string* required

The URL where the file can be downloaded from.

content_type string

The mime type of the file.

file_name string

The name of the file. It will be auto-generated if not provided.

file_size integer

The size of the file in bytes.

Related Models