fal-ai/vidu/q2/reference-to-image

Vidu Reference-to-Image creates images by using a reference image and combining it with a prompt.

Inference

Commercial use

Partner

Schema

LLMs

Playground

API

Table of contents

1. Calling the API
   • Install the client
   • Setup your API Key
   • Submit a request
2. Authentication
   • API Key
3. Queue
   • Submit a request
   • Fetch request status
   • Get the result
4. Files
   • Data URI (base64)
   • Hosted files (URL)
   • Uploading files
5. Schema
   • Input
   • Output
   • Other

About

Reference To Image Q2

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("fal-ai/vidu/q2/reference-to-image", {
  input: {
    prompt: "The little devil is looking at the apple on the beach and walking around it.",
    reference_image_urls: [
      "https://storage.googleapis.com/falserverless/web-examples/vidu/new-examples/reference1.png",
      "https://storage.googleapis.com/falserverless/web-examples/vidu/new-examples/reference2.png",
      "https://storage.googleapis.com/falserverless/web-examples/vidu/new-examples/reference3.png"
    ]
  },
  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, make sure to not expose your FAL_KEY. Instead, use a server-side proxy to make requests to the API.

3. Queue

Long-running requests

For long-running requests, it is recommended to check the Queue status and rely on Webhooks instead of blocking while waiting for the result.

Submit a request

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

const { request_id } = await fal.queue.submit("fal-ai/vidu/q2/reference-to-image", {
  input: {
    prompt: "The little devil is looking at the apple on the beach and walking around it.",
    reference_image_urls: [
      "https://storage.googleapis.com/falserverless/web-examples/vidu/new-examples/reference1.png",
      "https://storage.googleapis.com/falserverless/web-examples/vidu/new-examples/reference2.png",
      "https://storage.googleapis.com/falserverless/web-examples/vidu/new-examples/reference3.png"
    ]
  },
  webhookUrl: "https://optional.webhook.url/for/results",
});

Fetch request status

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

const status = await fal.queue.status("fal-ai/vidu/q2/reference-to-image", {
  requestId: "764cabcf-b745-4b3e-ae38-1200304cf45b",
  logs: true,
});

Get the result

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

const result = await fal.queue.result("fal-ai/vidu/q2/reference-to-image", {
  requestId: "764cabcf-b745-4b3e-ae38-1200304cf45b"
});
console.log(result.data);
console.log(result.requestId);

4. Files

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 can impact request performance.

Hosted files (URL)

You can also pass your own URLs as long as they are publicly accessible.

Uploading files

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

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

5. Schema

Input

• prompt (string) required
  • Text prompt for video generation, max 1500 characters.
• reference_image_urls (list) required
  • URLs of the reference images for consistent subject appearance.
• aspect_ratio (AspectRatioEnum)
  • The aspect ratio of the output video. Default value: "16:9".
  • Possible enum values: 16:9, 9:16, 1:1
• seed (integer)

Example Input JSON

{
  "prompt": "The little devil is looking at the apple on the beach and walking around it.",
  "reference_image_urls": [
    "https://storage.googleapis.com/falserverless/web-examples/vidu/new-examples/reference1.png",
    "https://storage.googleapis.com/falserverless/web-examples/vidu/new-examples/reference2.png",
    "https://storage.googleapis.com/falserverless/web-examples/vidu/new-examples/reference3.png"
  ],
  "aspect_ratio": "16:9"
}

Output

• image (Image) required
  • The edited image.

Example Output JSON

{
  "image": {
    "url": "https://storage.googleapis.com/falserverless/model_tests/video_models/general-1-2025-09-09T10_20_19Z.png"
  }
}

Other types

• StartEndToVideoRequest
• Q2VideoExtensionRequest
• Q1ReferenceToVideoRequest
• Q3ReferenceToVideoRequest

Image

• url (string) required
  • The URL where the file can be downloaded from.

hCaptcha

Please try again.