CDN Introduction - Convertly Docs

Convertly’s image CDN turns Convertly Storage files or configured origin-source assets into transform URLs. Embed the URL in <img src> or <video src> and the CDN resizes, re-encodes, smart-crops, trims, and quality-tunes media at request time — every visitor gets the right size and format for their viewport and browser, served from a global edge cache. In practice, you can choose either origin sources or Convertly Storage. If your images already live behind a public HTTPS URL, such as a deployed app’s public folder, a bucket, a CDN, or a web folder, point Convertly at that public origin and optimize those URLs in place. Convertly does not read local project folders or sync repo files. If you want Convertly to host and manage files directly, upload or import them into Convertly Storage.

https://cdn.convertly.sh/{deliveryKey}/{fileId}?w=1200&format=auto&q=auto
https://cdn.convertly.sh/{deliveryKey}/{videoId}?format=mp4&w=1280&so=0&du=30
https://cdn.convertly.sh/{deliveryKey}/o/{originSlug}/products/hero.jpg?w=1200&format=auto&q=auto

A single uploaded 7 MB PNG becomes a ~200 KB WebP or AVIF, sized to the request, served in ~20 ms from the nearest CDN edge.

CDN URLs transform at request time from Convertly Storage file IDs or configured origin sources — no pre-generated variant files required.

The SDK does not upload or sync your repo. Installing @convertly-sh/image or wiring a Next.js loader only rewrites URLs. Before images actually transform and serve through the CDN, you must configure a source Convertly can fetch:

