# 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](#calling-the-api)
    - [Install the client](#install-the-client)
    - [Setup your API Key](#setup-your-api-key)
    - [Submit a request](#submit-a-request)
2. [Authentication](#authentication)
    - [API Key](#api-key)
3. [Queue](#queue)
    - [Submit a request](#submit-a-request-1)
    - [Fetch request status](#fetch-request-status)
    - [Get the result](#get-the-result)
4. [Files](#files)
    - [Data URI (base64)](#data-uri-base64)
    - [Hosted files (URL)](#hosted-files-url)
    - [Uploading files](#uploading-files)
5. [Schema](#schema)
    - [Input](#input)
    - [Output](#output)
    - [Other](#other-types)

## About

Reference To Image Q2

## 1. Calling the API

### Install the client

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

```bash
npm install --save @fal-ai/client
```

### Setup your API Key

Set `FAL_KEY` as an environment variable in your runtime.

```bash
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.

```javascript
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.

```javascript
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](/content/docs/documentation/model-apis/inference/queue/index.html) status and rely on [Webhooks](/content/docs/documentation/model-apis/inference/webhooks/index.html) instead of blocking while waiting for the result.

### Submit a request

```javascript
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

```javascript
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

```javascript
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

```javascript
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<string>)** *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

```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

```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.