Assets

Finalize an uploaded asset

Step 2 of the two-step upload: verifies the uploaded object and its size, then flips the asset from pending to ready, recording image width/height when readable. A raster image finalized without a description gets one, plus a category, written in the background as a best-effort courtesy with a monthly cap per organization. Returns 409 if the bytes have not arrived or the asset is already finalized, and 400 on a size mismatch.

post/websiteAssets/{assetId}/finalize

Request

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

Path parameters

assetIdstring required

Response

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