Background Change

Background Change enables you to replace image backgrounds while preserving foreground subjects. The endpoint accurately separates the foreground from the background and applies harmonization so the subject blends seamlessly into the new environment.

Model Specifications

Model Name: background-change
Lifecycle: experimental
Processing Time: 12 seconds
Supported Resolution: up to 1.05MP
Credits: 1

Request

Replace image backgrounds by submitting the source image and background description to the universal /v1/run endpoint:

POST`https://api.fashn.ai/v1/run`

Request Examples

curl -X POST https://api.fashn.ai/v1/run \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -d '{
           "model_name": "background-change",
           "inputs": {
             "image": "https://example.com/portrait.jpg",
             "prompt": "modern office space with large windows"
           }
         }'

Response

Returns a prediction ID for status polling:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
  "error": null
}

Request Parameters

`image`
Required
image URL | base64

Source image containing the subject to preserve. The AI will automatically detect and separate the foreground subject from the background.

`prompt`
Required
string

Description of the desired new background (e.g., 'beach sunset', 'modern office', 'forest clearing'). The AI generates a new background based on this description and harmonizes it with the preserved foreground subject.

`seed`integer

Sets random operations to a fixed state. Use the same seed to reproduce results with the same inputs, or different seed to force different results.

Default: 42
Range: 0 to 2^32 - 1

`output_format`'png' | 'jpeg'

Specifies the output image format.

-png: Delivers the highest quality image, ideal for use cases such as content creation where quality is paramount.
-jpeg: Provides a faster response with a slightly compressed image, more suitable for real-time applications.

Default: png

`return_base64`boolean

When set to true, the API will return the generated image as a base64-encoded string instead of a CDN URL. The base64 string will be prefixed according to the output_format (e.g., data:image/png;base64,... or data:image/jpeg;base64,...).

This option offers enhanced privacy as user-generated outputs are not stored on our servers when return_base64 is enabled.

Default: false

Response Polling

After submitting your request, poll the status endpoint using the returned prediction ID. See API Fundamentals for complete polling details.

Successful Response

When your background change completes successfully, the status endpoint will return:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
  "status": "completed",
  "output": [
    "https://cdn.fashn.ai/123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1/output_0.png"
  ],
  "error": null
}

The output array contains URLs to your processed images with the new background and harmonized foreground subject.

Runtime Errors

Runtime errors for Background Change use the shared set in Error Handling.

For detailed implementation guidance and best practices:

Image Preprocessing Best Practices - Optimize your source images for background replacement

Background Change

POSThttps://api.fashn.ai/v1/run

Response

imageRequiredimage URL | base64

promptRequiredstring

seedinteger

output_format'png' | 'jpeg'