File URLs

Public files have two CDN URLs. Pick based on whether the tag should keep showing the original bytes after someone hits Replace in the app. Private files use a tokened /f/ URL instead — they never 302 onto the public CDN, and ?w= is ignored. Non-image files use the same URLs; they are not resized.

The two shapes

Kind	Shape	Cache	After replace
url	https://cdn.pixeldrive.dev/{projectId}/{publicId}/v{n}	1 year	Until that version is pruned
stableUrl	https://cdn.pixeldrive.dev/f/{publicId}	302, 5 minutes	Follows the live version
?w=	https://cdn.pixeldrive.dev/f/{publicId}?w=640	302 to a WebP variant, 5 minutes	Pro + optimizable; first request generates and stores the variant

When to use which

url — look books, printed pages, anything that must not silently change. Safe to put on a long-lived CDN or <img> while that version is retained. If the project prunes the version, the object 404s after cache expires.
stableUrl — a headshot, a hero, a product shot you’ll swap without editing the site. Expect up to five minutes of the old image after a replace.
?w= — a next/image-style loader, or the listing’s src / srcset on Pro. Widths snap to 320 / 640 / 960 / 1280 / 1920. Files with optimizable: false (over Cloudflare’s 100 MB / 100 MP / 12,000 px caps) stay original. Video, PDF, Word, and markdown are never optimizable.

Non-image files

/f/{publicId} is still the file URL. The browser chooses how to open a PDF or video (inline). There is no Pixeldrive preview page. Use kind from the listing to decide between an <img> and a download / new-window link.

next/image loader

Pass stableUrl into a width-based loader. Extra query params such as q are accepted and ignored so we don’t mint a unique per quality. Skip the loader when optimizable is false.

loader

export function pixeldriveLoader({ src, width, quality }) {
  const url = new URL(src);
  url.searchParams.set("w", String(width));
  if (quality !== undefined) url.searchParams.set("q", String(quality));
  return url.toString();
}

<Image
  src={file.stableUrl}
  width={file.width}
  height={file.height}
  alt={file.name}
  loader={file.optimizable ? pixeldriveLoader : undefined}
  sizes="(max-width: 768px) 100vw, 50vw"
/>

Replace

Replace uploads a new object at v{n+1} (never reusing a number) and only repoints the live file after the object is verified. The listing’s url field then points at the new live version (listings cache for 60 seconds). stableUrl follows live within about five minutes.

Projects can keep the last 3, 5, or 10 versions per file. Off (the default) keeps only live. Extra versions are deleted from storage when the cap is hit. Promote in the dashboard moves live to an older retained object without copying bytes.

Delete

Delete removes every retained version object for that file (and any in-flight replace). Cached copies of an immutable URL may still serve until the 1-year TTL. Pre-feature leftover objects that were never tracked may still sit in storage until garbage-collected.

Public storage vs private projects

On a public project, turning the listing off hides the JSON. It does not remove the object from public storage or encrypt it. Anyone who already has a url or stableUrl can keep fetching it (immutable URLs may stay in cache for up to a year).

Private-project bytes stream through /f/{id}?exp=&sig=. A missing or expired token 404s like an unknown id. Do not put those URLs through next/image — the optimizer cannot present the token.

stable file link

https://cdn.pixeldrive.dev/f/{publicId}