Place any product in any scenery with just a prompt or reference image while maintaining high integrity of the product. Trained exclusively on licensed data for safe and risk-free commercial use and optimized for eCommerce.

fal-ai/bria/product-shot

Inference

Commercial use

Partner

Schema

LLMs

Playground API

Loading API documentation…

fal-ai/bria/product-shot

Schema

LLMs

Loading API documentation…

fal-ai/bria/product-shot

Inference

Commercial use

Partner

Schema

LLMs

Playground API

1. Calling the API

2. Authentication

API Key

3. Queue

4. Files

5. Schema

About

Product Shot

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. Install the new package and update your imports — see client setup.

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/bria/product-shot", {
  input: {
    image_url: "https://storage.googleapis.com/falserverless/bria/bria_product_fg.jpg"
  },
  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 an environment where you cannot set environment variables, you can configure the API key manually on the client.

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/bria/product-shot", {
  input: {
    image_url: "https://storage.googleapis.com/falserverless/bria/bria_product_fg.jpg"
  },
  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/bria/product-shot", {
  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/bria/product-shot", {
  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

The URL of the product shot to be placed in a lifestyle shot. If both image_url and image_file are provided, image_url will be used. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.

scene_description string

Text description of the new scene or background for the provided product shot. Bria currently supports prompts in English only, excluding special characters.

ref_image_url string

The URL of the reference image to be used for generating the new scene or background for the product shot. Use "" to leave empty.Either ref_image_url or scene_description has to be provided but not both. If both ref_image_url and ref_image_file are provided, ref_image_url will be used. Accepted formats are jpeg, jpg, png, webp. Default value: ""

optimize_description boolean

Whether to optimize the scene description Default value: true

num_results integer

The number of lifestyle product shots you would like to generate. You will get num_results x 10 results when placement_type=automatic and according to the number of required placements x num_results if placement_type=manual_placement. Default value: 1

fast boolean

Whether to use the fast model Default value: true

placement_type PlacementTypeEnum

This parameter allows you to control the positioning of the product in the image. Choosing 'original' will preserve the original position of the product in the image. Choosing 'automatic' will generate results with the 10 recommended positions for the product. Choosing 'manual_placement' will allow you to select predefined positions (using the parameter 'manual_placement_selection'). Selecting 'manual_padding' will allow you to control the position and size of the image by defining the desired padding in pixels around the product. Default value: "manual_placement"

Possible enum values: original, automatic, manual_placement, manual_padding

original_quality boolean

This flag is only relevant when placement_type=original. If true, the output image retains the original input image's size; otherwise, the image is scaled to 1 megapixel (1MP) while preserving its aspect ratio.

shot_size list<integer>

The desired size of the final product shot. For optimal results, the total number of pixels should be around 1,000,000. This parameter is only relevant when placement_type=automatic or placement_type=manual_placement.

manual_placement_selection ManualPlacementSelectionEnum

If you've selected placement_type=manual_placement, you should use this parameter to specify which placements/positions you would like to use from the list. You can select more than one placement in one request. Default value: "bottom_center"

Possible enum values: upper_left, upper_right, bottom_left, bottom_right, right_center, left_center, upper_center, bottom_center, center_vertical, center_horizontal

padding_values list<integer>

The desired padding in pixels around the product, when using placement_type=manual_padding. The order of the values is [left, right, top, bottom]. For optimal results, the total number of pixels, including padding, should be around 1,000,000. It is recommended to first use the product cutout API, get the cutout and understand the size of the result, and then define the required padding and use the cutout as an input for this API.

sync_mode boolean

If True, the media will be returned as a data URI and the output data won't be available in the request history.

{
  "image_url": "https://storage.googleapis.com/falserverless/bria/bria_product_fg.jpg",
  "scene_description": "on a rock, next to the ocean, dark theme",
  "ref_image_url": "https://storage.googleapis.com/falserverless/bria/bria_product_bg.jpg",
  "optimize_description": true,
  "num_results": 1,
  "fast": true,
  "placement_type": "manual_placement",
  "shot_size": [
    1000,
    1000
  ],
  "manual_placement_selection": "bottom_center"
}

Output#

images list<Image>* required

The generated images

{
  "images": [
    {
      "url": "https://storage.googleapis.com/falserverless/bria/bria_product_res.png",
      "content_type": "image/png"
    }
  ]
}

Other types#

Image#

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 image in pixels.

height integer

The height of the image in pixels.

Related Models

Loading API documentation…

1. Calling the API

2. Authentication

API Key

3. Queue

4. Files

5. Schema

About

Product Shot

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. Install the new package and update your imports — see client setup.

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/bria/product-shot", {
  input: {
    image_url: "https://storage.googleapis.com/falserverless/bria/bria_product_fg.jpg"
  },
  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 an environment where you cannot set environment variables, you can configure the API key manually on the client.

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

fal.config({
  credentials: "YOUR_FAL_KEY"
});

Protect your API Key

3. Queue#

Long-running requests

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/bria/product-shot", {
  input: {
    image_url: "https://storage.googleapis.com/falserverless/bria/bria_product_fg.jpg"
  },
  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/bria/product-shot", {
  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/bria/product-shot", {
  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)#

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

The URL of the product shot to be placed in a lifestyle shot. If both image_url and image_file are provided, image_url will be used. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB.

scene_description string

Text description of the new scene or background for the provided product shot. Bria currently supports prompts in English only, excluding special characters.

ref_image_url string

optimize_description boolean

Whether to optimize the scene description Default value: true

num_results integer

fast boolean

Whether to use the fast model Default value: true

placement_type PlacementTypeEnum

Possible enum values: original, automatic, manual_placement, manual_padding

original_quality boolean

shot_size list<integer>

manual_placement_selection ManualPlacementSelectionEnum

Possible enum values: upper_left, upper_right, bottom_left, bottom_right, right_center, left_center, upper_center, bottom_center, center_vertical, center_horizontal

padding_values list<integer>

sync_mode boolean

If True, the media will be returned as a data URI and the output data won't be available in the request history.

{
  "image_url": "https://storage.googleapis.com/falserverless/bria/bria_product_fg.jpg",
  "scene_description": "on a rock, next to the ocean, dark theme",
  "ref_image_url": "https://storage.googleapis.com/falserverless/bria/bria_product_bg.jpg",
  "optimize_description": true,
  "num_results": 1,
  "fast": true,
  "placement_type": "manual_placement",
  "shot_size": [
    1000,
    1000
  ],
  "manual_placement_selection": "bottom_center"
}

Output#

images list<Image>* required

The generated images

{
  "images": [
    {
      "url": "https://storage.googleapis.com/falserverless/bria/bria_product_res.png",
      "content_type": "image/png"
    }
  ]
}

Other types#

Image#

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 image in pixels.

height integer

The height of the image in pixels.

fal-ai/bria/product-shot

fal-ai/bria/product-shot

fal-ai/bria/product-shot

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#

Image#

Related Models

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#

Image#

Related Models