Skip to main content
Convertly CDN URLs have three independent layers you can customize. Each layer solves a different problem — hostname branding, workspace routing, and file identity. 
https://{hostname}/{deliveryKeyOrAlias}/{fileIdOrSlug}?w=1200&format=auto
LayerDefaultOptional upgradeWhat it controls
Hostnamecdn.convertly.shCustom domain (cdn.yourdomain.com)Branding in browser devtools, emails, and social previews
Delivery keycvly_pub_… tokenDelivery alias (marketing, site, products)Which workspace + key rotation without moving files
File identifierStored file UUIDCDN slug (hero-summer, catalog-card-01) or origin pathWhich asset the URL resolves to
All three compose. A production marketing site often ends up with: 
https://cdn.acme.com/marketing/hero-summer?w=1200&format=auto&q=auto
Same transforms, same edge cache, your hostname, a readable key prefix, and a slug instead of a UUID.

​
Storage files: UUID by default

When you upload to Convertly Storage, every file gets an immutable internal id (UUID). CDN URLs use that id in the path: 
https://cdn.convertly.sh/cvly_pub_.../11111111-1111-1111-1111-111111111111?w=800
UUIDs are deliberate:
  • Stable caching — the URL never changes when you rename the display filename in the file manager.
  • Not enumerable — scrapers cannot guess other files in your workspace.
  • Immutable asset pattern — upload a new version as a new file id when you want a fresh cache (see Replacing a file).
Renaming a file in the dashboard (PATCH /api/files/{id} with filename) updates the label in Convertly Storage only. It does not change the CDN URL.

​
Optional CDN slugs

When you want a readable path segment instead of a UUID, set an optional CDN slug on the stored file. Slugs are off by default — nothing changes until you opt in. 
curl -X PATCH "https://convertly.sh/api/files/{fileId}" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cdnSlug": "hero-summer" }'
Then embed: 
https://cdn.convertly.sh/marketing/hero-summer?w=1200&format=auto
(with marketing as your delivery alias)

​
Slug rules

  • 3–80 characters
  • Lowercase letters, digits, hyphens, underscores
  • Must start with a letter or digit
  • Unique per workspace (409 if already taken)
  • Reserved names (api, cdn, v1, …) are blocked
  • Set cdnSlug: null to remove a slug and fall back to the UUID URL

​
UUID URLs still work

When a slug is set, both URLs resolve to the same file: 
https://cdn.convertly.sh/marketing/hero-summer?w=800
https://cdn.convertly.sh/marketing/11111111-1111-1111-1111-111111111111?w=800
Prefer the slug in new markup. Keep the UUID URL working for existing embeds.

​
Slugs vs folders

Folders organize files in the Convertly file manager. They do not appear in CDN URLs today.
FeatureIn file managerIn CDN URL
Folder treeYesNo (not yet)
Display filenameYesNo — use slug or UUID
Optional CDN slugYes (flat, one segment)Yes — {slug} only, not folder/slug
If you need multi-segment paths like catalog/products/hero.jpg on Convertly Storage, use an origin source pointed at a public HTTPS bucket or site today. Folder-aware CDN paths for storage-backed files are on the roadmap.

​
Origin sources: path-based URLs

For assets on a public HTTPS origin (deployed site, public bucket, existing CDN) or a private bucket connected as an origin source, use origin sources: 
https://cdn.convertly.sh/{deliveryKey}/o/{originSlug}/products/hero.jpg?w=1200
You control the full path after /o/{originSlug}/. This is the right choice when:
  • Images live in your repo’s public/ folder on a deployed site
  • You already publish assets to a bucket with folder structure
  • You want SEO-friendly paths without uploading to Convertly Storage
  • Assets live in a private S3/R2/GCS/Azure bucket (connect with encrypted credentials in Image CDN → Sources)

​
Video poster URLs

Video files uploaded to Convertly Storage can serve poster images through the same delivery URL shape as images: 
https://cdn.convertly.sh/{deliveryKey}/{videoFileId}?t=2&w=640&format=webp

​
Video clip URLs

Trim, resize, and transcode stored videos from the CDN — same delivery key, same file id: 
https://cdn.convertly.sh/{deliveryKey}/{videoFileId}?format=mp4&w=1280&so=0&du=30
https://cdn.convertly.sh/{deliveryKey}/{videoFileId}?format=gif&so=1&du=3&w=480
See Transforms — video delivery for all parameters. Without transform params, video URLs redirect to a signed download.

​
Delivery aliases

Delivery aliases replace the long cvly_pub_… token in URLs: 
curl -X POST "https://convertly.sh/api/delivery-keys" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Marketing site", "alias": "marketing" }'
Check availability before creating: 
curl "https://convertly.sh/api/delivery-keys/alias?alias=marketing" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"
Aliases are set at key creation time, globally unique, and safe to embed in HTML alongside custom domains.

​
Custom domains

On Pro and above, bind cdn.yourdomain.com (or similar) to your workspace. The path structure is identical — only the hostname changes. Set the hostname in your SDK config: 
createConvertlyCdn({
  deliveryKey: process.env.NEXT_PUBLIC_CONVERTLY_DELIVERY_KEY!,
  baseUrl: "https://cdn.yourdomain.com",
});
There is no separate dashboard toggle for this — pass baseUrl (or NEXT_PUBLIC_CONVERTLY_CDN_HOST) in your app environment. See Custom domain.

​
Choosing an approach

Convertly Storage + UUID

Simplest default. Upload, copy file id, embed. Best when URLs stay internal or you rotate ids on updates.

Storage + CDN slug

Same as above but readable paths when you opt in. Good for marketing assets with stable public names.

Origin source + path

Assets stay on your site or bucket. Full folder paths. No Convertly upload required.

Alias + custom domain

Brand the hostname and key prefix. Works with UUID or slug file identifiers.

​
Next steps

Operations

Delivery keys, aliases, purge, security.

Custom domain

CNAME setup and SSL provisioning.