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.

Lifecycle: Experimental · Released: August 15, 2025

Request body

Every call uses the universal POST /v1/run request body:

Place all endpoint parameters inside inputs; they are not top-level request fields.

Request

Remove image backgrounds by submitting the source image to the universal /v1/run endpoint:

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"
           }
         }'

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

Input parameters

Technical limitations

Minimum image dimensions are 128 × 128 px. Smaller images fail with InputValidationError.

Credit cost

Background Remove costs 1 credit per output image.

Processing time

Background removal typically completes in 1–3 seconds. Actual latency may vary with image complexity and current server load.

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

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

Related guides

For detailed implementation guidance and best practices:

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