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 — not just static file conversion. This guide walks through getting it live on your site end-to-end: choose where the source image lives, create a delivery key, 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 delivery key plus either an origin source or a storage file UUID. 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.

Create a delivery key

A delivery key is a publishable credential that identifies your workspace. It’s safe to embed in HTML and ship to the browser — it cannot upload, delete, or convert, only resolve URLs.Go to Settings → Image CDN → Delivery keys, click Create, and copy the token (format cvly_pub_…). You’ll only see the full token once.Optionally set a short alias (marketing, site) when creating the key so URLs look like https://cdn.convertly.sh/marketing/{fileId}?w=1200 instead of the long token. Check availability with GET /api/delivery-keys/alias?alias=marketing.

Don’t confuse delivery keys (cvly_pub_…) with regular API keys (cvly_… without _pub_). API keys can convert / upload / delete and must stay server-side.

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/{deliveryKey}/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 file IDs, such as /cdn/v1/{deliveryKey}/{fileId}.

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 in object storage, 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/{deliveryKey}/o/site/hero.jpg?w=1200&format=auto`
`public/products/card.png` or framework equivalent	`https://example.com/products/card.png`	`/cdn/v1/{deliveryKey}/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/{deliveryKey}/o/{originSlug}/{path}:

<img src="https://cdn.convertly.sh/cdn/v1/cvly_pub_.../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/{deliveryKeyOrAlias}/{fileId}?w=1200&format=auto. Set an optional CDN slug on a file when you want a readable segment instead of the UUID. Origin-backed images use https://cdn.convertly.sh/{deliveryKey}/o/{originSlug}/{path}?w=1200&format=auto.

Install the SDK

Do this after your delivery key 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({
  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;

Add NEXT_PUBLIC_CONVERTLY_DELIVERY_KEY=cvly_pub_... 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/{deliveryKey}/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 deliveryKey={process.env.NEXT_PUBLIC_CONVERTLY_DELIVERY_KEY!}>
      <ConvertlyImage
        src="11111111-1111-1111-1111-111111111111"
        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({
  deliveryKey: import.meta.env.PUBLIC_CONVERTLY_DELIVERY_KEY,
});
</script>

<template>
  <ConvertlyImage
    src="11111111-1111-1111-1111-111111111111"
    :width="1200"
    sizes="(min-width: 768px) 50vw, 100vw"
    alt="Hero image"
  />
</template>

components/CdnImage.astro

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

const cdn = createConvertlyCdn({
  deliveryKey: import.meta.env.PUBLIC_CONVERTLY_DELIVERY_KEY,
});

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/cvly_pub_.../o/site/hero.jpg?w=1200&format=auto"
  srcset="
    https://cdn.convertly.sh/cdn/v1/cvly_pub_.../o/site/hero.jpg?w=600&format=auto 600w,
    https://cdn.convertly.sh/cdn/v1/cvly_pub_.../o/site/hero.jpg?w=1200&format=auto 1200w,
    https://cdn.convertly.sh/cdn/v1/cvly_pub_.../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/cvly_pub_.../{fileId}?w=1200&format=auto"
  srcset="
    https://cdn.convertly.sh/cdn/v1/cvly_pub_.../{fileId}?w=600&format=auto 600w,
    https://cdn.convertly.sh/cdn/v1/cvly_pub_.../{fileId}?w=1200&format=auto 1200w,
    https://cdn.convertly.sh/cdn/v1/cvly_pub_.../{fileId}?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 served from cache in ~20 ms on subsequent hits.

Video clips and poster frames

Stored video files use the same delivery key and SDK. Add poster or transcode params to the URL — no separate video package:

https://cdn.convertly.sh/{deliveryKey}/{videoId}?t=3.5&w=800&format=webp
https://cdn.convertly.sh/{deliveryKey}/{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 keys, purging, security

Manage and rotate delivery keys, invalidate cached URLs, replace files.

Framework SDK reference

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

​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 keys, purging, security

Framework SDK reference

What happens on the first request

Video clips and poster frames

Troubleshooting

Next steps