Origin source (most framework sites) — add Settings → Image CDN → Sources with your deployed public HTTPS URL (e.g. slug site, base https://example.com). Then /hero.jpg becomes …/o/site/hero.jpg?w=… and Convertly fetches from your live site.
Convertly Storage — upload files and use file UUIDs in URLs (/{deliveryKey}/{fileId}).

Without one of these, CDN URLs will not resolve to optimized images. See the setup guide.

Storage or origin sources

The public Image CDN supports two source modes:

Convertly Storage: /{deliveryKey}/{fileId} where {fileId} is a stored file UUID.
Source URLs / Origin Sources: /{deliveryKey}/o/{originSlug}/{path...} where {originSlug} is a configured HTTPS origin such as your deployed website, an S3/R2/GCS/Azure public bucket endpoint, a custom CDN domain, or a web folder.

For framework apps, repo-served public/static assets can stay in your codebase as long as the deployed app exposes them over HTTPS. Once https://example.com/hero.jpg is public, create an origin source with slug site and base URL https://example.com. Convertly then fetches that deployed URL, transforms it, and caches the result through /{deliveryKey}/o/site/hero.jpg?w=1200&format=auto. Origin sources support two access modes:

Public HTTPS — a publicly readable bucket endpoint, CDN hostname, or web folder. Convertly stores the origin URL and optional path prefix only.
Private bucket — S3, R2, GCS, or Azure credentials encrypted at rest. Convertly fetches objects with read credentials; the bucket does not need a public URL.

Public origins are validated to block private-network fetches (localhost, RFC1918, etc.). Private origins use signed object APIs instead of public HTTP.

Choose your starting point

Use it from your framework

Install @convertly-sh/image and drop a one-prop <ConvertlyImage> into React, Next.js, Vue, Astro, Solid, or Svelte. Or use the framework-agnostic URL builder anywhere.

URL transforms reference

Every URL parameter: width, height, quality (including q=auto), fit, gravity (smart crop), format (including format=auto), video poster frames, text overlay, save-data quality.

Advanced URL features

Named transformation presets (?preset=hero) and HMAC-signed URLs for gated content.

URL structure

Hostname, delivery alias, UUID vs slug, folders, and origin paths.

Delivery keys, purging, security

Create and revoke delivery keys, purge cached URLs through Cloudflare, replace files, response codes, security model.

Pricing and quotas

Per-plan monthly delivery allowances, what counts as a delivery, what doesn’t.

How it works

Three components:

Delivery key — a publishable cvly_pub_… token or optional alias (marketing). Safe to embed in client markup.
Source — either a Convertly Storage file id (UUID), an optional CDN slug, or an origin-source slug + path.
The CDN URL — https://cdn.convertly.sh/{deliveryKey}/{fileId}?w=… or https://cdn.convertly.sh/{deliveryKey}/o/{originSlug}/{path}?w=…. Convertly transforms the source on the first request, caches the result globally, and serves repeats in milliseconds.

Defaults that match what every visitor actually wants:

format=auto — modern browsers get AVIF or WebP, older browsers get JPEG.
gravity=auto — entropy-based smart cropping picks the salient subject (works well on portraits and product photography).
q=auto — content-aware quality (lower for photos, higher for graphics).
loading="lazy" and decoding="async" on the <img> (when using the SDK).

Once you have a URL, embedding it is identical whether you use the SDK or write the markup by hand:

<img
  src="https://cdn.convertly.sh/cvly_pub_.../11111111-1111-1111-1111-111111111111?w=1200&format=auto&q=auto"
  alt="Hero image"
  loading="lazy"
/>

For real production code, use the SDK so you get responsive srcset for free — see Framework SDKs.

Quick example (Next.js)

npm install @convertly-sh/image

// lib/convertly-loader.ts
import { createConvertlyLoader } from "@convertly-sh/image/nextjs";

export default createConvertlyLoader({
  deliveryKey: process.env.NEXT_PUBLIC_CONVERTLY_DELIVERY_KEY!,
  origin: "site",
  localPassthrough: process.env.NODE_ENV === "development",
});

// next.config.ts
const nextConfig = {
  images: {
    loader: "custom",
    loaderFile: "./lib/convertly-loader.ts",
  },
};
export default nextConfig;

Create site as an origin source for your deployed app’s public HTTPS URL, then existing public assets like /hero.jpg can route through Convertly in production. In Next.js, the loader can keep <Image src="/hero.jpg" width={1200} /> unchanged while it rewrites the rendered image URL to the configured origin-backed CDN URL. During local development, use passthrough behavior because Convertly’s public CDN cannot fetch localhost. For full CDN verification before launch, point the origin at a public preview deployment or HTTPS tunnel. UUID-looking src values still route to Convertly Storage, so managed storage remains an option rather than a required upload step. Other frameworks: React, Vue, Astro, Solid, Svelte, plain HTML.

Pricing and quotas

The image CDN is included with every Convertly plan. Pricing is per CDN delivery — a request that reaches Convertly’s origin. Repeat hits served by an upstream CDN do not count against your meter. With the long-lived immutable cache headers the route sets, a typical site sees a 90–99% cache hit ratio.

Plan	Included deliveries / month	Overage
Free	5,000	Hard cap — upgrade to continue.
Starter ($9/mo)	50,000	Hard cap.
Pro ($19/mo)	500,000	$0.50 per 10,000 deliveries.
Business ($149/mo)	5,000,000	$0.40 per 10,000 deliveries.

Plan	Deliveries / mo	Approx. image views / mo at 95% cache ratio
Free	5,000	~100,000 image views
Starter	50,000	~1 million image views
Pro	500,000	~10 million image views
Business	5,000,000	~100 million image views

Every successful response carries quota headers so you can monitor consumption from any HTTP client:

X-Convertly-CDN-Limit-Month: 500000
X-Convertly-CDN-Used-Month: 12483
X-Convertly-CDN-Remaining-Month: 487517

Convertly does not separately meter CDN bandwidth at launch. If you serve unusual volumes (sustained 100 GB+ of egress per month) we may reach out — in practice, edge caching resolves this for almost every account.

Response codes

Status	When
`200`	Success. Body is the transformed image or video with the matching `Content-Type`. Video poster URLs and `format=mp4/webm/gif` transforms also return `200`.
`302`	Non-image file (PDF, video, audio) with no transform params — redirects to a signed download.
`400`	Missing `deliveryKey` or `fileId`, or malformed URL.
`403`	Signed URL signature failed verification.
`404`	Unknown delivery key, or the file does not belong to that key’s workspace.
`429`	Monthly delivery cap reached on a hard-capped plan (Free / Starter). Response carries `Cache-Control: no-store`.
`500`	Image transform failed (corrupt source, unsupported format).
`502`	Could not fetch the source image from storage.

Detailed behaviour for each (including signed URL errors, purge invalidation, and replacing a file) lives in Operations.

​Storage or origin sources

​Choose your starting point

Use it from your framework

URL transforms reference

Advanced URL features

URL structure

Delivery keys, purging, security

Pricing and quotas

​How it works

​Quick example (Next.js)

​Pricing and quotas

​Response codes

Storage or origin sources

Choose your starting point

How it works

Quick example (Next.js)

Pricing and quotas

Response codes