Name: BirefNet – High-Res Image Segmentation | $0.05/call | API.market
Brand: magicapi
SKU: api-magicapi-high-res-image-segmentation-api
Availability: InStock
Author: API Market

Shashank Agarwal

# 🧩 High-Res Image Segmentation API (BirefNet)

## Overview
This API provides high-resolution, dichotomous (binary or two-class) image segmentation. Powered by BirefNet (Bilateral Reference for High-Resolution Dichotomous Image Segmentation), it accurately identifies and extracts foreground objects from complex backgrounds. You can quickly process an image into a high-resolution segmentation mask—ideal for content analysis, background removal, object detection, or any vision task requiring precise delineation.

## Features
- Fast, high-resolution image segmentation for precise demarcation.  
- Dichotomous segmentation with consistent performance on diverse image scenes.  
- Optimized for complex visual tasks, including object isolation and content filtering.  
- Supports custom resolutions in WxH format for flexible integration into different workflows.

## Use Cases
1. E-Commerce Product Listing: Automatically remove and replace clothing or accessory backgrounds for clean product images.  
2. Medical Imaging Analysis: Segment X-ray or CT images for precise focus on abnormal regions, speeding up clinical workflows.  
3. Autonomous Vehicles: Distinguish key objects (e.g., pedestrians, cars) from the environment in real time.  
4. Creative Content Editing: Extract objects or people from a photo to create custom collages or marketing materials.  
5. Security & Surveillance: Quickly separate objects of interest from background noise for threat detection.

## Visual Examples

### Example Input
Below is an example input image showcasing a dog. The model would segment this dog from its background:

