Skip to main content

​
Named presets

Define a transform bundle once, reference it by name everywhere. Convertly ships built-in presets (no setup required) and supports workspace presets you save via the API.

​
Built-in presets

Available on both the CDN and Media API without creating a database record:
Workspace presets with the same name override built-ins.

​
Workspace presets

A workspace preset is a saved set of params (w, h, q, fit, gravity, format, plus the text-overlay options) stored only in the active workspace. There are two equivalent ways to reference a preset:
Use whichever reads better in your codebase. They resolve identically and share the same edge cache. Individual URL params override the preset’s values for one-off tweaks:

​
Manage presets

Names must be lowercase letters, digits, dashes, or underscores (32 chars max). You can also manage presets visually from Settings → Image CDN → Transform presets.

​
When to use a preset vs inline params

Use a preset when:
  • The same transform shows up in more than 2-3 places in your codebase.
  • A design-system component (Hero, Card, Thumb) has a standard variant.
  • You want to be able to retune quality / size without touching markup.
Inline params are fine for one-off transforms. Both work the same way at the cache level.

​
Signed URLs

By default, CDN URLs are public — anyone with the URL can fetch the image at any size. That’s fine for <img src> on a marketing page. For gated content (paid downloads, subscriber-only assets, signed-link emails), use signed URLs: a server-generated HMAC signature is appended as ?s=…, and any tampering with the URL (changing width, format, swapping the file id or slug) invalidates it.
Signed URLs are tamper-proof by default and do not expire unless you add exp (Unix seconds). Pass expiresAt to POST /api/delivery-keys/{id}/sign to mint time-limited links. After expiry the CDN returns 403 Signed URL has expired.

​
Generate a signed URL

  • {signingKeyId} is the row id you got when you created the signing key (visible in Image CDN → Delivery).
  • The Authorization header carries the CDN signing key token. Keep it server-side.
The returned URL is good only for the exact parameters that were signed. Tampering returns 403. Browsers, CDNs, and <img src> treat it like any other URL — there’s nothing special to do client-side.

​
When to use signed URLs

  • Paid downloads where you want to bind a URL to a specific transform you priced.
  • Subscriber-only galleries where you don’t want anyone to scrape and serve the same images elsewhere.
  • Email campaigns with one-shot artwork that shouldn’t be reused.
For general marketing pages and product catalogs, signed URLs add server-side work (you need to sign at render time) for no real protection — <img src> is public by nature. Use the unsigned form there.

​
Programmatic signing

Most apps should use the POST /api/delivery-keys/{id}/sign endpoint above — it returns a ready-to-embed URL. If you need to sign in application code, the algorithm matches what that endpoint uses: canonical query string (sorted keys, excluding s), HMAC over {endpointNamespace}:{fileId}:{canonicalQuery} with a per-signing-key secret. Include optional exp (Unix seconds) in the canonical string when minting time-limited URLs. Retrieve the secret from the dashboard when you create or rotate a signing key.