KeyoAPI

← Blog ·

Bulk Background Removal API for E-Commerce Product Catalogs

E-commerce catalogs often contain thousands of product images collected from different suppliers, studios, and internal teams.

Key Takeaways

1. Introduction: Why Catalog Teams Need Bulk Background Removal

E-commerce catalogs often contain thousands of product images collected from different suppliers, studios, and internal teams. Some images use white backgrounds, while others contain shadows, furniture, packaging materials, inconsistent lighting, or visible parts of the original studio setup. When these images are published together, the catalog can look inconsistent even when the product data is accurate.

Manual background removal is possible for a small collection, but it becomes difficult to manage at scale. A team may need to edit hundreds or thousands of images before a seasonal launch, supplier migration, marketplace submission, or catalog redesign. Manual work also introduces quality variation: one editor may preserve fine edges, while another may remove straps, handles, transparent parts, or product details.

A bulk background removal API addresses this specific operational problem. Instead of opening each image in an editor, an application sends product images to an image-processing endpoint, receives the processed result, validates the output, and stores it for later use.

The important distinction is that an API does not automatically solve every catalog-image problem. It automates a repeatable transformation, but the surrounding workflow still needs to decide:

This article explains how to design that workflow with a bulk background removal API and how to connect it to KeyoAPI using a server-side integration.

2. How a Bulk Background Removal Workflow Works

The core conclusion is straightforward: bulk processing is most reliable when it is designed as a pipeline rather than a loop of untracked API calls.

A typical workflow contains six stages:

  1. Collect input images
  2. Validate image files and metadata
  3. Submit multipart requests to the background removal endpoint
  4. Receive and store the processed output
  5. Run quality checks
  6. Publish or route exceptions for review

Input collection and validation

Before sending an image, the application should confirm that the file exists, can be decoded, and belongs to the expected product record. Useful metadata includes:

This metadata makes the workflow restartable. If a process stops after 3,000 of 5,000 images, the application can resume from the remaining records instead of repeating completed work.

Validation should also reject obvious problems early, such as missing files, unsupported extensions, zero-byte uploads, or files that cannot be opened as images. Early validation saves API usage and makes error reporting easier.

Multipart upload

Background removal requests generally need the image file itself, so the request should use multipart/form-data. The model identifier should be supplied according to the current KeyoAPI documentation. The API key belongs in the Authorization header using the Bearer format:

Authorization: Bearer YOUR_API_KEY

The API key should remain on a backend server, worker, or secure integration service. It should not be placed in browser JavaScript, a mobile application bundle, a public repository, or a client-side image-processing tool.

Output handling

The application should treat the API response as a file-processing result, not merely as a successful HTTP status. It should verify that:

A practical naming pattern might include a product identifier, processing version, and output format. Keeping the original file prevents irreversible catalog changes and supports later reprocessing.

Scenario: supplier catalog migration

Suppose a retailer receives 20,000 product images from a new supplier. The files use inconsistent backgrounds and naming conventions. A robust workflow first maps each image to a product identifier, validates the files, processes them in controlled batches, stores the results separately, and publishes only images that pass validation.

If a subset contains complex edges or unexpected output, those records can be routed to a review queue without blocking the entire migration.

3. Connecting to KeyoAPI

KeyoAPI is an independent, OpenAI-compatible multi-model API gateway. It provides a common API base URL for supported services, including image-related models. It is not an official service of OpenAI, Anthropic, Google, DeepSeek, or other model providers.

For the background removal use case, the relevant endpoint is:

POST https://www.keyoapi.xyz/v1/images/mattings

The background removal model specified for this integration is:

RMBG-2.0

Model availability and request parameters can change. Before building or deploying an integration, check the current KeyoAPI documentation and retrieve the live model catalog where appropriate.

Basic curl example

The following example demonstrates the request pattern for a local image file:

curl -X POST "https://www.keyoapi.xyz/v1/images/mattings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=RMBG-2.0" \
  -F "image=@./product-shoe.jpg" \
  --output./product-shoe-removed.png

The exact multipart field names should be confirmed against the current endpoint documentation before production deployment. The image field shown here represents the uploaded product image, while the output file is written locally by curl.

The command uses a placeholder API key intentionally. Replace YOUR_API_KEY with a key created in the KeyoAPI dashboard, but do not commit the key to source control or expose it in client-side code.

Server-side request pattern

A production application typically performs this operation from a backend worker:

Read catalog record -> Open original image -> Validate file and product ID -> Send multipart request with Bearer token -> Check HTTP status and response body -> Validate returned image -> Store output -> Update processing status

This structure makes the integration observable. A catalog administrator can see whether an image is pending, completed, failed, or awaiting manual review.

Model discovery

Applications should not permanently assume that a model will remain available. KeyoAPI documents the following endpoint for checking the current model list:

curl "https://www.keyoapi.xyz/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use a model ID returned by the live endpoint and the current documentation when configuring a deployment. For a controlled production system, it is useful to store the selected model ID in configuration rather than scattering it through application code.

4. Designing Bulk Processing for Reliability

The key production decision is how to control work volume and recover from partial failure. A simple loop may work for a small test, but catalog-scale processing needs explicit job states and error handling.

Use a queue or worker model

A queue-based architecture is usually easier to monitor than a single long-running request process. Each image becomes a job with a status such as:

