Set up the image CDN on your site

The Convertly image CDN serves on-the-fly transformed images and video from a global edge cache. Use it for responsive images, poster frames, trimmed MP4/GIF clips, and smart cropping. This guide walks through getting it live on your site end-to-end: choose where the source image lives, use a CDN endpoint, register an origin or upload to storage, install @convertly-sh/image, wire it into your framework, and verify the result.

Every CDN URL needs a CDN endpoint plus either an origin source or a storage file UUID/slug. The SDK rewrites URLs; Convertly still fetches the source from your deployed site or storage.

Origin before loader. If your images live in a Next.js public/ folder (or any deployed static path), you must create an origin source in the dashboard before CDN URLs will work. Installing the SDK alone only changes URL strings — Convertly still needs a public HTTPS URL to fetch each source file from. Skip origin setup only if every image is already in Convertly Storage (file UUID).

You have two source options:

Source URLs / origin sources: images that already live behind a public HTTPS URL. This includes deployed framework app public/static assets, plus public S3/R2/GCS/Azure bucket endpoints, custom CDN domains, and web folders. Convertly fetches these deployed URLs on demand; it does not read local project folders.
Convertly Storage: images uploaded to Convertly when you want managed files and file IDs.

For most framework sites, start with an origin source. You do not need to upload repo images to Convertly Storage just to optimize them, but the deployed app must expose those images over public HTTPS. If you’d rather skim the reference, jump to Image CDN docs.

Use your CDN endpoint

A CDN endpoint is the durable delivery identity in CDN URLs. Its URL namespace is safe to embed in HTML and ship to the browser because it is not a credential.Go to Image CDN → Delivery and copy your default endpoint, or create a site-specific endpoint with a URL namespace such as marketing or site. URL signing keys are only needed when the endpoint requires signed URLs or a protected transform requires a signature.

Choose a source

The CDN can optimize either a source URL from a configured public HTTPS origin or a file in Convertly Storage. Pick the source that matches where your images already live.

Repo public/static images: deploy your site, then point an origin source at that public site URL. If public/hero.jpg, static/hero.jpg, or another framework-served asset resolves as https://example.com/hero.jpg, Convertly can fetch that deployed URL and optimize it as /cdn/v1/{endpointNamespace}/o/site/hero.jpg.
Remote assets: point an origin source at an existing public HTTPS bucket, CDN, or web folder, such as https://assets.example.com.
Convertly Storage: upload or import files to Convertly and use their generated CDN slugs or file IDs, such as /cdn/v1/{endpointNamespace}/{fileIdOrSlug}.

Attach an origin source

Required for repo / bucket / external-host images. Skip this step only if every image uses Convertly Storage UUIDs.If your assets already live on HTTPS or a public bucket, go to Image CDN → Sources and add a source.Public HTTPS — bucket, CDN, or deployed site with a public read URL:For framework repo assets, use the deployed app URL:

Name: Site public assets
Slug: site
Access: Public HTTPS
Base URL: https://example.com
Path prefix: leave blank

Private bucket — S3, R2, GCS, or Azure without public access:

Choose your provider and select Private bucket
Enter bucket name, region/account details, and read credentials
Convertly encrypts credentials at rest; they are never shown again after save

With a public site origin, these paths map directly:

Repo or origin file	Public source URL	Convertly CDN URL
`public/hero.jpg` or `static/hero.jpg`	`https://example.com/hero.jpg`	`/cdn/v1/{endpointNamespace}/o/site/hero.jpg?w=1200&format=auto`
`public/products/card.png` or framework equivalent	`https://example.com/products/card.png`	`/cdn/v1/{endpointNamespace}/o/site/products/card.png?w=800&format=auto`

For an asset bucket or existing CDN, use the same pattern with your asset host:

Slug: a short URL-safe name, e.g. products.
Base URL: the public HTTPS origin, e.g. https://assets.example.com.
Path prefix: optional folder prefix, e.g. catalog.

Then request images with /cdn/v1/{endpointNamespace}/o/{originSlug}/{path}:

<img src="https://cdn.convertly.sh/cdn/v1/assets-acme/o/products/hero.jpg?w=1200&format=auto" alt="Hero" />

Use Convertly Storage instead

If you want Convertly to host and manage the source image, upload it to Convertly Storage instead of creating an origin source.

