Assets

Remove an image background

Creates a new PNG asset with the main subject isolated on a transparent background, derived from a ready PNG, JPEG, WebP, GIF, or AVIF image of the same website. The source is unchanged; the result carries sourceAssetId, its own colors and transparentShare, the source category, and a description naming the source. Soft shadows and reflections are removed; trim crops to the subject bounds. Not billed to credits; limited to 10,000 per organization per calendar month. MCP clients that render images also receive the result.

post/websiteAssets/{assetId}/removeBackground

Request

  • Base URL: https://api.cactal.ai/v1
  • URL: https://api.cactal.ai/v1/websiteAssets/{assetId}/removeBackground
  • Auth: HTTP bearer

Path parameters

assetIdstring required

Request body

trimboolean

Crop the result to the subject bounds instead of keeping the source dimensions.

Response

The new transparent asset with its public CDN delivery URLs.

idstring required

Unique asset id. Pass it to websiteAssets.get and websiteAssets.delete.

kind'image' | 'file' required

Asset kind. Each kind has its own MIME allowlist and size limit.

filenamestring required

Original filename supplied at upload (1–255 characters).

mimeTypestring required

MIME type stored for the asset after upload normalization.

descriptionstring nullable required

One-line description supplied at upload, edited later, or generated for dashboard uploads. null when absent.

category'logo' | 'icon' | 'photo' | 'illustration' | 'screenshot' | 'graphic' | 'background' | 'other' nullable required

Image category: logo, icon, photo, illustration, screenshot, graphic, background, or other. null for files and unclassified images.

byteSizeinteger required

Exact file size in bytes.

widthinteger nullable required

Intrinsic pixel width, recorded at finalize for images. null for non-images and formats whose dimensions cannot be read.

heightinteger nullable required

Intrinsic pixel height; see width.

transparentSharenumber nullable required

Fraction of the backdrop that shows through, weighting each pixel by its transparency: 0 for an opaque image, roughly the background area for a cutout, 0.5 for a uniform 50% overlay. null when unknown.

translucentSharenumber nullable required

Fraction of pixels with partial alpha (soft shadows, glows, fades, glass), excluding fully transparent and fully opaque pixels. null when unknown.

sourceAssetIdstring nullable required

For a background-removed image, the id of the asset it was derived from.

urlstring required

Optimized public CDN URL for display. Transformable images use the 1920px default variant; other assets use originalUrl.

originalUrlstring required

Stable public CDN URL for the original bytes. It never expires.

previewUrlstring nullable required

For SVG images, the stable public CDN URL of a rasterized PNG preview (longest edge 1024px) that image models, MCP previews, and favicon fallbacks use. null for other assets and for SVGs that could not be rendered.

srcSetstring nullable required

Ready-to-use responsive image srcset. null when image transformation is unavailable.

variantsobject required

Optimized image URLs keyed by pixel width. Empty when image transformation is unavailable.

createdAtstring date-time required

When the upload was started.

status'pending' | 'ready' required

pending until websiteAssets.finalize confirms the upload; ready once the asset is servable.

Changes

No recorded changes to this operation across all 1 revision of this API.