Scene
Learn how to control the quality and speed of image generation.
AI Background API provides you with three ways to create a background for your product:
Template-free approach
Template-based approach
Solid color background with product shadow only
Template-free options
In the template-free approach, only text prompts are used for background generation. You can either generate prompts automatically with Autoprompt AI or write them manually for more control.
Prompt
The AI Background API accepts text prompts to define the background. Prompts can be generated automatically using Autoprompt AI or provided manually.
Autoprompt AI: Automatic prompt generation
Autoprompt AI analyzes the input product image and generates a text prompt tailored to create a contextually relevant background. This is useful for automating background generation, especially with large batches of images.
How to use it: Set the generate
parameter to true
within the prompt
object in the scene
section of your API request.
Generating a prompt with Autoprompt AI costs an additional 0.5 credits per request. Factor this into your usage planning.
Custom prompts: Manual control
For more control over the background, provide your own prompt. Custom prompts must be between 3 and 2048 characters.
Example:
Tips for effective custom prompts
Structure: Include place (surface), background, lighting, and mood for control.
Detail: Specify materials, textures, and context clearly (e.g., "rustic wooden table").
Clarity: Use precise terms—avoid vague words like "nice" or "pretty."
For more, see How to write prompts for AI product photos.
Negative prompt
The negative prompt is a parameter that specifies what you don't want to see on the generated background. When specified, it tells the generation process not to include things in the image that match a given text. The negative_prompt
must be between 3 and 2048 characters.
Color
If you want to change the color of the background, you can specify the desired color in hexadecimal format and it will be used as the main color.
Using color will make the resulting background look closer to the sample image.
Is only available for v1
model.
Inference steps
The more inference steps you use, the better the results, but the more steps, the longer it takes to generate. If you want faster results, you can use fewer steps. If you want higher-quality results, you can use more steps.
Is only available for v1
model. For v2-beta
the preference
parameter should be used instead.
Aspect ratio
By default, the aspect ratio is 1:1 with dimensions of 1024x1024px. But you can change it to any of the following values, listed from wider to taller:
12:5
1536x640px
16:9
1336x752px
7:4
1344x768px
19:13
1216x832px
9:7
1152x896px
1:1
1024x1024px
4:5
896x1120px
7:9
896x1152px
4:7
768x1344px
9:16
752x1336px
5:12
640x1536px
If you need a size larger than the generation result, you can upscale. See Upscale for more info.
Model
The template-free approach supports several background generation models. Available models are listed below:
v1
A stable, production-ready model optimized for product photography. Provides consistent results with fast processing times. Requires specific prompt formatting for best results. See Tips for more info.
v2-beta
Advanced model with improved photorealism. Processes natural language prompts more effectively and works with diverse subjects (products, people, etc.). Slightly slower processing time due to enhanced quality algorithms.
v1
model is used by default.
Preference
Easy to use parameter to configure model settings to achieve the desired balance between generation speed and output image quality.
Can be set to "fast"
, "optimal"
, or "best"
.
If no preference is specified, "optimal"
is used by default. But if negative_prompt
is specified - "best"
is used by default, since negative_prompt
can be specified only with "best"
preference.
Is only available for v2-beta
model.
Possible values
prompt
string, object
3 - 2048
is required
negative_prompt
string
3 - 2048
text, watermark, man, woman, child, overlay text, cartoon, pixelated, illustration, ugly, painting, cropped, lowres, low quality, jpeg artifacts, signature, logo
color
string
#000000
- #ffffff
steps
integer
1-49
15
aspect_ratio
string
12:5 - 5:12
1:1
model
string
v1, v2-beta
v1
preference
string
"fast"
, "optimal"
, "best"
"optimal"
Template-based approach
In the template-based approach, you can use a sample image that will be used to generate a background similar to the image, and you can also use prompts to increase the likelihood of achieving the desired result.
Template image
AI Background API supports several options to provide sample images that will be used to generate background.
If you upload a non-square image, it will be scaled and cropped to fit a square.
HTTP(S) URL
URL of the input image should be from 1 to 4096 characters. The image must be accessible by our system.
Connected storage
You can connect Cloud Storage and use it as a source for images. Currently, our API supports AWS S3 and Google Cloud Storage.
After connecting your Cloud Storage, you can refer the storage name as an input.
Input image file types
The API supports the following image formats as inputs: BMP, GIF, JPEG, PNG, TIFF, WEBP, AVIF, and HEIC.
Template mode
The template mode enables you to determine the degree of similarity between the background and the template image. You can select between lock
mode to preserve maximum details, adjust
mode to slightly adjust the background to better match the product, or transform
mode to freely transform the background with prompt
and color
parameters. See Color and Prompts for more info.
prompt
, color
and steps
are unavailable for lock
template mode.
color
is unavailable for adjust
template mode.
transform
Template is transformed according to the prompt
and color
.
adjust
Template is slightly adjusted to the product and prompt
.
lock
Template is preserved with maximum detail.
transform
template mode is used by default.
Template viewpoint
The template viewpoint describes the camera position and tilt angle from which the photo was taken. Available viewpoints are listed below:
top
The view is top-down, looking down on the subject from above.
front
The view is horizontal, looking directly on the subject.
front
viewpoint is used by default.
Prompts
You can use prompt
and negative_prompt
in the same way as in the template-free approach, but prompt
is not a required parameter for template-based approach.
Color
You can use color
in the same way as in the template-free approach, and color
is not a required parameter for template-based approach as well. If specified, color will be used as the main color of the image sample-based background.
Inference steps
You can use steps
in the same way as in the template-free approach, and again, steps
is not a required parameter for the template-based approach. By default, each template_mode
has an optimal steps
value. And steps
is not available for lock
mode.
Possible values
template_url
str
1 - 4096
is required
view
str
top
, front
front
color
str
#000000
- #ffffff
prompt
str
3 - 2048
negative_prompt
str
3 - 2048
text, watermark, man, woman, child, overlay text, cartoon, pixelated, illustration, ugly, painting, cropped, lowres, low quality, jpeg artifacts, signature, logo
steps
int
1-49
depends on template_mode
Limitations
The template image viewpoint (camera position and tilt angle from which the photo was taken) should match the viewpoint of the product image.
Product Shadows
Shadows generation mode covers the straightforward yet highly popular scenario in product photography. Creating a shadow effect for a product on transparent or on a solid Color can enhance its appearance. A product on a white background, for instance, looks better with a shadow.
The shadow generation effect requires View parameter. Color parameter is optional and omitting it will leave the background of the result image transparent.
Limitations
Background with product shadows does not require placement for the Object, so you don't need to pass any of placement related parameters in request payload. Object payload should be:
Last updated