Manual upload: open the Files tab in the dashboard and drag-and-drop. The file’s id (UUID) is shown in the details panel; the menu has a Copy file ID shortcut.
Programmatic upload: POST /api/uploads from your backend with the file bytes; the response includes the file id.
WordPress media: install the Convertly WordPress plugin so media library files sync automatically.

Storage-backed images use https://cdn.convertly.sh/{endpointNamespace}/{fileIdOrSlug}?w=1200&format=auto. New uploads get readable CDN slugs automatically and UUID URLs keep working. Origin-backed images use https://cdn.convertly.sh/{endpointNamespace}/o/{originSlug}/{path}?w=1200&format=auto.

Install the SDK

Do this after your CDN endpoint exists and your source is configured (origin source or Convertly Storage upload).

npm install @convertly-sh/image

The package ships React, Next.js, Vue, Astro, Solid, and Svelte adapters. Pick the one that matches your stack.

Wire it into your framework

Choose your path:

Next.js
React
Vue
Astro
Plain HTML

Set it once globally so every existing <Image> in your app routes through Convertly with no per-component changes.

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;

Add NEXT_PUBLIC_CONVERTLY_CDN_NAMESPACE=assets-acme to your .env.local. Create site as an origin source for your deployed app’s public HTTPS URL. In production, <Image src="/hero.jpg" width={1200} /> is rewritten to a Convertly URL for the deployed public asset: /cdn/v1/{endpointNamespace}/o/site/hero.jpg?w=1200.... During next dev, localPassthrough renders /hero.jpg directly because the public CDN cannot fetch localhost; use a preview deployment or HTTPS tunnel when you want to test the real optimized CDN URL before launch.

import { ConvertlyCdnProvider, ConvertlyImage } from "@convertly-sh/image/react";

export default function App() {
  return (
    <ConvertlyCdnProvider namespace={process.env.NEXT_PUBLIC_CONVERTLY_CDN_NAMESPACE!}>
      <ConvertlyImage
        src="7c3f2a91-8b64-4d5e-a2f7-91c06b48de35"
        width={1200}
        height={800}
        alt="Hero image"
        sizes="(min-width: 768px) 50vw, 100vw"
      />
    </ConvertlyCdnProvider>
  );
}

<script setup>
import { provideConvertlyCdn, ConvertlyImage } from "@convertly-sh/image/vue";

provideConvertlyCdn({
  namespace: import.meta.env.PUBLIC_CONVERTLY_CDN_NAMESPACE,
});
</script>

<template>
  <ConvertlyImage
    src="7c3f2a91-8b64-4d5e-a2f7-91c06b48de35"
    :width="1200"
    sizes="(min-width: 768px) 50vw, 100vw"
    alt="Hero image"
  />
</template>

components/CdnImage.astro

---
import { createConvertlyCdn } from "@convertly-sh/image";

const cdn = createConvertlyCdn({
  namespace: import.meta.env.PUBLIC_CONVERTLY_CDN_NAMESPACE,
});

const { fileId, width, sizes, alt } = Astro.props;
const src = cdn.url(fileId, { w: width });
const srcset = cdn.srcset(fileId, { widths: [400, 800, 1200, 1600] });
---

<img {src} {srcset} {sizes} {alt} loading="lazy" decoding="async" />

Origin-source image:

<img
  src="https://cdn.convertly.sh/cdn/v1/assets-acme/o/site/hero.jpg?w=1200&format=auto"
  srcset="
    https://cdn.convertly.sh/cdn/v1/assets-acme/o/site/hero.jpg?w=600&format=auto 600w,
    https://cdn.convertly.sh/cdn/v1/assets-acme/o/site/hero.jpg?w=1200&format=auto 1200w,
    https://cdn.convertly.sh/cdn/v1/assets-acme/o/site/hero.jpg?w=1800&format=auto 1800w"
  sizes="(min-width: 768px) 50vw, 100vw"
  alt="..."
  loading="lazy"
/>

Convertly Storage image:

<img
  src="https://cdn.convertly.sh/cdn/v1/assets-acme/{fileIdOrSlug}?w=1200&format=auto"
  srcset="
    https://cdn.convertly.sh/cdn/v1/assets-acme/{fileIdOrSlug}?w=600&format=auto 600w,
    https://cdn.convertly.sh/cdn/v1/assets-acme/{fileIdOrSlug}?w=1200&format=auto 1200w,
    https://cdn.convertly.sh/cdn/v1/assets-acme/{fileIdOrSlug}?w=1800&format=auto 1800w"
  sizes="(min-width: 768px) 50vw, 100vw"
  alt="..."
  loading="lazy"
