> For the complete documentation index, see [llms.txt](https://documentation.deep-image.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.deep-image.ai/image-processing/background-removal-and-generation.md).
# Background removal and generation
Use `background.remove` to cut out the main subject.
You can keep transparency, apply a flat color, replace the background, or generate a new one.
### Background removal
```json
{
"background": {
"remove": "auto",
"color": "#FFFFFF"
}
}
```
#### Parameters
| Parameter | Description |
| --------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `remove` | Controls the background removal mode. Supported values are `auto`, `auto_v2` (Combined), `v2`, `human`, `item`, and `generative`. |
| `prompt` | Text instruction used with `remove: "generative"`. Describe what should stay in the foreground. |
| `color` | Controls the output background color. Use `auto`, a hex color like `#FFFFFF`, or `transparent`. |
| `replace` | URL of a background image for simple replacement. This does not generate new shadows or reflections. |
Set the desired API mode explicitly. **Combined** (`auto_v2`) is the default selection for signed-in users in the web app; existing saved selections are restored.
Use `human` for portraits.
Use `item` for products and objects.
Use `generative` when the image has multiple relevant foreground elements and you want the prompt to guide what stays.
Let's check some examples.
{% hint style="info" %}
Click the result image to compare it with the source.
{% endhint %}
{% tabs %}
{% tab title="transparent" %}
```json
{
"url": "https://deep-image.ai/api-example.png",
"background": {
"remove": "auto",
"color": "transparent"
}
}
```
{% endtab %}
{% tab title="white" %}
```json
{
"url": "https://deep-image.ai/api-example.png",
"background": {
"remove": "item",
"color": "#FFFFFF"
}
}
```
{% endtab %}
{% tab title="replace" %}
```json
{
"url": "https://deep-image.ai/api-example.png",
"background": {
"remove": "auto",
"replace": "https://images.pexels.com/photos/628281/pexels-photo-628281.jpeg?auto=compress&cs=tinysrgb&w=1260&h=750&dpr=1"
}
}
```
{% endtab %}
{% endtabs %}
### Combined background removal (`auto_v2`)
**Combined** runs both `auto` and `v2`, then selectively combines their masks using the original image and nearby contours. It is intended to retain foreground details that one model may miss, including the complete physical package and its printed artwork. It does not need a prompt.
Use `"remove": "auto_v2"` explicitly in API requests. Combined is the default selection for signed-in users in the web app; an existing saved selection is restored.
Both segmentation models run, so processing takes longer than a single-model mode. Results still need review: textured backgrounds can leave extra background, and transparent objects, windows and faint object outlines can be ambiguous. Combined is not guaranteed to outperform `auto` or `v2` on every image.
#### Example: transparent PNG
```json
{
"url": "https://deep-image.ai/api-example.png",
"background": {
"remove": "auto_v2",
"color": "transparent"
},
"output_format": "png"
}
```
#### Example: white background
```json
{
"url": "https://deep-image.ai/api-example2.jpg",
"background": {
"remove": "auto_v2",
"color": "#FFFFFF"
},
"output_format": "png"
}
```
For a packaged product, keep the full package as the foreground, including pictures printed on it. This mode selects a cutout; it does not redraw the product or generate a replacement scene.
#### Complete API request
```bash
curl --request POST 'https://deep-image.ai/rest_api/process_result' \
--header "x-api-key: $DEEP_IMAGE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"url": "https://deep-image.ai/api-example.png",
"background": {"remove": "auto_v2", "color": "transparent"},
"output_format": "png"
}'
```
Set `DEEP_IMAGE_API_KEY` to your API key. If the response status is not yet `complete`, poll `GET https://deep-image.ai/rest_api/result/{job}` using the returned `job` identifier and the same API key. When processing completes, download the file from `result_url`. See [API methods](/api-methods.md) for request and response details.
#### Comparing the modes
These examples use the public demo images linked above. Each source was processed separately through the local API with `auto`, `v2` and `auto_v2`, using PNG output and default mask settings. The checkerboard is a display aid for transparency; it is not part of the output PNG. These are examples, not an accuracy benchmark. The results on these two sources are similar across the three modes; they do not demonstrate a universal quality improvement.
Source: [api-example.png](https://deep-image.ai/api-example.png).
Source: [api-example2.jpg](https://deep-image.ai/api-example2.jpg).
The existing `background.mask_smooth`, `background.mask_repair` and `background.matting` options also apply to Combined. Mask smoothing is applied after combining the masks.
### Prompt-based background removal
Use prompt-based removal when `auto` keeps too much, removes too much, or misses related foreground objects.
Keep the prompt short and focused on what should remain.
```json
{
"background": {
"remove": "generative",
"prompt": "keep relevant foreground, keep relevant objects"
}
}
```
You can combine this with `color` or `replace` when you do not want a transparent result.
For image preparation tips, see [Remove BG recommendation](/image-processing/background-removal-and-generation/remove-bg-recommendation.md).
### Item cropping
You can combine background removal, padding, and item crop to center a subject inside a fixed canvas.
```json
{
"url": "https://deep-image.ai/api-example2.jpg",
"width": 1000,
"height": 1000,
"fit": {
"crop": "item"
},
"background": {
"remove": "auto",
"color": "#FFFFFF"
},
"padding": 100
}
```
Result
### Background generation
Background generation improves product photos without a manual photo shoot.
It removes the original background, places the subject on the canvas, and generates a new scene around it.
#### Parameters
| Parameter | Description |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `description` | Text prompt describing the scene. |
| `item_area_percentage` | Float from `0` to `1` that controls how much of the final image the item occupies. `0.85` means 85%. |
| `sample_num` | Random seed for the generated image. If you omit it, results vary between runs. |
| `color` | Converts the generated background to black and white, then tints it with the given RGB array. Example: `[255,255,255]`. |
| `background_url` | URL of an image blended with the generated background for more consistent outputs. |
```json
{
"url": "https://deep-image.ai/api-example.png",
"background": {
"generate": {
"description": "item standing on sand with beach in background",
"item_area_percentage": 0.65,
"sample_num": 12663
}
}
}
```
Without `sample_num`:
```json
{
"url": "https://deep-image.ai/api-example.png",
"background": {
"generate": {
"description": "item standing on sand with beach in background",
"item_area_percentage": 0.65
}
}
}
```
You can also set the output size:
```json
{
"url": "https://deep-image.ai/api-example.png",
"width": 1000,
"height": 1000,
"background": {
"generate": {
"description": "item standing on sand with beach in background",
"item_area_percentage": 0.65
}
}
}
```
When specifying a color:
```json
{
"url": "https://deep-image.ai/api-example.png",
"width": 1000,
"height": 1000,
"background": {
"generate": {
"description": "item positioned on plain white background",
"item_area_percentage": 0.65,
"color": [217,179,190]
}
}
}
```
