Create a talking video from a reference visual and driving audio.
{
"video_reference_url": "https://example.com/reference.mp4",
"audio_url": "https://example.com/dialogue.mp3"
}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"
}.mp3, .wav, .aif, .aiff, .aifc, .m4a, .mp4, .aac,
.ogg, .oga, .opus, .webm, .weba, .flac.jpg, .jpeg, .png, .webp.mp4, .mov, .m4v, .webmIf 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.
The result is one lip-synced MP4 video. Its duration follows the driving audio.
The client provides a convenient way to interact with the model API.
npm install --save @fal-ai/clientThe @fal-ai/serverless-client package has been deprecated in favor of @fal-ai/client. Install the new package and update your imports — see client setup.
Set FAL_KEY as an environment variable in your runtime.
export FAL_KEY="YOUR_API_KEY"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);The API uses an API Key for authentication. It is recommended you set the FAL_KEY environment variable in your runtime when possible.
import { fal } from "@fal-ai/client";
fal.config({
credentials: "YOUR_FAL_KEY"
});When running code on the client-side (e.g. in a browser, mobile app or GUI applications), make sure to not expose your FAL_KEY. Instead, use a server-side proxy to make requests to the API. For more information, check out our server-side integration guide.
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",
});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,
});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);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.
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.
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.
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);The client will auto-upload the file for you if you pass a binary object (e.g. File, Data).
Read more about file handling in our file upload guide.
audio_url string* requiredPublicly 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 stringPublicly 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 EnumStock visual that can be used instead of an image or video reference; it does not supply audio. Browse the avatar 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), 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)
image_reference_url stringPublicly 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"
}{
"video": {
"file_name": "mirage-avatar-x-luke-reference-to-video-demo.mp4",
"file_size": 11833398,
"url": "https://v3b.fal.media/files/b/0aa596d5/q8taheXQ-KlmtoC-uKViG_mirage-avatar-x-luke-reference-to-video-demo.mp4",
"content_type": "video/mp4"
}
}cancelled boolean* requiredreason EnumPossible enum values: missing_or_invalid_request_id, request_not_active, delivery_already_committed
message string* requiredurl string* requiredThe URL where the file can be downloaded from.
content_type stringThe mime type of the file.
file_name stringThe name of the file. It will be auto-generated if not provided.
file_size integerThe size of the file in bytes.