Clipdrop / Stability AI API Guide

Clipdrop / Stability AI API guide

Clipdrop — now part of Stability AI — packages a set of practical image-editing operations behind a simple REST API: background removal, object cleanup, super-resolution upscaling, and reimagine variations. Each is its own endpoint that accepts a multipart upload and an x-api-key header, then returns a finished image. This guide documents the request shape for each and lets you fire the single-file operations live with your own key.

How it works

Pick an operation and the tool shows the matching endpoint URL and the form fields it expects. For remove-background and reimagine — which take only an image_file — you can upload an image and run the call directly from your browser; the result image renders inline with a download link. For cleanup (which needs a mask_file) and upscaling (which needs target_width / target_height), the tool prints the exact cURL command so you can wire the extra inputs into your own backend. Your key travels only to clipdrop-api.co.

The four endpoints and when to use each

Remove background (/remove-background) — the most commonly used endpoint. Takes a single image and returns a PNG with the subject isolated on a transparent background. No mask required; the model detects edges automatically. Best results on subjects with clear separation from the background; struggles with very fine hair or objects that match the background colour closely. Returns a PNG regardless of input format.

Cleanup (/cleanup) — removes a specific region of an image rather than the whole background. Requires a second mask_file image of the same pixel dimensions as the source, where white areas indicate the region to erase and black preserves the original. Use this for removing distracting objects, watermarks, or unwanted elements while keeping the rest of the image intact. Because the mask must exactly match the source dimensions, this endpoint is best scripted rather than used interactively.

Upscaling (/upscaling) — increases the resolution of a source image using AI super-resolution. You specify target_width and target_height in pixels. The model infers and reconstructs detail rather than simply interpolating, so outputs typically look sharper than bicubic upscaling at the same scale factor. Check the API documentation for the maximum output resolution; requesting dimensions beyond the cap returns an error.

Reimagine (/reimagine) — generates creative variations of the source image while preserving its general composition and subject. Takes a single image_file and returns a new image in the same style but with variations in details, lighting, or rendering. Useful for exploring design alternatives without starting from a text prompt.

Authentication and request structure

Every Clipdrop API call requires:

POST https://clipdrop-api.co/<endpoint>
Headers: x-api-key: <your_api_key>
Body:    multipart/form-data with image_file (and mask_file for cleanup)

The response is a binary image — Content-Type: image/png or image/jpeg depending on the endpoint. You must read the response body as binary and write it to a file or pass it to an <img src> blob URL in the browser.

Production integration notes

• Keep the key server-side. Browser calls are fine for testing, but a production site should proxy Clipdrop requests through your own backend so the API key never reaches client-side JavaScript. A simple serverless function that accepts the image and forwards it to Clipdrop is the standard pattern.
• Masks must match dimensions exactly. For cleanup, the mask_file must be pixel-for-pixel the same width and height as image_file. A size mismatch returns a 400 error immediately.
• Upscaling caps apply. Request target_width and target_height within the documented maximum or the call returns an error. Check the API docs for the current resolution limit before batching large upscaling jobs.
• Watch your credit consumption. Each API call consumes Stability AI credits at a per-operation rate. Background removal typically costs fewer credits than upscaling. Use the Stability AI credit calculator to budget a batch job before running it at scale.
• Error handling. The API returns standard HTTP status codes. A 401 means your key is invalid or expired; a 402 means you have run out of credits; a 422 is a validation error (check field names and file formats); a 500 is a server error and warrants a retry with backoff.