Skip to main content

Remove Background (Asset)

GET 
/api/v1/assets/:asset_id/addons/bg_remove

Remove background from an existing asset by asset ID. The original file for the given asset is downloaded and processed.

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 the asset identified by {asset_id}. conversion_name controls the conversion key.
add_new_assetSave the result as a new asset. Optional: metadata=inherit to copy source asset 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, conversion_name must match ^[a-zA-Z0-9_-]{1,30}$.
  • metadata is only allowed when disposition is add_new_asset. Allowed value: inherit.

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.