# Replace background

div
strong
🔨 In Development
 — This section is still being developed and may change.

Swap image backgrounds for new scenes, patterns, or solid fills using Freddy vision models.

## Authentication

- `Authorization: Bearer $FREDDY_API_KEY`
[Get your API key](https://freddy-hub.aitronos.com/freddy/api)


## Request body

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `image_url` | string | **Yes** | Public URL or base64-encoded data for the source image. |
| `new_background` | string | **Yes** | Description, image URL, or color code for the replacement background. |
| `format` | string | No | Output format: `png`, `jpeg`, or `webp`. Default: `png`. |
| `blend_mode` | string | No | Foreground blending strategy. Choose `natural`, `overlay`, or `multiply`. Default: `natural`. |


## Returns

JSON object containing processed images with new backgrounds and related metadata.


```json
{
  "data": [
    {
      "url": "https://api.freddy.aitronos.com/processed-images/img_abc123.png",
      "foreground_mask": "https://api.freddy.aitronos.com/masks/mask_abc123.png",
      "background_replaced": true
    }
  ]
}
```

Request (curl)

```bash
curl -X POST "https://api.freddy.aitronos.com/v1/images/replace-background" \
  -H "Authorization: Bearer $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/product.jpg",
    "new_background": "modern office environment",
    "format": "png",
    "blend_mode": "natural"
  }'
```

Error Response

```json
{
  "error": {
    "type": "invalid_background",
    "message": "new_background must be a color or descriptive prompt"
  }
}
```

## Related resources

- [Image object](/docs/api-reference/images/objects/image-object)
- [Remove background](/docs/api-reference/images/remove-background)
- [Generate image](/docs/api-reference/images/generate)
- [Cleanup image](/docs/api-reference/images/cleanup)