Skip to main content
POST
Finalize an uploaded asset

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

Response

The finalized, ready-to-serve asset with optimized 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