LogoLogo
  • Overview
  • Quick Start
  • Authentication
  • Rate limits
  • Errors
  • Image Editing API
    • Image I/O
    • Image Operations
      • Restorations
      • Resizing
      • Outpainting
      • Generative Editing
      • Color Adjustments
      • Background
      • Padding
      • Privacy
    • API Reference
    • Async API Reference
    • Batch API Reference
    • Upload API Reference
  • image generation api
    • Image Generation I/O
    • Image Generation Options
    • API Reference
  • AI Background API
    • AI Background I/O
    • AI Background Options
      • Object
      • Scene
      • Product Shadow
    • API Reference
  • Image to Video API
    • Image to Video I/O
    • Image to Video Options
    • Async API Reference
  • Storage Connectors
    • Overview
    • AWS S3
    • Google Cloud Storage
    • Web Folder
    • API Reference
  • Guides
    • E-commerce
    • Real Estate
    • Printing
  • Redoc
  • Blog
Powered by GitBook
On this page
  • Template-free approach
  • Template-free models
  • Template-free v2 model options
  • Prompt
  • Negative prompt
  • Aspect ratio
  • Preference
  • Possible values
  • Template-free v1 model options
  • Prompt
  • Negative prompt
  • Aspect ratio
  • Color
  • Inference steps
  • Possible values
  • Template-based approach
  • Template image
  • Template mode
  • Template viewpoint
  • Prompts
  • Color
  • Inference steps
  • Possible values
  • Limitations
  • Product Shadows
  • Limitations
Edit on GitHub
  1. AI Background API
  2. AI Background Options

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 approach

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.

Template-free models

The template-free approach supports several background generation models. Available models are listed below:

Model
Description

v1

v2

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.

We recommend starting with the v2 model as it is a flagship model.

Template-free v2 model options

v2 model supports the following options:

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.

Generating a prompt with Autoprompt AI costs an additional 0.5 credits per request. Factor this into your usage planning.

How to use it: Set the generate parameter to true within the prompt object in the scene section of your API request.

{
    "scene": {
        "model": "v2",
        "prompt": {
            "generate": true
        }
    }
}

You can influence Autoprompt AI by providing guidelines. Guidelines can be specific keywords (e.g., "seaside, sunset, ocean") or more abstract concepts (e.g., "summer vibes," "pink monochromatic environment," "real life setting").

{
    "scene": {
        "model": "v2",
        "prompt": {
            "generate": true,
            "guidelines": "seaside, sunset, ocean, beach, sand, waves"
        }
    }
}

Including humans in the guidelines is only supported with the v2 model.

Custom prompts: Manual control

For even more precise control over the background, you can provide your own prompt. Custom prompts must be between 3 and 2048 characters.

Example:

{
    "scene": {
        "model": "v2",
        "prompt": "Professional photo of a product. The background features a serene spa environment with natural wooden textures, soft white towels, and smooth pebbles. Lavender plants add to the calming ambiance. The lighting is soft and natural, coming from the left, creating a tranquil and inviting atmosphere perfect for wellness and relaxation. The setting exudes a sense of luxury and care, aligning with the product's high-end aesthetic."
    }
}

Negative prompt

The negative prompt parameter specifies elements to exclude from the generated background. The model will avoid including content matching this text. The negative_prompt must be between 3 and 2048 characters.

{
    "scene": {
        "model": "v2",
        "prompt": "Professional photo of a product. The background features a serene spa environment with natural wooden textures, soft white towels, and smooth pebbles. Lavender plants add to the calming ambiance. The lighting is soft and natural, coming from the left, creating a tranquil and inviting atmosphere perfect for wellness and relaxation. The setting exudes a sense of luxury and care, aligning with the product's high-end aesthetic.",
        "negative_prompt": "pixelated, low quality"
    }
}

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:

Aspect ratio
Output size

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

{
    "scene": {
        "model": "v2",
        "prompt": "Professional photo of a product. The background features a serene spa environment with natural wooden textures, soft white towels, and smooth pebbles. Lavender plants add to the calming ambiance. The lighting is soft and natural, coming from the left, creating a tranquil and inviting atmosphere perfect for wellness and relaxation. The setting exudes a sense of luxury and care, aligning with the product's high-end aesthetic.",
        "negative_prompt": "pixelated, low quality",
        "aspect_ratio": "16:9"
    }
}

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.