![Example input image: A dog waiting to be segmented](https://blog.api.market/wp-content/uploads/2026/04/high-res-image-segmentation-scaled.jpg)

### Example Output
Here is an example output image produced by the API, showing the resulting segmentation (background removed or masked):

![Example output image: A segmented dog on a transparent or uniform background](https://blog.api.market/wp-content/uploads/2026/04/output-dog-scaled.png)

## Pricing
- 1 API unit equals 1 image processed.  
- GET requests to check prediction status (GET /api/v1/magicapi/high-res-image-segmentation-api/predictions/{id}) are free and do not count toward API unit usage.  
- Tiered pricing is available based on usage volume. Contact us for high-volume discounts or custom pricing options.

## API Documentation

### Base URL
All requests to this API should be sent to:
```
https://prod.api.market/api/v1/magicapi/high-res-image-segmentation-api
```

### Authentication
Use your API key to authenticate requests. Include the following header in every request:
```
x-magicapi-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
Image segmentation runs asynchronously. The typical workflow:
1. Send a POST request to create a segmentation prediction.  
2. Receive a prediction ID in the immediate response.  
3. Poll the GET endpoint with that prediction ID to check status.  
4. When the status becomes "succeeded," you can retrieve the result.  

Implementation details:  
- Use a polling interval of 1 second between status checks.  
- Allow up to 600 seconds (10 minutes) before considering the request timed out.  
- If status is "failed," handle or report the error.  

### Endpoints

#### 1. Create a Prediction
• Method: POST  
• Path: /api/v1/magicapi/high-res-image-segmentation-api/predictions  
• Description: Creates a new image segmentation prediction request.

Example Request:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/high-res-image-segmentation-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "input": {
      "image": "https://example.com/image.jpg",
      "resolution": "1024x1024"
    }
  }'
```

Example Response (JSON):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "f74986db0355b58403ed20963af156525e2891ea3c2d499bfbfb2a28cd87c5d7",
  "status": "starting",
  "created_at": "2025-05-18T08:20:57.980Z"
}
```

#### 2. Get Prediction Status and Result
• Method: GET  
• Path: /api/v1/magicapi/high-res-image-segmentation-api/predictions/{id}  
• Description: Checks the status of an existing prediction request and retrieves the result once it's completed.

Example Request:
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/high-res-image-segmentation-api/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

Example Response (JSON):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://example.com/output-segmented.png",
  "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: The request was successful.  
- 201 Created: A new resource (prediction) was successfully created.  
- 400 Bad Request: Input parameters are invalid or malformed.  
- 401 Unauthorized: The API key is missing or invalid.  
- 403 Forbidden: The API key is valid but does not have the required permissions.  
- 404 Not Found: The requested resource does not exist.  
- 429 Too Many Requests: Rate limit exceeded; retry after the specified time.  
- 500 Internal Server Error: A general server error occurred.  
- 503 Service Unavailable: Service is under maintenance or temporarily overloaded.

## Rate Limits
The API enforces rate limits to ensure consistent performance for all users. If you exceed the allowed request rate, you will receive a 429 status code. Implement exponential backoff or a suitable retry strategy to handle such responses.

## Error Handling
When an error occurs, the API returns a JSON error object. For example:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'image' is required",
    "status": 400
  }
}
```
Recommendations:  
- Parse the error object to identify the issue.  
- Correct invalid parameters.  
- In case of 429 responses, implement a delay before retrying.

## Implementation Guide

### JavaScript (Node.js) Example
```javascript
// Example JavaScript code demonstrating prediction creation and polling
const fetch = require("node-fetch");

const API_KEY = "YOUR_API_MARKET_KEY";
const BASE_URL = "https://prod.api.market/api/v1/magicapi/high-res-image-segmentation-api";

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

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

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

    // Step 2: Poll until the prediction completes or fails
    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(`${BASE_URL}/predictions/${predictionId}`, {
      headers: {
        "x-magicapi-key": API_KEY
      }
    });

    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");
}

// Usage example:
// createAndWaitForPrediction({
//   image: "https://example.com/image.jpg",
//   resolution: "1024x1024"
// })
//   .then(output => console.log("Segmentation output URL:", output))
//   .catch(err => console.error(err));
```

### Python Example
```python
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/high-res-image-segmentation-api"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-magicapi-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 until complete or fail
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 10 minutes
    POLL_INTERVAL = 1  # 1 second
    start_time = time.time()
    
    while time.time() - start_time < MAX_TIMEOUT:
        headers = { "x-magicapi-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")

# Usage example:
# output_url = create_and_wait_for_prediction({"image": "https://example.com/image.jpg", "resolution": "1024x1024"})
# print("Segmentation output URL:", output_url)
```

### cURL Example
```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/high-res-image-segmentation-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "input": {
      "image": "https://example.com/image.jpg",
      "resolution": "1024x1024"
    }
  }'

# Sample response (JSON):
# {
#   "id": "abcd1234",
#   "status": "starting",
#   ...
# }

# Step 2: Poll for status until "succeeded"
curl -X GET "https://prod.api.market/api/v1/magicapi/high-res-image-segmentation-api/predictions/abcd1234" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
- Resize or compress large images before sending to reduce processing time and cost.  
- Only run segmentation on the portions of the image where needed (e.g., if you already know the region of interest).  
- Leverage caching strategies for repeated segmentation on the same input.

## FAQ
1. **How large can my images be?**  
   We recommend standard resolutions up to your chosen size, but you can specify higher values if needed. Just keep in mind that larger images take longer to process.

2. **How quickly can I expect a response?**  
   Most requests complete in a few seconds. For extremely high resolutions or complex images, it might take up to a minute or more.

3. **Do I pay for unsuccessful predictions?**  
   Yes, creating a prediction request consumes an API unit whether or not it succeeds. We encourage handling errors carefully to minimize wasted calls.

4. **Can I segment multiple objects in an image?**  
   Yes, the model will produce a mask that attempts to capture all main foreground objects.

5. **Can I choose custom segmentations, like multi-class?**  
   This particular model focuses on binary (dichotomous) segmentation, separating foreground from background. For multi-class segmentation, consider other specialized APIs.

## 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.

Achieve precise, high-resolution image segmentation. Extract foreground objects and create clean masks from any image. Try it free on API.market.