Background Remove

Background Remove enables you to cleanly remove backgrounds from images, creating transparent PNG cutouts of foreground subjects. This classic background removal tool automatically detects and preserves the main subject while eliminating the background.

Model Specifications

Model Name: background-remove
Processing Time: 1-3 seconds
Supported Resolution: up to 4MP

Request

Remove image backgrounds by submitting the source image 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-remove",
           "inputs": {
             "image": "https://example.com/portrait.jpg"
           }
         }'

Response

Returns a prediction ID for status polling:

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

Request Parameters

Required Parameters

`image`
Required
image URL | base64

Source image to remove the background from. The AI will automatically detect the main subject and create a clean cutout with transparent background.

Base64 Format

Base64 images must include the proper prefix (e.g., data:image/jpg;base64,<YOUR_BASE64>)

Optional Parameters

`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 data:image/png;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 removal 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 either URLs or, if return_base64 is set to true, base64-encoded strings of your processed PNG images with backgrounds removed.

Runtime Errors

Background Remove may encounter the following model-specific errors during processing:

Name Cause Solution

Name	Cause	Solution
`ImageLoadError`	The pipeline was unable to load the input image from the provided inputs.	For Image URLs: Ensure the URL is publicly accessible and not restricted by permissions. Verify that the Content-Type header specifies the correct image format (e.g., image/jpeg, image/png). For Base64-encoded images: Prefix the string with data:image/`format`;base64, where format is the image type (e.g., jpeg, png).
`PipelineError`	An unexpected error occurred during the execution of the pipeline.	Retry the request (you will not be charged for failed attempts). If the issue persists, please reach out to us at support@fashn.ai and include the prediction ID from the failed attempt to help us locate and address the issue promptly.

ImageLoadError

The pipeline was unable to load the input image from the provided inputs.

For Image URLs:

Ensure the URL is publicly accessible and not restricted by permissions.
Verify that the Content-Type header specifies the correct image format (e.g., image/jpeg, image/png).

For Base64-encoded images:

Prefix the string with data:image/format;base64, where format is the image type (e.g., jpeg, png).

PipelineError An unexpected error occurred during the execution of the pipeline. Retry the request (you will not be charged for failed attempts). If the issue persists, please reach out to us at support@fashn.ai and include the prediction ID from the failed attempt to help us locate and address the issue promptly.

The Error Object

{
  "error": {
    "name": "PipelineError",
    "message": "Internal server error. If the problem persists, please contact support."
  }
}

Example of an error when polling the /status endpoint:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
  "status": "failed",
  "error": {
    "name": "ImageLoadError",
    "message": "Error loading input image: The URL's Content-Type is not an image. Content-Type: text/plain;charset=UTF-8"
  }
}

If you encounter an unrecognized error, please contact us at support@fashn.ai.

For detailed implementation guidance and best practices:

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

Background Remove

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

Response

imageRequiredimage URL | base64

return_base64boolean

On this page

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

`image`
Required
image URL | base64

`return_base64`boolean