Name: Bria – AI Background Removal & Swap | $0.05/call | API.market
Brand: magicapi
SKU: api-magicapi-ai-image-background-removal-replacement
Availability: InStock
Author: API Market

Shashank Agarwal

# 🌄 AI Image Background Swap API (Bria) – Realistic & Safe Results

## Overview
This API allows you to replace or remove the background of an image, either by providing a text prompt that describes the desired new background or by referencing another image whose environment should be used. The result is a polished, realistic composite that maintains the foreground subject's details while accurately blending in the new background. This service is trained exclusively on licensed data, ensuring safe and risk-free usage for various commercial applications.

![Example input image: A sample portrait for background replacement.](https://blog.api.market/wp-content/uploads/2026/04/Background-replacement.jpg)

## Features
- Simple text or reference-based background swapping.
- Maintains realistic details and lighting for a professional finish.
- Fast inference mode to balance speed and quality.
- Safe for commercial use (trained on licensed data).
- Option to force background removal, even if the source has transparency.
- Configurable output resolution and image enhancement settings.

## Use Cases
1. **E-Commerce Product Shoots**  
   Quickly place products in different, contextually relevant backgrounds (e.g., home interiors, outdoor locations) to attract shoppers’ attention.

2. **Real Estate Marketing**  
   Replace cluttered or uninviting backgrounds in property photos with bright, welcoming scenes, improving listing appeal.

3. **Social Media & Influencer Content**  
   Instantly create visually striking imagery by transporting the subject to dream destinations or branded backdrops.

4. **Corporate Branding & Advertising**  
   Maintain a consistent look for ad campaigns by standardizing or tailoring the background to match brand aesthetics.

5. **Travel & Tourism Campaigns**  
   Quickly showcase destinations by placing travelers in scenic or iconic backgrounds—perfect for marketing materials and brochures.

## Visual Examples

Below is a sample input image and the corresponding output after running it through the API with a prompt instructing the model to place the subject “in a parking lot.”

**Input:**
![Portrait for background replacement](https://blog.api.market/wp-content/uploads/2026/04/Background-replacement.jpg)

**Output (with background replaced):**
![Subject replaced into a new parking lot background](https://blog.api.market/wp-content/uploads/2026/04/output-background-replacement.png)

You can also reference any secondary image (e.g., “https://example.com/image.jpg”) to extract its environment and use it as the new background.

## Pricing
- Pay As You Go (PAYG) – only pay for each image processed.  
- 1 API unit = 1 image processed.  
- Checking prediction status (GET /api/v1/magicapi/ai-image-background-removal-replacement/predictions/{id}) is free.  
- No monthly subscription fees or usage limits—per-call pricing.

## API Documentation

### Base URL
All requests to this API should be made to:  
```
https://prod.api.market/api/v1/magicapi/ai-image-background-removal-replacement
```

### Authentication
Include your API key in the request header:

```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
This service processes background replacement asynchronously. The typical flow is:

1. POST your prediction request to create a new job.
2. Receive a prediction ID in the response.
3. Poll the GET endpoint with the prediction ID to check the status.
4. Continue polling until the status is “succeeded” (or until an error or timeout occurs).

We recommend:
- A polling interval of 1 second.  
- A maximum timeout of 600 seconds (10 minutes).  
- Stopping polling if status is “failed” or you exceed your timeout.  
- Appropriately handling the “succeeded” status by retrieving the final output.

### Endpoints

#### 1) Create a Prediction
• **Endpoint**:  
POST `/api/v1/magicapi/ai-image-background-removal-replacement/predictions`

• **Description**:  
Submit an image (either directly or via an image URL) along with your text or reference-based background instructions.  

• **Example Request** (cURL):
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-image-background-removal-replacement/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "e9e2ad4616048014645b4d3a0bc95f0b254c03dcbbbe8e6a28483bcbae4bd9a5",
    "input": {
      "fast": true,
      "sync": true,
      "image": "https://blog.api.market/wp-content/uploads/2026/04/Background-replacement.jpg",
      "bg_prompt": "in a parking lot",
      "force_rmbg": false,
      "refine_prompt": true,
      "original_quality": false,
      "enhance_ref_image": true,
      "content_moderation": false
    }
  }'
```

• **Example Response (201)**:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "e9e2ad4616048014645b4d3a0bc95f0b254c03dcbbbe8e6a28483bcbae4bd9a5",
  "status": "starting",
  "created_at": "2025-07-11T07:19:37.658Z"
}
```

#### 2) Check Prediction Status & Results
• **Endpoint**:  
GET `/api/v1/magicapi/ai-image-background-removal-replacement/predictions/{id}`

• **Description**:  
Retrieve the status of a prediction. Once the status is “succeeded,” the `output` field will contain the new image URLs.

• **Example Request** (cURL):
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-image-background-removal-replacement/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

• **Example Response (200, succeeded)**:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": [
    "https://blog.api.market/wp-content/uploads/2026/04/output-background-replacement.png"
  ],
  "error": null,
  "created_at": "2023-01-01T12:00:00.000Z",
  "started_at": "2023-01-01T12:00:05.000Z",
  "completed_at": "2023-01-01T12:01:00.000Z"
}
```

## Status Codes
- **200 OK**: Request was successful.  
- **201 Created**: The resource was successfully created.  
- **400 Bad Request**: Invalid input or malformed request.  
- **401 Unauthorized**: Missing or invalid API key.  
- **403 Forbidden**: The API key is valid but doesn’t have permissions.  
- **404 Not Found**: The requested resource doesn’t exist.  
- **429 Too Many Requests**: You’ve exceeded the allowed rate limit.  
- **500 Internal Server Error**: Something went wrong on the server.  
- **503 Service Unavailable**: Service is temporarily down or overloaded.

## Rate Limits
If there are rate limits, the API will return a 429 status code. You should:
1. Wait a brief period and then retry.  
2. Implement exponential backoff or a similar strategy to handle multiple 429s.

## Error Handling
When errors occur, the API typically returns JSON that includes an error code, message, and HTTP status. Example:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'image' is required",
    "status": 400
  }
}
```

### Common Errors
- Missing or invalid API key → 401 Unauthorized.  
- Invalid JSON format → 400 Bad Request.  
- Resource not found (wrong ID) → 404 Not Found.  
- Exceeding rate limits → 429 Too Many Requests.  

### Retry Strategies
- Use a short delay (e.g., 1 second) between retries.  
- Increase the delay exponentially on repeated failures.  
- Stop retrying after a certain number of attempts or if the error indicates a permanent failure.

## Implementation Guide

### Example Code

#### JavaScript (Node.js)
```javascript
// JavaScript example with proper polling and timeout

const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/ai-image-background-removal-replacement";

async function createAndWaitForPrediction(inputData) {
  try {
    // Step 1: Create the prediction
    const response = await fetch(`${baseUrl}/predictions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-market-key": apiKey
      },
      body: JSON.stringify({
        input: inputData
      })
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();
    const predictionId = prediction.id;

    // Step 2: Poll for results (1s interval, 10m timeout)
    return await pollForResults(predictionId);
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function pollForResults(predictionId) {
  const MAX_TIMEOUT = 600000; // 600 seconds (10 minutes)
  const POLL_INTERVAL = 1000; // 1 second
  const startTime = Date.now();

  while (Date.now() - startTime < MAX_TIMEOUT) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: {
        "x-api-market-key": apiKey
      }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();
    if (prediction.status === "succeeded") {
      return prediction.output; 
    }

    if (prediction.status === "failed") {
      throw new Error(`Prediction failed: ${prediction.error || "Unknown error"}`);
    }

    await delay(POLL_INTERVAL);
  }

  throw new Error("Prediction timed out after 10 minutes");
}
```

#### Python
```python
# Python example with proper polling and timeout

import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/ai-image-background-removal-replacement"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-api-market-key": API_KEY
    }
    response = requests.post(f"{BASE_URL}/predictions", headers=headers, json={"input": input_data})
    
    if response.status_code != 200 and response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    prediction = response.json()
    prediction_id = prediction["id"]
    
    # Step 2: Poll for results
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 600 seconds (10 minutes)
    POLL_INTERVAL = 1  # 1 second
    start_time = time.time()

    while time.time() - start_time < MAX_TIMEOUT:
        headers = {"x-api-market-key": API_KEY}
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)
        
        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")
        
        prediction = response.json()
        
        if prediction["status"] == "succeeded":
            return prediction["output"]
        if prediction["status"] == "failed":
            error_msg = prediction.get("error", "Unknown error")
            raise Exception(f"Prediction failed: {error_msg}")
        
        time.sleep(POLL_INTERVAL)
    
    raise Exception("Prediction timed out after 10 minutes")
```

#### cURL
```bash
# 1) Create a Prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-image-background-removal-replacement/predictions" \
     -H "Content-Type: application/json" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY" \
     -d '{
       "input": {
         "image": "https://example.com/image.jpg"
       }
     }'

# The response will contain a prediction ID, e.g.:
# {"id": "abcd1234", "status": "starting"}

# 2) Poll the Prediction Status
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-image-background-removal-replacement/predictions/abcd1234" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"

# Repeat the GET call until "status" is "succeeded" or "failed".
```

### Performance Optimization
- Use `fast: true` when you need quicker results with a balanced quality level.
- Keep your images near 1MP resolution (or set `original_quality: false`) to reduce processing time and cost.
- Use correct prompts and references to reduce trial-and-error attempts.

## FAQ
1. **Can I replace the background using both a prompt and a reference image?**  
   Yes. You can specify a text prompt for your desired scene or provide a reference image. If you specify both, the reference image will take priority for background style, but the additional prompt may help refine the background details.

2. **How long does the average request take?**  
   Times vary based on complexity and load, but most requests will complete within seconds. For best reliability, consider up to 10 minutes as a safe waiting limit.

3. **Is there a limit on image size?**  
   By default, images scale to 1MP unless you enable `original_quality: true`, which may increase processing time and cost.

4. **Do GET requests for checking status cost money?**  
   No. They’re free. Only image processing (POST requests) incur cost.

5. **Are there any usage limits or monthly fees?**  
   No, this service is purely PAYG. There are no monthly subscription fees or usage caps.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello[at]api.market.

Swap or remove image backgrounds using text prompts or a reference image. Trained exclusively on licensed data, ensuring commerc Try it free on API.market.