KeyoAPI

← Blog ·

RMBG-2.0 API for Product Photos: A Practical Integration Guide

A developer-focused guide to server-side multipart uploads, output validation, production limits, and safe ecommerce image workflows.

Key Takeaways

1. Introduction

Product photography is often created in inconsistent environments. A retailer may receive images from multiple suppliers, each using a different background, lighting setup, camera angle, or file format. Before those images can appear in a catalog or marketplace, a developer may need to isolate the product, place it on a neutral background, or prepare it for a standardized design template.

Manual editing does not scale well when a catalog contains hundreds or thousands of images. A background removal API provides a way to add this operation to an existing upload, catalog, or media-processing workflow.

This guide explains how to integrate the RMBG-2.0 API for product photos through KeyoAPI. It focuses on the concrete developer problem: sending a product image through a server-side API request and handling the result safely in production.

The article covers:

  1. How to confirm model availability and authenticate requests.
  2. How to submit a product image using multipart upload.
  3. What to expect from the input and output workflow.
  4. How to handle common errors and production risks.
  5. When this approach is appropriate for an ecommerce or catalog pipeline.

2. How the RMBG-2.0 API Fits a Product-Image Workflow

Core conclusion

The API should be treated as one processing step in a larger image pipeline, not as a complete product-content system. The most reliable implementations validate images before upload, call the API from a protected backend, inspect the returned media, and then save the processed asset with its own metadata.

A typical product-photo workflow looks like this:

Supplier or user upload ↓
Input validation and file-size checks ↓
Server-side multipart request ↓
RMBG-2.0 background removal ↓
Output validation ↓
Object storage or media service ↓
Catalog, marketplace, or design workflow

This separation is useful because background removal and catalog management have different responsibilities. The API processes the image; your application decides where the result is stored, how it is named, whether it requires review, and which storefront uses it.

Common product-photo scenarios

The RMBG-2.0 API may be useful in scenarios such as:

The correct result depends on the source image. A product photographed against a high-contrast, uncluttered background is generally easier to process than a product with fine hair, transparent materials, reflective surfaces, or strong visual overlap with the background.

Recommended architecture

Use a backend service to manage the request:

This architecture keeps the API key private and makes it easier to add retries, logging, moderation, file cleanup, and human review later.

3. Authentication and Model Availability

Core conclusion

Do not hard-code assumptions about model availability. Confirm the current model catalog before deploying an integration, and keep the API key in a server-side environment variable.

KeyoAPI uses Bearer-token authentication. The request header follows this format:

Authorization: Bearer YOUR_API_KEY

Create the key from the KeyoAPI dashboard and store it in a secret manager or environment variable. Do not place it in:

Check the live model catalog

Model availability can change. Before using RMBG-2.0, check 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 or listed in the current KeyoAPI documentation. If RMBG-2.0 is not currently available, do not assume that the request will work simply because an older integration used that model.

Environment configuration

A server-side environment might include:

export KEYOAPI_API_KEY="YOUR_API_KEY"

In a real deployment, use the secret-management facilities provided by your hosting platform rather than committing this value to a configuration file.

4. Sending a Product Image with Multipart Upload

Core conclusion

For a local product image, use a multipart form upload and include the model identifier in the request. The background removal endpoint is:

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

A curl request provides a simple integration test:

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

Replace YOUR_API_KEY with a valid server-side key and replace product-photo.jpg with the path to the source image.

Why multipart matters

Multipart form data sends the image as a file part rather than embedding the binary file into a JSON request. This is a natural format for server-side upload workflows and allows the request to carry both:

When using curl, the -F options construct the multipart request automatically. When using an HTTP library, ensure that the library creates the multipart boundary correctly. Do not manually set an incorrect Content-Type boundary.

Input expectations

Before sending a product image, your application should check:

The exact supported formats, limits, and response behavior should be confirmed in the current KeyoAPI documentation. Avoid building a production system around undocumented assumptions.

Output handling

The API response should be handled as a media-processing result rather than blindly written to storage. Depending on the current endpoint behavior, your application may need to process returned image data or another documented response representation.

A robust implementation should:

  1. Check the HTTP status code.
  2. Inspect the response Content-Type.
  3. Confirm that the response body is not empty.
  4. Validate that the resulting file can be opened as an image.
  5. Store it with a new filename or object key.
  6. Preserve a link to the original image for comparison and reprocessing.

For example, do not overwrite the original supplier photo immediately. A safer naming pattern is:

products/1234/source/product-photo.jpg
products/1234/processed/product-photo-rmbg.png

The final extension should match the actual returned media format. If the API documentation specifies a particular response format, follow that specification rather than assuming that every response is PNG or that transparency is always represented in the same way.

5. Production Error Handling and Operational Cautions

Core conclusion

A successful prototype is not enough for a catalog pipeline. Production code must distinguish authentication errors, temporary request failures, invalid input, and output-validation failures.

Common errors

401 Unauthorized

