Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Generate stable, cacheable image URLs while keeping arbitrary transform creation on a trusted server.

​
Prerequisites

  • An image asset whose status is ready
  • A server-side StackShift client for creating named transforms or signing dynamic transforms

​
Workflow

1
Choose a local SDK preset or persist a named transformation for a repeated design shape.
2
Use a named URL for public, stable recipes; use a signed dynamic URL when dimensions are user- or device-specific.
3
Render responsive srcset values from a bounded list of widths rather than accepting arbitrary browser input.
4
Let StackShift cache derived outputs by source checksum and transform hash.

​
Supported transform grammar

A transform needs a width or height. The URL grammar uses w_<pixels>, h_<pixels>, c_fit or c_fill, f_auto, f_webp, f_avif, f_jpeg, or f_png, q_auto or q_<1-100>, g_centre, g_attention, or g_entropy, and a_first or a_reject for animated input. The SDK accepts these as typed options and serializes them into the normalized spec. f_auto negotiates AVIF first, then WebP, from the request Accept header; if neither is accepted, the service falls back to the source-friendly PNG or JPEG format. Derived output is keyed by the source checksum and normalized transform, so changing the source creates a new derivative.
  • fit preserves the full image inside the requested bounds; fill crops to cover them.
  • gravity chooses the crop anchor: centre, attention, or entropy.
  • animation: "first" uses the first frame; animation: "reject" rejects animated input.
  • A named transform name is persisted server-side and is limited to letters, numbers, dots, underscores, and dashes.
  • The SDK also exports a local assetTransformPresets catalog; using a catalog item does not persist a server-side preset until createTransformation is called.

​
Persist a named transformation

​
Signed dynamic transform

Create signed transform URLs from a trusted backend. The endpoint rejects private assets; private originals should use signedUrl and private delivery, not a public transform URL.

​
Responsive image helper

The JS SDK exports createResponsiveImage for server-rendered src, srcset, and sizes. It accepts 1–12 positive integer widths, signs one URL per width, and defaults sizes to 100vw.

​
Expected result

Repeated requests reuse cached derived assets, while the CDN receives stable or short-lived authorized URLs appropriate to the use case.

StackShift Assets

A grounded guide to Assets storage, uploads, delivery, imports, BYOB and S2, transformations, OCR, media processing, AI jobs, and DAM controls.

Assets SDK quick start

Install the official SDKs, upload a first asset, and handle the readiness state before you publish its URL.