CDN Introduction

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/{endpointNamespace}/{fileIdOrSlug}?w=1200&format=auto&q=auto
https://cdn.convertly.sh/{endpointNamespace}/{videoId}?format=mp4&w=1280&so=0&du=30
https://cdn.convertly.sh/{endpointNamespace}/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 generated CDN slugs or file UUIDs in URLs (/{endpointNamespace}/{fileIdOrSlug}).

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

Storage or origin sources

Convertly uses HDAM (Hybrid Digital Asset Management): a managed library plus external origins, with CDN URLs that resolve library files directly by id or slug. That keeps URLs short and stable when you reorganize the workspace. Origin sources remain fully supported for assets on your site or bucket. The public Image CDN supports two source modes:

Convertly Storage: /{endpointNamespace}/{fileIdOrSlug} where {fileIdOrSlug} is a stored file UUID or generated CDN slug.
Source URLs / Origin Sources: /{endpointNamespace}/o/{originSlug}/{path...} where {originSlug} is a configured HTTPS origin such as your deployed website, a public object 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 /{endpointNamespace}/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: object storage 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.

Transform Lab

Preview posters, clips, and image transforms in the dashboard and copy production-ready URLs.

URL transforms reference

Parameter index plus focused guides: Forma AI, watermarks, face and plate privacy, crop & fit, text, format, and video.

Advanced URL features

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

Smart cropping & analysis

Focal points, face-aware crop, palette extraction, and the analyze API.

Responsive images

srcset, <picture> art direction, and <ConvertlyCdnProvider>.

Client Hints

Browser-driven width and DPR without hard-coding w on every URL.

CDN performance

Cache strategy, origin deliverability, and purge by tag.

Social & OG images

Open Graph cards and platform previews from one hero file.

Setup walkthrough

End-to-end CDN setup for your framework.

URL structure

Hostname, CDN endpoint namespace, UUID vs slug, folders, and origin paths.

Convertly HDAM

Hybrid digital asset management: library, origins, metadata, and stable CDN URLs.

Delivery, purging, security

Access policies, cache-tag purge, GCS/Azure origins, URL signing keys, and security model.

Pricing and quotas

Per-plan monthly origin request allowances, what counts, what doesn’t.

Plan limits

Full quota reference for CDN, storage, streaming, and Forma AI.

How it works

Three components:

CDN endpoint: a stable delivery identity with a public URL namespace such as assets-acme or marketing. Choose whether it accepts public URLs or requires signed URLs.
Source: either a Convertly Storage file id (UUID), a generated/editable CDN slug, or an origin-source slug + path.
The CDN URL. https://cdn.convertly.sh/{endpointNamespace}/{fileIdOrSlug}?w=… or https://cdn.convertly.sh/{endpointNamespace}/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/assets-acme/hero-summer?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({
  namespace: process.env.NEXT_PUBLIC_CONVERTLY_CDN_NAMESPACE!,
  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 origin request: an uncached image CDN request that reaches Convertly to fetch or transform a source. Repeat hits served by an upstream edge cache do not count against your meter. With long-lived immutable cache headers, a typical site sees a 90-99% cache hit ratio. Plan prices are on Pricing. Included origin request allowances:

Plan	Included origin requests / month	Overage
Free	5,000	Hard cap. Upgrade to continue.
Starter	50,000	Hard cap.
Pro	500,000	Metered overage when enabled (rates)
Business	5,000,000	Metered overage when enabled (rates)
Enterprise	Contracted	Contracted

Plan	Origin requests / 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

Full quota tables (custom domains, CDN endpoints, and other meters) are in Limits. Estimated bandwidth depends on output size. As a rough planning guide, 100,000 optimized image views at 200 KB each is about 20 GB of viewer transfer. Origin requests are usually much lower than viewer loads because repeated URLs are served from edge and browser caches. 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

Edge-cache hits do not consume your origin-request allowance. Convertly does not separately charge for bandwidth at launch. Every plan also has generous edge-delivery and delivered-data safety limits that protect your endpoint from hotlinking, automated redistribution, and abusive traffic. These are protective ceilings, not overage billing meters, and normal website or application delivery should remain well below them.

Plan	Edge deliveries / month	Delivered data / month
Free	1 million	50GB
Starter	5 million	500GB
Pro	50 million	5TB
Business	250 million	50TB
Enterprise	Contracted	Contracted

Convertly canonicalizes transform parameters before cache lookup. Requests such as out-of-range widths that resolve to the same rendered output reuse one cache identity. New uncached variants also have workspace and per-client burst limits. The Image CDN analytics screen reports all three meters and sends alerts as safety thresholds approach.

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 endpoint namespace or file identifier, or malformed URL.
`403`	Signed URL signature failed verification.
`404`	Unknown CDN endpoint, or the file does not belong to that endpoint’s workspace.
`429`	An origin-request quota, new-variant burst limit, edge-delivery safety limit, or delivered-data safety limit was reached. Response carries `Cache-Control: no-store` and may include `Retry-After`.
`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.

Getting Started

Image CDN

Media Platform

SDKs & Integrations

Resources

Storage or origin sources

Choose your starting point

Use it from your framework

Transform Lab

URL transforms reference

Advanced URL features

Smart cropping & analysis

Responsive images

Client Hints

CDN performance

Social & OG images

Setup walkthrough

URL structure

Convertly HDAM

Delivery, purging, security

Pricing and quotas

Plan limits

How it works

Quick example (Next.js)

Pricing and quotas

Response codes

​Storage or origin sources

​Choose your starting point

Use it from your framework

Transform Lab

URL transforms reference

Advanced URL features

Smart cropping & analysis

Responsive images

Client Hints

CDN performance

Social & OG images

Setup walkthrough

URL structure

Convertly HDAM

Delivery, purging, security

Pricing and quotas

Plan limits

​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