This usually indicates an authentication problem, such as:

Check that the request contains:

Authorization: Bearer YOUR_API_KEY

Do not solve a 401 by repeatedly retrying the same request. First verify the environment variable, key status, endpoint, and header format.

429 Too Many Requests

A 429 response indicates that the request cannot be processed at that moment because of request-volume or service constraints. Your application should:

Do not assume a fixed rate limit or promise a specific retry time unless the current documentation defines it.

Other unsuccessful responses

For other non-success responses, log enough information to diagnose the problem without exposing the API key or sensitive product data. Useful fields include:

Avoid logging the full image or embedding secret headers in application logs.

Add idempotent job tracking

Catalog systems frequently retry jobs after a timeout. Without job tracking, one source image may produce several duplicate assets.

Use an internal record containing fields such as:

Field Purpose
job_id Identifies the processing request
product_id Links the image to a catalog item
source_hash Detects whether the source image changed
status Tracks queued, processing, completed, or failed state
attempt_count Prevents unlimited retries
output_key Stores the processed asset location
error_code Supports operational diagnosis

This approach also makes it easier to reprocess only the images affected by a model or workflow change.

Quality review is still necessary

Background removal is not the same as product-quality assurance. Add review rules for images containing:

For high-value listings, compare the processed result with the original before publishing. A human review step may be appropriate when a cutout directly affects customer trust or marketplace compliance.

6. Integration Decision Guide

The following table summarizes practical decisions for a product-photo implementation:

Decision area Recommended approach Why it matters
API location Call from a protected backend Prevents API-key exposure
Authentication Bearer token in a secret environment variable Keeps credentials outside public code
Upload method Multipart form data Sends the image and model parameter together
Model selection Confirm RMBG-2.0 in the live model catalog Availability can change
Original image Preserve it separately Enables review and reprocessing
Output validation Check status, content type, and image readability Prevents corrupted assets entering the catalog
Retry behavior Use bounded, logged retries Reduces duplicate jobs and retry storms
Quality control Add automated checks and human review where needed Handles difficult product categories
Cost control Monitor usage and consult live pricing Prevents outdated assumptions

When to use a queue

A queue is useful when image processing is not required to complete during the user’s upload request. For example:

  1. Accept the product image.
  2. Create a processing job.
  3. Return a pending status.
  4. Process the image asynchronously.
  5. Notify the catalog service when the output is ready.

This design protects the upload endpoint from long-running work and makes retry handling more predictable.

For small internal tools, a synchronous request may be adequate. For supplier feeds or bulk catalog imports, asynchronous processing is usually easier to operate.

Pricing and model availability

KeyoAPI uses prepaid API credits and usage-based billing. Model availability and pricing may change. Check the KeyoAPI model catalog for current information.

Review the current pricing page before estimating catalog-processing costs:

/pricing-list

Do not place a fixed price in application documentation unless it is maintained from the live source. A useful internal estimate should account for the number of source images, reprocessing jobs, failed attempts, and manual-review workflows.

7. FAQ

Is the RMBG-2.0 API suitable for ecommerce product images?

It can be suitable for automating background-removal steps in ecommerce workflows, especially when product images are consistently framed and reasonably separated from their backgrounds. Difficult materials and complex scenes should be tested before full catalog migration.

Which endpoint should developers use?

The integration endpoint is:

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

Send the request with Bearer-token authentication and multipart form data, including the RMBG-2.0 model identifier and the product image file.

Can I put the API key in frontend code?

No. Keep the API key on your server. Browser code, mobile applications, public repositories, and screenshots can expose credentials and allow unauthorized use.

How do I know whether RMBG-2.0 is currently available?

Query the live model list:

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

Use the model ID returned by the current endpoint or documented in the current model catalog.

8. Conclusion

The RMBG-2.0 API can provide a practical background-removal step for product-photo pipelines, but the quality of the integration depends on more than one API request. Developers should validate source files, use multipart uploads, protect the Bearer token, confirm model availability, validate the returned media, and preserve the original asset.

For a quick server-side test, call:

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

with model=RMBG-2.0 and a multipart image upload. For production, add job tracking, bounded retries, output checks, and review rules for difficult product categories.

To begin, create a KeyoAPI account and generate an API key from the dashboard. Then review the current documentation, model catalog, and pricing before connecting the RMBG-2.0 workflow to your product-image pipeline.

Editorial scope and verification

This guide is for developers building a product-image workflow, not a claim that every image will produce a perfect cutout. The integration contract, model availability, supported formats, response type, limits, and pricing must be checked against the current provider documentation before deployment. The examples below show the application boundary and validation responsibilities; they do not replace a live endpoint test.

What to verify before shipping

Decision rule

Use this API when background removal is one controlled step in a larger catalog pipeline. Add human review for high-value listings or difficult source images. Do not publish a processed asset merely because the HTTP request succeeded; validate the pixels and the business result first.

← Blog · Home · Docs