Status Meaning
pending Waiting to be processed
processing Assigned to a worker
completed Output stored and validated
retryable_error Temporary failure; eligible for another attempt
failed Requires investigation or manual action
review Output exists but needs human inspection

A worker can claim a limited number of jobs, send requests, and update the status after each result. This prevents one failed image from terminating the entire batch.

Handle common HTTP failures

KeyoAPI documentation identifies several common request failures:

Not every failure should be retried. A malformed image, invalid parameter, or incorrect endpoint configuration will usually fail again until the input or configuration changes. Temporary service or network failures may be suitable for bounded retries.

A conservative retry policy should include:

Preserve idempotency

Bulk jobs are often interrupted. To avoid creating inconsistent records, calculate a stable processing identity from the product ID, source image version, and selected model configuration. Before submitting a new request, check whether a valid output already exists for that identity.

This avoids unnecessary repeat processing when a worker restarts after successfully storing an output but before updating the catalog database.

Separate processing from publishing

Background removal should not automatically overwrite the live catalog image without validation. Store the processed image in a staging location first. After quality checks, the catalog system can promote it to the published asset.

This separation is especially important for:

The API can automate the initial transformation, while a review step protects customer-facing quality.

5. Output Expectations and Quality Control

A background removal result should be treated as a new image asset whose dimensions, format, and transparency need to be verified. Do not assume that every output is immediately suitable for every marketplace or storefront.

What to validate

After receiving the result, inspect:

An automated check can flag unusual cases. For example, an output with an extremely small non-transparent area may indicate that the product was incorrectly removed. An output with almost the entire canvas marked as foreground may indicate that the original background was not separated as expected. These checks should be used as review signals, not as unsupported claims about model accuracy.

Input categories that deserve review

Some images are naturally more difficult than a simple product centered on a plain background. Add a manual-review path for images containing:

The right operational goal is not to force every result into automatic publication. It is to process routine images efficiently while making difficult cases visible.

Format and publishing decisions

A transparent result may be useful for storefront composition, marketplace templates, or consistent product-card backgrounds. Other destinations may require a solid background or a specific file format. Those transformations should be handled as explicit downstream steps, because “background removed” and “ready for every channel” are different requirements.

Keep the original image and processed image as separate assets. This supports:

6. Comparison: Manual Editing, Batch Tools, and APIs

Different catalog teams need different operating models. The right choice depends on volume, integration requirements, and the amount of human review required.

Approach Best fit Main strength Main limitation
Manual editing Small batches or highly art-directed images Direct visual control Slow and difficult to standardize
Desktop batch processing Recurring jobs managed by a creative team Familiar workflow for non-developers Less integrated with catalog systems
Background removal API Automated catalog pipelines and supplier imports Programmatic processing and status tracking Requires engineering, monitoring, and quality checks
Hybrid workflow Large catalogs with difficult exceptions Automation for routine images plus human review Requires clear routing and operational ownership

A bulk background removal API is a strong fit when the image operation is part of a larger system. For example, a product-information-management platform can trigger processing when a new supplier image arrives. An e-commerce platform can process only images missing a standardized asset. A migration script can create staged outputs before a catalog launch.

An API is less suitable when every image requires extensive artistic retouching, compositing, color correction, or layout-specific adjustments. Background removal can be one step in a creative workflow, but it should not be presented as a complete replacement for professional image editing in every scenario.

Cost and operational planning

Usage-based image processing should be measured against the number of images, reprocessing frequency, and failure rate. Do not hard-code prices in application documentation because model availability and pricing can change.

Model availability and pricing may change. Check the KeyoAPI model catalog for current information.

A practical cost-control strategy is to validate files before submission, avoid duplicate jobs, process only changed source images, and monitor retries separately from successful requests.

7. Production Checklist

Before enabling bulk processing for a live catalog, verify the following:

8. FAQ

What is a bulk background removal API?

A bulk background removal API is a programmatic image-processing service that accepts product images and returns processed results with the background removed. It allows an application to process catalog images from a script, queue, import workflow, or product-information-management system.

How should I authenticate requests to KeyoAPI?

Use a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Create the API key in the KeyoAPI dashboard and keep it on the server. Never expose it in browser code, mobile application packages, public repositories, or screenshots.

Should every processed image be published automatically?

No. Routine images may pass automated validation, but difficult subjects can require human review. A safer workflow stores the result in staging, validates the file and product association, and publishes it only after the configured quality checks pass.

What should I do if a request returns 401 or 429?

For a 401 response, check that the Bearer token is present, correctly formatted, valid, and not revoked. For a 429 response, slow the worker, apply bounded retry delays, and inspect the current service documentation. Do not respond to either error by exposing the API key or retrying indefinitely.

9. Conclusion

A bulk background removal API is most valuable when it is integrated into a controlled catalog workflow. The API request is only one part of the solution: reliable results also require input validation, server-side authentication, durable job states, output verification, retry handling, staged publishing, and a review path for complex images.

KeyoAPI provides an API gateway approach for developers who want to connect image-processing capabilities through a consistent endpoint and Bearer-token authentication. For the background removal workflow described here, use the documented POST /v1/images/mattings endpoint with the RMBG-2.0 model configuration, then confirm current availability and parameters through the live documentation and model catalog.

To begin, create a KeyoAPI API key, test the multipart request with a small set of representative product images, and measure the complete workflow before scheduling a large catalog batch.

← Blog · Home · Docs