fal-ai/lyra-2/zoom

Lyra 2.0 is an image-to-video model that turns a single image into an explorable 3D-style video with camera-controlled motion.

Learn more about Lyra 2

Inference

Commercial use

Schema

LLMs

Playground API

About

Zoom

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

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.

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("fal-ai/lyra-2/zoom", {
  input: {
    image_url: "https://v3b.fal.media/files/b/0a972579/6NsCexuhSlD8gcFYlpr1K_00.png",
    prompt: "A slow, steady horizontal orbit of the camera around the scene, focusing on the two massive galleons. The scene is a frozen tableau: the turquoise water is glass-like and motionless, the canvas sails are rigid, and the distant clouds are fixed in the golden sky. Every element, from the foreground wooden barrels and coiled ropes to the intricate coastal architecture, remains perfectly still. The warm, late-afternoon sunlight and soft shadows are permanent. As the camera advances, more of the harbor's stone buildings and the ships' wooden hulls are revealed, maintaining identical textures and colors. The entire world is locked in a silent, breathless moment with zero object or environmental movement."
  },
  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"
});

Protect your API 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.

3. Queue#

Long-running requests

For long-running requests, such as training jobs or models with slower inference times, it is recommended to check the Queue status and rely on Webhooks instead of blocking while waiting for the result.

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("fal-ai/lyra-2/zoom", {
  input: {
    image_url: "https://v3b.fal.media/files/b/0a972579/6NsCexuhSlD8gcFYlpr1K_00.png",
    prompt: "A slow, steady horizontal orbit of the camera around the scene, focusing on the two massive galleons. The scene is a frozen tableau: the turquoise water is glass-like and motionless, the canvas sails are rigid, and the distant clouds are fixed in the golden sky. Every element, from the foreground wooden barrels and coiled ropes to the intricate coastal architecture, remains perfectly still. The warm, late-afternoon sunlight and soft shadows are permanent. As the camera advances, more of the harbor's stone buildings and the ships' wooden hulls are revealed, maintaining identical textures and colors. The entire world is locked in a silent, breathless moment with zero object or environmental movement."
  },
  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("fal-ai/lyra-2/zoom", {
  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("fal-ai/lyra-2/zoom", {
  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);

Auto uploads

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.

5. Schema#

Input#

image_url string* required

URL of the input image. Lyra-2 hallucinates a video that starts from this image and moves the camera along the requested trajectory.

prompt string* required

Text prompt describing the scene. Best results come from prompts

zoom_direction ZoomDirectionEnum

Whether to generate a zoom-in video (camera moves toward the subject), a zoom-out video (camera retreats), or a combined out-then-in video. Default value: "in"

Possible enum values: in, out, both

num_frames NumFramesEnum

Number of frames per direction. Each AR chunk produces 80 frames, and the loop emits an extra anchor frame at the start, so valid values are 81, 161, 241, 321, 401, 481. Default value: "81"

Possible enum values: 81, 161, 241, 321, 401, 481

zoom_in_trajectory ZoomInTrajectoryEnum

Camera-trajectory preset for the zoom-in direction. horizontal_zoom is a straight translation along the z-axis; horizontal_zoom_bend adds a slight arc; spiral produces a spiraling approach. Default value: "orbit_horizontal"

Possible enum values: horizontal_zoom, horizontal_zoom_bend, spiral, dolly_zoom, orbit_horizontal, back

zoom_in_strength float

Displacement scale for the zoom-in trajectory (relative to subject depth). Default value: 0.5

zoom_out_trajectory ZoomOutTrajectoryEnum

Camera-trajectory preset for the zoom-out direction. Default value: "horizontal_zoom"

Possible enum values: horizontal_zoom, horizontal_zoom_bend, spiral, dolly_zoom, orbit_horizontal, back

zoom_out_strength float

Displacement scale for the zoom-out trajectory. Default value: 1.5

resolution ResolutionEnum

Output resolution. 480p = 480x832, 720p = 720x1280. Higher resolutions take substantially longer to generate. Default value: "480p"

Possible enum values: 480p, 720p

use_dmd boolean

Enable the upstream DMD distillation LoRA and 4-step scheduler for much faster generation. Disable for the higher-quality default Lyra-2 sampling path. Default value: true

guidance_scale float

Classifier-free guidance scale. Default value: 5

num_inference_steps integer

Number of denoising steps per frame chunk. Ignored when use_dmd is enabled because the DMD scheduler uses a fixed 4-step schedule. Default value: 28

frames_per_second integer

Frame rate of the output video. Default value: 16

seed integer

Random seed for reproducibility. If not provided, a random seed is chosen.

{
  "image_url": "https://v3b.fal.media/files/b/0a972579/6NsCexuhSlD8gcFYlpr1K_00.png",
  "prompt": "A slow, steady horizontal orbit of the camera around the scene, focusing on the two massive galleons. The scene is a frozen tableau: the turquoise water is glass-like and motionless, the canvas sails are rigid, and the distant clouds are fixed in the golden sky. Every element, from the foreground wooden barrels and coiled ropes to the intricate coastal architecture, remains perfectly still. The warm, late-afternoon sunlight and soft shadows are permanent. As the camera advances, more of the harbor's stone buildings and the ships' wooden hulls are revealed, maintaining identical textures and colors. The entire world is locked in a silent, breathless moment with zero object or environmental movement.",
  "zoom_direction": "in",
  "num_frames": 81,
  "zoom_in_trajectory": "orbit_horizontal",
  "zoom_in_strength": 0.5,
  "zoom_out_trajectory": "horizontal_zoom",
  "zoom_out_strength": 1.5,
  "resolution": "480p",
  "use_dmd": true,
  "guidance_scale": 5,
  "num_inference_steps": 28,
  "frames_per_second": 16
}

Output#

video VideoFile* required

The generated MP4 video.

seed integer* required

The seed used for generation.

timings Timings

Per-stage timing breakdown (seconds).

{
  "video": {
    "content_type": "video/mp4",
    "url": "https://v3b.fal.media/files/b/0a972e2c/6ACGX02AxQXhC1t9BED4b_tmpoufr9iug.mp4"
  },
  "seed": 478163327,
  "timings": {
    "encode_s": 1.475144863128662,
    "zoom_in_s": 51.5847270488739
  }
}

Other types#

VideoFile#

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.

width integer

The width of the video

height integer

The height of the video

fps float

The FPS of the video

duration float

The duration of the video

num_frames integer

The number of frames in the video

fal-ai/lyra-2/zoom

Table of contents

1. Calling the API

2. Authentication

3. Queue

4. Files

5. Schema

About

1. Calling the API#

Install the client#

Migrate to @fal-ai/client

Setup your API Key#

Submit a request#

2. Authentication#

API Key#

Protect your API Key

3. Queue#

Long-running requests

Submit a request#

Fetch request status#

Get the result#

4. Files#

Data URI (base64)#

Hosted files (URL)#

Uploading files#

Auto uploads

5. Schema#

Input#

Output#

Other types#

VideoFile#