Migrate to @fal-ai/client
The @fal-ai/serverless-client
package has been deprecated in favor of @fal-ai/client
. Please check the migration guide for more information.
Image To Video V1
The client provides a convenient way to interact with the model API.
npm install --save @fal-ai/client
The @fal-ai/serverless-client
package has been deprecated in favor of @fal-ai/client
. Please check the migration guide for more information.
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("fal-ai/minimax-video/image-to-video", {
input: {
prompt: "A stylish woman walks down a Tokyo street filled with warm glowing neon and animated city signage.",
image_url: "https://fal.media/files/elephant/8kkhB12hEZI2kkbU8pZPA_test.jpeg"
},
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("fal-ai/minimax-video/image-to-video", {
input: {
prompt: "A stylish woman walks down a Tokyo street filled with warm glowing neon and animated city signage.",
image_url: "https://fal.media/files/elephant/8kkhB12hEZI2kkbU8pZPA_test.jpeg"
},
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("fal-ai/minimax-video/image-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("fal-ai/minimax-video/image-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.
prompt
string
* requiredimage_url
string
* requiredURL of the image to use as the first frame
prompt_optimizer
boolean
Whether to use the model's prompt optimizer Default value: true
{
"prompt": "A stylish woman walks down a Tokyo street filled with warm glowing neon and animated city signage.",
"image_url": "https://fal.media/files/elephant/8kkhB12hEZI2kkbU8pZPA_test.jpeg",
"prompt_optimizer": true
}
The generated video
{
"video": {
"url": "https://fal.media/files/monkey/vNZqQV_WgC9MhoidClLyw_output.mp4"
}
}
text
string
* requiredText to convert to speech (max 5000 characters)
Voice configuration settings
Audio configuration settings
language_boost
Enum
Enhance recognition of specified languages and dialects
Possible enum values: Chinese, Chinese,Yue, English, Arabic, Russian, Spanish, French, Portuguese, German, Turkish, Dutch, Ukrainian, Vietnamese, Indonesian, Japanese, Italian, Korean, Thai, Polish, Romanian, Greek, Czech, Finnish, Hindi, auto
output_format
OutputFormatEnum
Format of the output content (non-streaming only) Default value: "hex"
Possible enum values: url, hex
Custom pronunciation dictionary for text replacement
prompt
string
* requiredprompt_optimizer
boolean
Whether to use the model's prompt optimizer Default value: true
List of pronunciation replacements in format ['text/(pronunciation)', ...]. For Chinese, tones are 1-5. Example: ['燕少飞/(yan4)(shao3)(fei1)']
prompt
string
* requiredText prompt for video generation. Camera movement instructions can be added using square brackets (e.g. [Pan left] or [Zoom in]). You can use up to 3 combined movements per prompt. Supported movements: Truck left/right, Pan left/right, Push in/Pull out, Pedestal up/down, Tilt up/down, Zoom in/out, Shake, Tracking shot, Static shot. For example: [Truck left, Pan right, Zoom in]. For a more detailed guide, refer https://sixth-switch-2ac.notion.site/T2V-01-Director-Model-Tutorial-with-camera-movement-1886c20a98eb80f395b8e05291ad8645
image_url
string
* requiredURL of the image to use as the first frame
prompt_optimizer
boolean
Whether to use the model's prompt optimizer Default value: true
prompt
string
* requiredprompt_optimizer
boolean
Whether to use the model's prompt optimizer Default value: true
url
string
* requiredThe 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.
text
string
* requiredText to convert to speech (max 5000 characters)
Voice configuration settings
Audio configuration settings
language_boost
Enum
Enhance recognition of specified languages and dialects
Possible enum values: Chinese, Chinese,Yue, English, Arabic, Russian, Spanish, French, Portuguese, German, Turkish, Dutch, Ukrainian, Vietnamese, Indonesian, Japanese, Italian, Korean, Thai, Polish, Romanian, Greek, Czech, Finnish, Hindi, auto
output_format
OutputFormatEnum
Format of the output content (non-streaming only) Default value: "hex"
Possible enum values: url, hex
Custom pronunciation dictionary for text replacement
prompt
string
* requiredsubject_reference_image_url
string
* requiredURL of the subject reference image to use for consistent subject appearance
prompt_optimizer
boolean
Whether to use the model's prompt optimizer Default value: true
sample_rate
SampleRateEnum
Sample rate of generated audio Default value: "32000"
Possible enum values: 8000, 16000, 22050, 24000, 32000, 44100
bitrate
BitrateEnum
Bitrate of generated audio Default value: "128000"
Possible enum values: 32000, 64000, 128000, 256000
format
FormatEnum
Audio format Default value: "mp3"
Possible enum values: mp3, pcm, flac
channel
ChannelEnum
Number of audio channels (1=mono, 2=stereo) Default value: "1"
Possible enum values: 1, 2
prompt
string
* requiredText prompt for image generation (max 1500 characters)
image_url
string
* requiredURL of the subject reference image to use for consistent character appearance
aspect_ratio
AspectRatioEnum
Aspect ratio of the generated image Default value: "1:1"
Possible enum values: 1:1, 16:9, 4:3, 3:2, 2:3, 3:4, 9:16, 21:9
num_images
integer
Number of images to generate (1-9) Default value: 1
prompt_optimizer
boolean
Whether to enable automatic prompt optimization
prompt
string
* requiredText prompt for video generation. Camera movement instructions can be added using square brackets (e.g. [Pan left] or [Zoom in]). You can use up to 3 combined movements per prompt. Supported movements: Truck left/right, Pan left/right, Push in/Pull out, Pedestal up/down, Tilt up/down, Zoom in/out, Shake, Tracking shot, Static shot. For example: [Truck left, Pan right, Zoom in]. For a more detailed guide, refer https://sixth-switch-2ac.notion.site/T2V-01-Director-Model-Tutorial-with-camera-movement-1886c20a98eb80f395b8e05291ad8645
prompt_optimizer
boolean
Whether to use the model's prompt optimizer Default value: true
prompt
string
* requiredText prompt for image generation (max 1500 characters)
aspect_ratio
AspectRatioEnum
Aspect ratio of the generated image Default value: "1:1"
Possible enum values: 1:1, 16:9, 4:3, 3:2, 2:3, 3:4, 9:16, 21:9
num_images
integer
Number of images to generate (1-9) Default value: 1
prompt_optimizer
boolean
Whether to enable automatic prompt optimization
voice_id
VoiceIdEnum
Predefined voice ID to use for synthesis Default value: "Wise_Woman"
Possible enum values: Wise_Woman, Friendly_Person, Inspirational_girl, Deep_Voice_Man, Calm_Woman, Casual_Guy, Lively_Girl, Patient_Man, Young_Knight, Determined_Man, Lovely_Girl, Decent_Boy, Imposing_Manner, Elegant_Man, Abbess, Sweet_Girl_2, Exuberant_Girl
custom_voice_id
string
Custom cloned voice ID. If provided, this will override the voice_id field.
speed
float
Speech speed (0.5-2.0) Default value: 1
vol
float
Volume (0-10) Default value: 1
pitch
integer
Voice pitch (-12 to 12)
emotion
Enum
Emotion of the generated speech
Possible enum values: happy, sad, angry, fearful, disgusted, surprised, neutral
english_normalization
boolean
Enables English text normalization to improve number reading performance, with a slight increase in latency
audio_url
string
* requiredURL of the input audio file for voice cloning. Should be at least 10 seconds long.
noise_reduction
boolean
Enable noise reduction for the cloned voice
need_volume_normalization
boolean
Enable volume normalization for the cloned voice
accuracy
float
Text validation accuracy threshold (0-1)