Skip to main content

Remove Background (Bulk)

POST 
/api/v1/assets/bulk/bg_remove

Remove the background from a whole selection of existing assets in one call — up to 100 asset IDs.

Unlike the single-asset endpoints, this is asynchronous: the call returns 202 with a job_id and the cut-outs are produced in the background. Poll GET /api/v1/jobs/{job_id} for progress and completion.

Credits are all-or-nothing​

Each asset in the batch is a separate paid cut-out. The whole batch is pre-flighted against your AI credit balance before any work starts: if the wallet cannot cover every asset in the selection the request is rejected with 402 and nothing is processed. This is deliberate — debiting per asset as the run proceeds would otherwise leave a half-processed selection behind when the balance ran out mid-batch.

The credits_required field in the 202 response reports what the batch reserved.

One run at a time​

Only one bulk cut-out may run per user at a time. Submitting a second batch while one is still running returns 409 already_running — a guard against a double-clicked selection being charged twice. The lock is released when the run finishes.

Output​

dispositionResult
add_new_assetEach cut-out is saved as a new asset (default). The new asset's original is always private.
add_conversionEach cut-out is saved as a named conversion on its own source asset, keyed by conversion_name.

public applies to add_conversion only, and defaults to true — a cut-out is normally produced in order to be published.

Request​

Responses​

Batch accepted and queued. Poll the job for progress.