Skip to main content
POST
Remove an image background

Authorizations

Authorization
string
header
required

Cactal API key. Create one in the dashboard or via POST /apiKeys. The plaintext key is shown once at creation.

Path Parameters

assetId
string
required
Minimum string length: 1

Body

application/json
trim
boolean
default:false

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

Response

The new transparent asset with its public CDN delivery URLs.

id
string
required

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

kind
enum<string>
required

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

Available options:
image,
file
filename
string
required

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

mimeType
string
required

MIME type stored for the asset after upload normalization.

description
string | null
required

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

category
enum<string> | null
required

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

Available options:
logo,
icon,
photo,
illustration,
screenshot,
graphic,
background,
other
byteSize
integer
required

Exact file size in bytes.

width
integer | null
required

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

height
integer | null
required

Intrinsic pixel height; see width.

colors
object[] | null
required

Up to 8 representative colors sorted by share. null for files and for images that could not be analyzed.

Maximum array length: 8
transparentShare
number | null
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.

Required range: 0 <= x <= 1
translucentShare
number | null
required

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

Required range: 0 <= x <= 1
sourceAssetId
string | null
required

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

url
string
required

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

originalUrl
string
required

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

previewUrl
string | null
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.

srcSet
string | null
required

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

variants
object
required

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

createdAt
string<date-time>
required

When the upload was started.

status
enum<string>
required

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

Available options:
pending,
ready