> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convertly.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# CDN Introduction

> On-the-fly image transforms with smart cropping, format negotiation, signed URLs, and a one-prop SDK for every modern framework.

<div className="docs-page-banner">
  <img src="https://cdn.convertly.sh/cvly/o/convertly-site/docs/image-cdn/docs-cdn.png?v=docs-20260717&format=auto&q=auto:eco" alt="Image CDN" />
</div>

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.

<div className="convertly-callout">
  CDN URLs transform at request time from Convertly Storage file IDs or configured origin sources. No pre-generated variant files required.
</div>

<Warning>
  **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:

  1. **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.
  2. **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](/guides/image-cdn-setup).
</Warning>

## Storage or origin sources

Convertly uses [HDAM](/docs/image-cdn/hdam-storage) (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](/docs/image-cdn/url-structure#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

<CardGroup cols={3}>
  <Card title="Use it from your framework" icon="box" href="/docs/image-cdn/sdks">
    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.
  </Card>

  <Card title="Transform Lab" icon="flask" href="https://convertly.sh/app/image-cdn?tab=lab">
    Preview posters, clips, and image transforms in the dashboard and copy production-ready URLs.
  </Card>

  <Card title="URL transforms reference" icon="crop" href="/docs/image-cdn/transforms">
    Parameter index plus focused guides: Forma AI, watermarks, face and plate privacy, crop & fit, text, format, and video.
  </Card>

  <Card title="Advanced URL features" icon="key" href="/docs/image-cdn/presets-and-signing">
    Named transformation presets (`?preset=hero`) and HMAC-signed URLs for gated content.
  </Card>

  <Card title="Smart cropping & analysis" icon="brain" href="/docs/image-cdn/smart-cropping">
    Focal points, face-aware crop, palette extraction, and the analyze API.
  </Card>

  <Card title="Responsive images" icon="mobile-screen-button" href="/guides/responsive-images">
    srcset, `<picture>` art direction, and `<ConvertlyCdnProvider>`.
  </Card>

  <Card title="Client Hints" icon="tower-broadcast" href="/guides/client-hints">
    Browser-driven width and DPR without hard-coding `w` on every URL.
  </Card>

  <Card title="CDN performance" icon="gauge-high" href="/guides/cdn-performance">
    Cache strategy, origin deliverability, and purge by tag.
  </Card>

  <Card title="Social & OG images" icon="share-nodes" href="/guides/social-open-graph-images">
    Open Graph cards and platform previews from one hero file.
  </Card>

  <Card title="Setup walkthrough" icon="compass" href="/guides/image-cdn-setup">
    End-to-end CDN setup for your framework.
  </Card>

  <Card title="URL structure" icon="link" href="/docs/image-cdn/url-structure">
    Hostname, CDN endpoint namespace, UUID vs slug, folders, and origin paths.
  </Card>

  <Card title="Convertly HDAM" icon="folder-tree" href="/docs/image-cdn/hdam-storage">
    Hybrid digital asset management: library, origins, metadata, and stable CDN URLs.
  </Card>

  <Card title="Delivery, purging, security" icon="shield-halved" href="/docs/image-cdn/operations">
    Access policies, cache-tag purge, GCS/Azure origins, URL signing keys, and security model.
  </Card>

  <Card title="Pricing and quotas" icon="dollar-sign" href="#pricing-and-quotas">
    Per-plan monthly origin request allowances, what counts, what doesn't.
  </Card>

  <Card title="Plan limits" icon="gauge-high" href="/limits">
    Full quota reference for CDN, storage, streaming, and Forma AI.
  </Card>
</CardGroup>

## How it works

Three components:

1. **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.
2. **Source**: either a [Convertly Storage](/docs/files-and-storage) file id (UUID), a generated/editable [CDN slug](/docs/image-cdn/url-structure#cdn-slugs), or an origin-source slug + path.
3. **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:

```html theme={"system"}
<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](/docs/image-cdn/sdks).

## Quick example (Next.js)

```bash theme={"system"}
npm install @convertly-sh/image
```

```ts theme={"system"}
// 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",
});
```

```ts theme={"system"}
// 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](/docs/image-cdn/sdks#react), [Vue](/docs/image-cdn/sdks#vue), [Astro](/docs/image-cdn/sdks#astro), [Solid](/docs/image-cdn/sdks#solidjs), [Svelte](/docs/image-cdn/sdks#svelte), [plain HTML](/docs/image-cdn/sdks#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](https://convertly.sh/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](/limits#image-cdn)) |
| **Business**   | 5,000,000                        | Metered overage when enabled ([rates](/limits#image-cdn)) |
| **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](/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](/docs/image-cdn/operations).