Skip to main content

Remove Background (Upload)

POST 
/api/v1/assets/file/addons/bg_remove

Remove background from an uploaded image (no asset ID in path). Use image as the multipart-form field name for the uploaded file.

Behaviour and response type are controlled by the mode and disposition query parameters.

Mode​

ValueMeaning
get_imageReturn the processed PNG only. No save. disposition is ignored.
save_imageSave the result only. Response is JSON (no PNG). Requires disposition.
get_image_and_saveReturn the PNG and also save in the background. Requires disposition.

Disposition​

ValueMeaning
add_conversionSave the result as a named conversion on an existing asset. Requires asset_id query parameter. conversion_name controls the conversion key.
add_new_assetSave the result as a new asset. Optional: metadata=inherit with asset_id query to copy source custom data and set lineage.

Validation Rules​

  • If mode is save_image or get_image_and_save, disposition is required.
  • If disposition is add_conversion, asset_id query parameter is required and conversion_name must match ^[a-zA-Z0-9_-]{1,30}$.
  • metadata is only allowed when disposition is add_new_asset. Allowed value: inherit.
  • If metadata is inherit, asset_id query parameter is required.

Response​

  • mode = get_image (default): Content-Type: image/png — PNG bytes in body.
  • mode = get_image_and_save: Content-Type: image/png — PNG bytes in body (save happens in background).
  • mode = save_image, disposition = add_conversion: 
    \{ "status": "ok", "mode": "save_image", "disposition": "add_conversion", "asset_id": "<id&gt;", "conversion_name": "&lt;name&gt;" \}
  • mode = save_image, disposition = add_new_asset: 
    \{ "status": "ok", "mode": "save_image", "disposition": "add_new_asset", "source_asset_id": "<id&gt;", "metadata": "inherit", "new_asset_id": "<id&gt;" \}
    (source_asset_id and metadata only present when provided; new_asset_id when save succeeds.)

Request​

Responses​

Successful operation. Response depends on mode:

  • get_image or get_image_and_save: PNG image bytes with Content-Type: image/png.
  • save_image: JSON object with save details.