/>

All adapters default to format=auto (AVIF/WebP/JPEG negotiation), gravity=auto (smart cropping), q=auto (content-aware quality), and loading="lazy". You can override any of them per call.

Verify it's working

Load a deployed page that renders one of your CDN-backed images. In the browser DevTools Network tab, look for a request to convertly.sh/cdn/v1/.... If you are using localPassthrough in next dev, localhost will show the original /hero.jpg path; that is expected and is not the optimized CDN path because Convertly cannot fetch local project files. The deployed or tunneled page response should:

Be 200 OK
Have Content-Type: image/webp (or image/avif if your browser supports it)
Have Cache-Control: public, max-age=31536000, immutable, stale-while-revalidate=86400
Have an X-Convertly-CDN-Used-Month header showing your delivery counter (first requests that reach Convertly for that URL variant)

Refresh the page. The image should now come from disk cache or memory cache in DevTools — no second network request.

(Optional) Add design-system presets

If you find yourself writing the same transform many times — say, every hero is 1920×720 — save it as a named preset and reference it by name:

curl -X POST "https://convertly.sh/api/cdn-presets" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hero",
    "params": { "w": 1920, "h": 720, "fit": "cover", "gravity": "auto", "q": "auto" }
  }'

Now any URL with ?preset=hero (or path /p/hero) gets those defaults. Override individual params on a per-URL basis when you need to — e.g. ?preset=hero&w=800.You can also manage presets visually in Settings → Image CDN → Transform presets.

What happens on the first request

When a browser fetches a CDN URL for the first time:

The request hits Convertly’s edge cache. On a miss, Convertly loads the source (storage file, origin URL, or private bucket object).
Convertly applies the requested transforms (resize, format, smart crop, quality).
The result is cached with long-lived immutable headers. Popular variants are retained so repeat requests — including from other regions — often skip re-encoding.

A typical 7 MB source PNG becomes a ~200 KB WebP or AVIF. The first request for that URL may take around a second to encode; repeats are typically ~20 ms from edge cache.

Video clips and poster frames

Stored video files use the same CDN endpoint and SDK. Add poster or transcode params to the URL; no separate video package is required:

https://cdn.convertly.sh/{endpointNamespace}/{videoId}?t=3.5&w=800&format=webp
https://cdn.convertly.sh/{endpointNamespace}/{videoId}?format=mp4&w=1280&so=0&du=30

See Video transforms for every video parameter.

Troubleshooting

Symptom	Likely cause	Fix
CDN URL returns 404 / 502	No origin source, wrong slug, or file not public on origin	Add Sources entry; verify `https://your-site.com/hero.jpg` returns 200
Next.js still shows `/hero.jpg` in dev	`localPassthrough` is working as designed	Expected in `next dev`; test on preview deploy or disable passthrough with a tunnel
Installed SDK, nothing changed in production	Loader not wired, or origin slug mismatch	Check `next.config.ts` loader + `origin: "site"` matches dashboard slug
UUID images work, `/public` paths don’t	Storage works; origin missing	Create origin for deployed site URL
Random external URL fails	Host not registered	Add an origin source for that HTTPS host — no open fetch

Next steps

Use your own hostname

Serve from cdn.yourdomain.com instead of cdn.convertly.sh. One CNAME — we handle SSL.

Every URL parameter

Width, height, quality, fit, gravity, format, text overlay, save-data quality.

Presets and signed URLs

Named transformation bundles and HMAC-signed URLs for gated content.

Delivery, purging, security

Manage CDN endpoints and URL signing keys, invalidate cached URLs, replace files.

Framework SDK reference

Full prop tables for React, Next.js, Vue, Astro, Solid, and Svelte.

Build Flows

Image CDN

AI Agents

What happens on the first request

Video clips and poster frames

Troubleshooting

Next steps

Use your own hostname

Every URL parameter

Presets and signed URLs

Delivery, purging, security

Framework SDK reference

​What happens on the first request

​Video clips and poster frames

​Troubleshooting

​Next steps

Use your own hostname

Every URL parameter

Presets and signed URLs

Delivery, purging, security

Framework SDK reference

What happens on the first request

Video clips and poster frames

Troubleshooting

Next steps