# Scene

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

## Models

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

<table><thead><tr><th width="138">Model</th><th>Description</th></tr></thead><tbody><tr><td><code>v1</code></td><td>A stable, production-ready model optimized for product photography. Provides consistent results with fast processing times. Requires specific prompt formatting for best results. See <a href="#tips-for-effective-custom-prompts">Tips</a> for more info.</td></tr><tr><td><code>v2</code></td><td>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.</td></tr></tbody></table>

`v1` model is used by default.

{% hint style="success" %}
We recommend starting with the `v2` model as it is a flagship model.
{% endhint %}

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

{% hint style="info" %}
Generating a prompt with Autoprompt AI costs an additional 0.5 credits per request. Factor this into your usage planning.
{% endhint %}

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

```json
{
    "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").

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

{% hint style="info" %}
Including humans in the `guidelines` is only supported with the `v2` model.
{% endhint %}

**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:**

{% code overflow="wrap" %}

```json
{
    "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."
    }
}
```

{% endcode %}

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

{% code overflow="wrap" %}

```json
{
    "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"
    }
}
```

{% endcode %}

### 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         | 1312x736px  |
| 7:4          | 1344x768px  |
| 19:13        | 1216x832px  |
| 9:7          | 1152x896px  |
| 1:1          | 1024x1024px |
| 4:5          | 896x1120px  |
| 7:9          | 896x1152px  |
| 4:7          | 768x1344px  |
| 9:16         | 736x1312px  |
| 5:12         | 640x1536px  |

{% hint style="info" %}
If you need a size larger than the generation result, you can upscale. See [Upscale](https://docs.claid.ai/image-editing-api/image-operations/restorations#upscale) for more info.
{% endhint %}

{% code overflow="wrap" %}

```json
{
    "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"
    }
}
```

{% endcode %}

### Preference

Easy to use parameter to configure model settings to achieve the desired balance between generation speed and output image quality.&#x20;

Can be set to `"fast"`, `"optimal"`, or `"best"`.&#x20;

If no preference is specified, `"optimal"` is used by default. If `negative_prompt` is specified, however, only `"optimal"` or `"best"` are allowed.

{% code overflow="wrap" %}

```json
{
    "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"
    }
}
```

{% endcode %}

### Possible values

<table><thead><tr><th width="202">Parameter</th><th width="95">Type</th><th width="145">Range</th><th>Default value</th></tr></thead><tbody><tr><td><code>prompt</code></td><td><em>string, object</em></td><td>3 - 2048</td><td><strong>is required</strong></td></tr><tr><td><code>negative_prompt</code></td><td><em>string</em></td><td>3 - 2048</td><td>text, watermark, man, woman, child, overlay text, cartoon, pixelated, illustration, ugly, painting, cropped, lowres, low quality, jpeg artifacts, signature, logo</td></tr><tr><td><code>aspect_ratio</code></td><td><em>string</em></td><td>12:5 - 5:12</td><td>1:1</td></tr><tr><td><code>preference</code></td><td><em>string</em></td><td><code>"fast"</code>, <code>"optimal"</code>, <code>"best"</code></td><td><code>"optimal"</code></td></tr></tbody></table>

## Template-free v1 model options

`v1` model also supports:&#x20;

### [Prompt](#prompt)

**Custom prompts: Manual control**

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

**Example:**

{% code overflow="wrap" %}

```json
{
    "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"
    }
}
```

{% endcode %}

#### 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](https://claid.ai/blog/article/prompt-guide/).

### [Negative prompt](#negative-prompt)

### [Aspect ratio](#aspect-ratio)&#x20;

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.

{% code overflow="wrap" %}

```json
{
    "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"
    }
}
```

{% endcode %}

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

{% code overflow="wrap" %}

```json
{
    "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
    }
}
```

{% endcode %}

### Possible values

<table><thead><tr><th width="202">Parameter</th><th width="95">Type</th><th width="145">Range</th><th>Default value</th></tr></thead><tbody><tr><td><code>prompt</code></td><td><em>string, object</em></td><td>3 - 2048</td><td><strong>is required</strong></td></tr><tr><td><code>negative_prompt</code></td><td><em>string</em></td><td>3 - 2048</td><td>text, watermark, man, woman, child, overlay text, cartoon, pixelated, illustration, ugly, painting, cropped, lowres, low quality, jpeg artifacts, signature, logo</td></tr><tr><td><code>aspect_ratio</code></td><td><em>string</em></td><td>12:5 - 5:12</td><td>1:1</td></tr><tr><td><code>color</code></td><td><em>string</em></td><td><code>#000000</code> - <code>#ffffff</code></td><td></td></tr><tr><td><code>steps</code></td><td>integer</td><td>1-49</td><td>15</td></tr></tbody></table>

## 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-based v2 model options

`v2` model supports the following options:

### Template image

AI Background API supports several options to provide sample images that will be used to generate background.

{% hint style="info" %}
If you upload a non-square image, it will be scaled and cropped to fit a square.
{% endhint %}

#### HTTP(S) URL

URL of the input image should be from 1 to 4096 characters. The image must be accessible by our system.

```json
{
    "scene": {
        "model": "v2",
        "template_url": "https://images.claid.ai/photoshoot-templates/docs/scene.png"
    }
}
```

#### Connected storage

You can connect [Cloud Storage](https://docs.claid.ai/storage-connectors) 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.

```json
{
    "scene": {
        "model": "v2",
        "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.&#x20;

### 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](#color) and [Prompts](#prompts) for more info.

{% hint style="info" %}
`prompt`, `color` and `steps` are unavailable for `lock` template mode.\
\
`color` is unavailable for `adjust` template mode.
{% endhint %}

<table><thead><tr><th width="153">Viewpoint</th><th></th></tr></thead><tbody><tr><td><code>transform</code></td><td>Template is transformed according to the <code>prompt</code> and <code>color</code>.</td></tr><tr><td><code>adjust</code></td><td>Template is slightly adjusted to the product and <code>prompt</code>.</td></tr><tr><td><code>lock</code></td><td>Template is preserved with maximum detail.</td></tr></tbody></table>

`transform` template mode is used by default.

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "scene": {
        "model": "v2",
        "template_url": "storage://storage-name/path/scene.png",
        "template_mode": "lock"
    }
}
</code></pre>

### Template viewpoint

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

<table><thead><tr><th width="139">Viewpoint</th><th></th></tr></thead><tbody><tr><td><code>top</code></td><td>The view is top-down, looking down on the subject from above.</td></tr><tr><td><code>front</code></td><td>The view is horizontal, looking directly on the subject.</td></tr></tbody></table>

`front` viewpoint is used by default.

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

### Prompt

You can use `prompt` in the same way as in the template-free approach, but `prompt` is not a required parameter for template-based approach.

{% hint style="info" %}
`generate` parameters is available only for `transform` and `adjust` modes.

`guidelines` parameter is available only for  `transform` mode.
{% endhint %}

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

<table><thead><tr><th width="212">Parameter</th><th width="75">Type</th><th width="139">Range</th><th>Default value</th></tr></thead><tbody><tr><td><code>template_url</code></td><td><em>string</em></td><td>1 - 4096</td><td><strong>is required</strong></td></tr><tr><td><code>view</code></td><td><em>string</em></td><td><code>top</code>, <code>front</code></td><td><code>front</code></td></tr><tr><td><code>prompt</code></td><td><em>string, object</em></td><td>3 - 2048</td><td></td></tr><tr><td><code>steps</code></td><td><em>integer</em></td><td>1-49</td><td>depends on <code>template_mode</code></td></tr></tbody></table>

## Template-based v1 model options

`v1` model also supports:&#x20;

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

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

### Possible values

<table><thead><tr><th width="212">Parameter</th><th width="75">Type</th><th width="139">Range</th><th>Default value</th></tr></thead><tbody><tr><td><code>template_url</code></td><td><em>string</em></td><td>1 - 4096</td><td><strong>is required</strong></td></tr><tr><td><code>view</code></td><td><em>string</em></td><td><code>top</code>, <code>front</code></td><td><code>front</code></td></tr><tr><td><code>color</code></td><td><em>string</em></td><td><code>#000000</code> - <code>#ffffff</code></td><td></td></tr><tr><td><code>prompt</code></td><td><em>string</em></td><td>3 - 2048</td><td></td></tr><tr><td><code>negative_prompt</code></td><td><em>string</em></td><td>3 - 2048</td><td>text, watermark, man, woman, child, overlay text, cartoon, pixelated, illustration, ugly, painting, cropped, lowres, low quality, jpeg artifacts, signature, logo</td></tr><tr><td><code>steps</code></td><td><em>integer</em></td><td>1-49</td><td>depends on <code>template_mode</code></td></tr></tbody></table>

### 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 v2 model options

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

```json
{
    "scene": {
        "effect": "shadows",
        "model": "v2",
        "color": "#d3d3d3",
        "view": "top",
        "aspect_ratio": "1:1"
    }
}

```

[Color](#color) and [Aspect ratio](#aspect-ratio) parameters are optional and omitting it will leave the background of the result image transparent and with a 1:1 aspect ratio.

### Viewpoint

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

<table><thead><tr><th width="139">Viewpoint</th><th></th></tr></thead><tbody><tr><td><code>auto</code></td><td>The shadows will be generated for the most common copyspace arrangement depending on the product.</td></tr><tr><td><code>top</code></td><td>The shadows will be generated for a copyspace photographed from above, with shadows around the product.</td></tr><tr><td><code>front</code></td><td>The shadows will be generated for a copyspace photographed frontally, with shadows under the product.</td></tr></tbody></table>

`auto` viewpoint is used by default.

### Possible values

<table><thead><tr><th width="212">Parameter</th><th width="75">Type</th><th width="139">Range</th><th>Default value</th></tr></thead><tbody><tr><td><code>effect</code></td><td><em>string</em></td><td><code>shadows</code></td><td><strong>is required</strong></td></tr><tr><td><code>model</code></td><td><em>string</em></td><td><code>v2</code></td><td><strong>is required</strong></td></tr><tr><td><code>view</code></td><td><em>string</em></td><td><code>auto,</code> <code>top</code>, <code>front</code></td><td><code>auto</code></td></tr><tr><td><code>color</code></td><td><em>string</em></td><td><code>#000000</code> - <code>#ffffff</code>, <code>"transparent"</code> </td><td></td></tr><tr><td><code>aspect_ratio</code></td><td><em>string</em></td><td>12:5 - 5:12</td><td></td></tr></tbody></table>

## Product Shadows v1 model options

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

```json
{
    "scene": {
        "model": "v1",
        "effect": "shadows",
        "color": "#d3d3d3",
        "view": "top"
    }
}

```

&#x20;[Color](#color) parameter is optional and omitting it will leave the background of the result image transparent.

### Model v1 limitations

* Requires [Viewpoint](#viewpoint) parameter with either `front` or `top` values, `auto` is not supported.
* Does not support  [Aspect ratio](#aspect-ratio) parameter.
* Does not support placement for the [Object](https://docs.claid.ai/ai-background-api/ai-background-options/object), so you don't need to pass any of placement related parameters in request payload. Object payload should be:

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

### Possible values

<table><thead><tr><th width="212">Parameter</th><th width="75">Type</th><th width="139">Range</th><th>Default value</th></tr></thead><tbody><tr><td><code>effect</code></td><td><em>string</em></td><td><code>shadows</code></td><td><strong>is required</strong></td></tr><tr><td><code>model</code></td><td><em>string</em></td><td><code>v1-v2</code></td><td><code>v1</code></td></tr><tr><td><code>view</code></td><td><em>string</em></td><td><code>top</code>, <code>front</code></td><td><strong>is required</strong></td></tr><tr><td><code>color</code></td><td><em>string</em></td><td><code>#000000</code> - <code>#ffffff</code>, <code>"transparent"</code> </td><td></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.claid.ai/ai-background-api/ai-background-options/scene.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.