{
    "scene": {
        "model": "v2",
        "prompt": "Professional photo of a product. The background features a serene spa environment with natural wooden textures, soft white towels, and smooth pebbles. Lavender plants add to the calming ambiance. The lighting is soft and natural, coming from the left, creating a tranquil and inviting atmosphere perfect for wellness and relaxation. The setting exudes a sense of luxury and care, aligning with the product's high-end aesthetic.",
        "negative_prompt": "pixelated, low quality",
        "aspect_ratio": "16:9",
        "preference": "fast"
    }
}

Possible values

Parameter
Type
Range
Default value

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

aspect_ratio

string

12:5 - 5:12

1:1

preference

string

"fast", "optimal", "best"

"optimal"

Template-free v1 model options

v1 model also supports:

Custom prompts: Manual control

For more control over the background, provide your own prompt. Custom prompts must be between 3 and 2048 characters.

Example:

{
    "scene": {
        "model": "v1",
        "prompt": "on a rugged mountain trail, scattered rocks, moss-covered ground, sunlight filtering through pine trees, rich earthy colors, warm light, dynamic perspective, high quality, professional product photography"
    }
}

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

In addition it supports the following options:

Color

If you want to change the color of the background, you can specify the desired color in hexadecimal format. The color parameter defines the main color theme for the generated background scene.

{
    "scene": {
        "model": "v1",
        "prompt": "on a rugged mountain trail, scattered rocks, moss-covered ground, sunlight filtering through pine trees, rich earthy colors, warm light, dynamic perspective, high quality, professional product photography",
        "negative_prompt": "pixelated, low quality",
        "aspect_ratio": "16:9",
        "color": "#8fa782"
    }
}

Inference steps

The inference steps parameter controls the number of iterations the model uses for generation. Increasing the steps value generally improves image quality and detail but also increases processing time. Conversely, decreasing steps speeds up generation, potentially at the cost of some quality.

{
    "scene": {
        "model": "v1",
        "prompt": "on a rugged mountain trail, scattered rocks, moss-covered ground, sunlight filtering through pine trees, rich earthy colors, warm light, dynamic perspective, high quality, professional product photography",
        "negative_prompt": "pixelated, low quality",
        "aspect_ratio": "16:9",
        "color": "#8fa782",
        "steps": 20
    }
}

Possible values

Parameter
Type
Range
Default value

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

aspect_ratio

string

12:5 - 5:12

1:1

color

string

#000000 - #ffffff

steps

integer

1-49

15

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.

{
    "scene": {
        "template_url": "https://images.claid.ai/photoshoot-templates/docs/scene.png"
    }
}

Connected storage

After connecting your Cloud Storage, you can refer the storage name as an input.

{
    "scene": {
        "template_url": "storage://storage-name/path/scene.png"
    }
}

Input image file types

The API supports the following image formats as inputs: BMP, GIF, JPEG, PNG, TIFF, WEBP, AVIF, and HEIC.

Template mode

prompt, color and steps are unavailable for lock template mode. color is unavailable for adjust template mode.

Viewpoint

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.

{
    "scene": {
        "template_url": "storage://storage-name/path/scene.png",
        "template_mode": "lock"
    }
}

Template viewpoint

The template viewpoint describes the camera position and tilt angle from which the photo was taken. Available viewpoints are listed below:

Viewpoint

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.

{
    "scene": {
        "template_url": "storage://storage-name/path/scene.png",
        "view": "top"
    }
}

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

Parameter
Type
Range
Default value

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

{
    "scene": {
        "effect": "shadows",
        "color": "#d3d3d3",
        "view": "top"
    }
}

Limitations

{
    "object": {
        "image_url": "https://images.claid.ai/photoshoot-templates/docs/product.png"
    }
}
PreviousObjectNextAPI Reference

Last updated 2 days ago

A stable, production-ready model optimized for product photography. Provides consistent results with fast processing times. Requires specific prompt formatting for best results. See for more info.

If you need a size larger than the generation result, you can upscale. See for more info.

For more, see .

You can connect and use it as a source for images. Currently, our API supports AWS S3 and Google Cloud Storage.

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 and for more info.

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 can enhance its appearance. A product on a white background, for instance, looks better with a shadow.

The shadow generation effect requires parameter. parameter is optional and omitting it will leave the background of the result image transparent.

Background with product shadows does not require placement for the , so you don't need to pass any of placement related parameters in request payload. Object payload should be:

How to write prompts for AI product photos
Cloud Storage
Object
Prompt
Negative prompt
Aspect ratio
Color
Prompts
Color
View
Color
Tips
Upscale