{resolutions .filter((r) => r.url) .map((r) => ( // biome-ignore lint/performance/noImgElement: framework-agnostic example ))}

; ``` Treating it as a failure means the first person to add a slot to the codebase breaks the page for everyone until someone remembers to bind it. ## The browser client cannot hold a key [Section titled “The browser client cannot hold a key”](#the-browser-client-cannot-hold-a-key) `@nitida/sdk/web` exports an `NitidaClient` whose **type rejects** `apiKey` and `signingKey`. That is deliberate: the browser talks to *your* route, and your route holds the key. If you find yourself wanting to pass a key here, the architecture went wrong one step earlier. # A gallery that is fast on a phone and sharp on a desktop > One photo, two srcSets. Which widths to ask for on mobile vs desktop, what each one actually weighs, and the two things that silently give you the wrong size. Every number on this page was measured against production. A phone and a 27-inch monitor need very different bytes from the same photo. This page is the recipe: **upload once, serve two ladders**, with the weights measured so the speed/quality trade is a number and not a feeling. *** ## 1 · The imports, which are not all in one package [Section titled “1 · The imports, which are not all in one package”](#1--the-imports-which-are-not-all-in-one-package) ```ts import { NitidaClient, getTransformUrl, getTransformSrcSet, setTenantId, } from "@nitida/sdk"; import { setCdnBase, type TransformWidth } from "@nitida/asset-client"; ``` ⚠️ **`setCdnBase` is not re-exported by `@nitida/sdk`**, while `setTenantId` is. Importing both from the SDK fails at module load. *** ## 2 · Upload: ask for the ladder, and upload the biggest master you have [Section titled “2 · Upload: ask for the ladder, and upload the biggest master you have”](#2--upload-ask-for-the-ladder-and-upload-the-biggest-master-you-have) The default is `["original"]` and nothing else. ```ts await nt.upload(file, { fileName: "villa-sunset.jpg", presets: ["original", "thumb", "sm", "md", "lg", "xl"], }); ``` **The source is the ceiling — there is no upscale.** Measured: a 2400 px master asked for `width=2560` returns **2400 px**. Put widths in your `srcSet` that your masters can actually sustain, or the browser picks a candidate that does not exist at that size. *** ## 3 · What each width weighs [Section titled “3 · What each width weighs”](#3--what-each-width-weighs) Measured on a 2400×1600 master, WebP at `quality=75`: | width | 400 | 600 | 800 | 960 | **1080** | 1600 | **1920** | | ------ | --- | --- | --- | --- | -------- | ---- | -------- | | **KB** | 21 | 32 | 56 | 74 | **86** | 123 | **175** | That table *is* the trade-off. A phone served at `1080` downloads **86 KB**; served at `1920` it downloads **175 KB** — double the weight for pixels the screen cannot resolve. | surface | CSS width | DPR | ask for | | ---------------------- | -------------- | --- | --------------------------------------------------- | | Mobile · 2-col grid | \~190 px | 2–3 | `400`, `480` | | Mobile · full screen | \~400 px | 2–3 | `800`, `960`, `1080` | | Desktop · grid | \~300–400 px | 1–2 | `400`, `600`, `800` | | Desktop · lightbox | \~1200–1600 px | 1–2 | `1600`, `1920` | | Full-bleed retina hero | — | 2 | `2560` / `3840` — **only if the master reaches it** | *** ## 4 · One photo, both galleries [Section titled “4 · One photo, both galleries”](#4--one-photo-both-galleries) ```tsx // No `quality` here — auto-quality probes the MASTER, so the image is // compressed exactly once. Pinning a number turns on the shortcut that reads an // already-compressed variant instead. See the double-pass warning below. ``` **`sizes` is what makes the phone pick 800 and the desktop pick 1600 from the same tag.** Leave it out and the browser assumes `100vw` — it will fetch the large candidate for everyone, and the whole ladder buys you nothing. ### Quality and format [Section titled “Quality and format”](#quality-and-format) * **Omit `quality` unless you have a hard byte budget.** `75` for grids and `80` for the large view are sensible *numbers*, but pinning either one is what triggers the second compression pass on a laddered asset — **read the warning below first if your assets have the preset ladder.** * **`format: "webp"`.** The DSL accepts `avif`, but this platform standardises on WebP. * **Grid cells:** `{ fit: "cover", gravity: "auto" }` crops to fill and frames itself — verified to return an exact 400×400. **Lightbox:** `fit: "inside"`, which never crops. Pinning `quality` on a laddered asset compresses the image twice `/t/` short-circuits to the smallest **stored variant** that covers the requested size — and that variant is already a WebP that has been through one lossy pass. The shortcut only fires when the request carries an **explicit numeric `quality`**, so `quality: 75` is precisely what turns it on. Measured on five photographs at `width=800` ([the benchmark](/guides/transform-benchmark/)): the laddered asset answered from `md` (1280 px WebP) every time, came back **7–9 % smaller** than the same photo served from its master — and **worse on both PSNR and SSIM, 5 times out of 5** (up to −3.01 dB / −0.0200 SSIM). Smaller *and* worse is generation loss, not a saving. * **Want the master’s quality?** Drop `quality` and let auto-quality run: it has to probe the full-resolution master, so it cannot take the shortcut. Measured cost: between −2.6 % and +4.7 % bytes, with SSIM up on all five. * **Raising `quality` does not undo it.** The doubly-compressed output at `quality: 80` is still worse than the single-pass output at `quality: 60` — and 31 % heavier. * **Worst at 640, 1280 and 1920**, the widths that match `sm`/`md`/`lg` exactly: no downscale in between to hide the first pass. At 640 and 1920 the laddered result is *heavier* as well. * **Assets uploaded with `["original"]` only are unaffected** — every transform comes off the master. *** ## 5 · Widths are a fixed ladder [Section titled “5 · Widths are a fixed ladder”](#5--widths-are-a-fixed-ladder) 21 of them: 96 · 128 · 160 · 180 · 240 · 256 · 320 · 400 · 480 · 600 · 640 · 800 · 960 · 1080 · 1200 · 1280 · 1440 · 1600 · 1920 · 2560 · 3840. Anything off it is **HTTP 400 at the edge**, deliberately — verified with `width=777`. Import the `TransformWidth` type and an off-ladder number becomes a compile error instead of a production 400. *** ## 6 · The first request of each width is cold [Section titled “6 · The first request of each width is cold”](#6--the-first-request-of-each-width-is-cold) A transform is generated on first request and then cached at the edge immutably. If the gallery must be fast for its *first* visitor too, either ask for those sizes as stored presets at ingest, or warm them with a sweep of requests after upload. *** ## What running it caught [Section titled “What running it caught”](#what-running-it-caught) The first version of this recipe was written by reading the source. Executing it found two errors in it: 1. **`setCdnBase` imported from the wrong package** — it failed on the first line. Anyone following the instructions would have bounced immediately. 2. **`width=2560` returns 2400 px** when the master is 2400 px wide. The draft recommended 2560 for desktop lightboxes without saying it depends on the source. Neither is visible from reading the code. That is why the script exists, and why it runs against production rather than a fixture. A third thing was found later, the same way: the `quality: 75` / `80` advice on this page was written without knowing that pinning a numeric `quality` is what enables the stored-variant shortcut — so the recommendation was quietly asking for a second lossy pass on exactly the assets we tell everyone to upload. The measurement, on all five documentation photographs and every gallery width, is [the transform benchmark](/guides/transform-benchmark/). # Upload and render > The whole loop — bytes in, responsive URLs out — with the two decisions that cannot be undone later. ## Upload [Section titled “Upload”](#upload) upload-an-image.ts ```ts /** * Upload one image, end to end. * * This file is REAL: `bun run check` type-checks it in CI against the same * workspace version of the SDK this site documents. If a signature changes, * the build fails instead of the website quietly lying. */ import { NitidaClient } from "@nitida/sdk"; // The `amk_rt_*` runtime key is a WRITE key to a paid platform. It lives on the // server, in a secret — never in a client bundle, never in `NEXT_PUBLIC_*`. const nt = new NitidaClient({ endpoint: process.env.NITIDA_ENDPOINT ?? "https://assets.example.com", apiKey: process.env.NITIDA_RUNTIME_KEY, tenantCode: "demo", // Required: variant URLs are tenant-prefixed in base36 (`/a/v/-lg.webp`). tenantId: Number(process.env.NITIDA_TENANT_ID ?? 1), }); export async function uploadImage(file: File) { const result = await nt.upload(file, { // ⚠️ "original" is non-negotiable at FIRST ingest. A variant you do not ask // for here can never be recovered later: the cleanup job reaps `raw/`, and // `regenerate()` then has nothing left to read from. presets: ["original", "thumb", "md", "lg"], // Browser-only; in Node/Bun it no-ops with a warning and uploads raw bytes. compress: true, }); // `upload` returns ids and the canonical URL — not a full asset. Build the // other URLs from the sha. return { assetId: result.assetId, canonical: result.cdnUrl, display: nt.urlFor({ sha: result.sha256 }, "lg"), }; } ``` `upload()` does the whole loop in one call: compress → sha256 → presign → PUT straight to storage → register → poll until ready. It returns ids and the canonical URL, **not** a full asset — build the other URLs from the sha. ## Render [Section titled “Render”](#render) image-urls.ts ```ts /** * Build image URLs without uploading anything. * * `@nitida/asset-client` has no network and no key — it is pure URL * construction. Import it directly when all you do is render. */ import { getTransformSrcSet, getTransformUrl, setCdnBase, setTenantId, type TransformWidth, } from "@nitida/asset-client"; // The builders read PROCESS-GLOBAL config. Pin it once where your helpers live, // so every module that imports a builder is configured. setCdnBase(process.env.NEXT_PUBLIC_NITIDA_CDN ?? "https://8ok.uk"); setTenantId(Number(process.env.NEXT_PUBLIC_NITIDA_TENANT_ID ?? 1)); // Lock the output format to your project's policy rather than using `auto`. const FORMAT = "webp" as const; /** * ⚠️ The width MUST be on the unsigned ladder. Any other width is an HTTP 400 * at the edge — that is a deliberate DoS guard, not a bug. Importing * `TransformWidth` turns an off-ladder width into a COMPILE error, which is * where you want to find out. */ export const imageUrl = (sha: string, width: TransformWidth) => getTransformUrl({ sha }, { format: FORMAT, width }); export const imageSrcSet = (sha: string, widths: readonly TransformWidth[]) => getTransformSrcSet({ sha }, widths, { format: FORMAT }); /** Fixed-aspect cards and thumbnails want a cover crop. */ export const thumbUrl = (sha: string, width: TransformWidth) => getTransformUrl( { sha }, { format: FORMAT, width, fit: "cover", gravity: "auto" }, ); ``` ## The two decisions you cannot undo [Section titled “The two decisions you cannot undo”](#the-two-decisions-you-cannot-undo) ### 1. The presets you ask for at the FIRST ingest [Section titled “1. The presets you ask for at the FIRST ingest”](#1-the-presets-you-ask-for-at-the-first-ingest) Ask for what you need here. A variant you skip is **not** lost — cleanup keeps `raw/` for as long as the asset row exists (verified on a 2-month-old thumb-only asset), so `regenerate({ presets })` can add it later. What you get meanwhile is an incoherence: `getAssetUrl(asset,"md")` **404**s while `/t/…width=1280/.webp` serves the same image on demand. The real trap is upstream of that: a backup run once archived **97 files “successfully”** after copying a delivery-oriented `presets: ["thumb"]` from a migration example, and the operator concluded the bytes were gone without checking `raw`. **A preset list copied from an example is a decision you did not make**, and *“N uploaded, 0 failed”* measures the upload, not the outcome. If the bytes matter, `"original"` is not optional. ### 2. The filename you upload under [Section titled “2. The filename you upload under”](#2-the-filename-you-upload-under) The stored extension for `original` comes from the **uploaded filename**, not from the MIME type. For JPEG those disagree: `image/jpeg` implies `jpeg` while every camera writes `.jpg`. Measured: `…-o.jpeg` **404**, `…-o.jpg` **200**. If you plan to fetch the original back by URL, `HEAD` it once and store what answered rather than deriving it twice in two places. ## What you get back [Section titled “What you get back”](#what-you-get-back) | | | | --------- | ------------------------------------------------------------- | | `assetId` | the row id — poll this, bind slots to it | | `sha256` | content address — dedup key, and what every URL builder takes | | `cdnUrl` | the canonical URL for the asset | Two uploads of the same bytes return the **same** asset. That is a feature, and it is also why a retried upload can hide a bug in the non-deduped path — see [For agents](/start/for-agents/). # The rest of the surface > Signed URLs, upscaling, usage metering, OG cards, compositions — the features that exist but rarely come up first. The pages before this cover what almost every integration needs. This one covers what exists beyond that, so nothing is a surprise you discover from a stack trace. ## Signed transform URLs — the only way to a custom width [Section titled “Signed transform URLs — the only way to a custom width”](#signed-transform-urls--the-only-way-to-a-custom-width) Unsigned transforms accept **only** widths on the fixed ladder. Anything else is `400` at the edge, and that is a denial-of-service guard, not an oversight: an open resize endpoint lets anyone mint unlimited unique renders on your bill. A **signed** URL earns the bypass, because you vouched for it: ```ts import { getSignedTransformUrl } from "@nitida/asset-client"; // width is a plain number here — any number. // The signing key is the THIRD argument and it is required. const url = await getSignedTransformUrl( { sha }, { width: 733, format: "webp" }, process.env.NITIDA_SIGNING_KEY!, ); // or, with the client holding the key: // const nt = new NitidaClient({ …, signingKey: process.env.NITIDA_SIGNING_KEY }); // await nt.transform(asset, { width: 733 }, { sign: true }); ``` The types enforce the rule so you cannot get it wrong by accident: `TransformOptions.width` is the ladder union, while `SignedTransformOptions.width` is `number` — and only the signing helpers accept the latter. The signing key is server-side, like the API key Sign in a route handler or at build time. A signing key in the browser is an open resize endpoint with extra steps. ### Getting the key [Section titled “Getting the key”](#getting-the-key) The signing key is **not** part of the credential set you are issued, and none of your own keys can read it — a tenant admin key gets `403 SYSTEM_KEY_REQUIRED`. It is minted by: ```plaintext POST /admin/projects/:code/rotate-signing-key ``` which requires a **system-scope** credential held by the platform operator, and returns the key **once**. So: ask for it, then keep it in your secret manager next to the API key. Rotating invalidates every URL signed with the previous key immediately, so coordinate it with whatever pre-signs — a build-time cache, a BFF route. If you already hold a key and a signed URL still answers `401 invalid_signature`, the key is wrong or rotated, not the URL shape: an off-ladder width that answers `400` unsigned and `401` signed proves the signature path is reached and the bypass works. ## Upscaling [Section titled “Upscaling”](#upscaling) An AI upscale of an existing asset, through a configured provider. ```plaintext POST /assets/:id/upscale start (or return an existing one) GET /assets/:id/upscales everything upscaled for this sha POST /assets/upscale/:id/poll manual finalize, when a webhook was missed ``` **Idempotent on `(tenant, sha, preset, provider)`** — asking twice does not pay twice. It is asynchronous and provider-backed, so treat it like the video path: kick it off, poll or wait for the webhook, and have a fallback for the missed one. That is what `/poll` is for. This is metered separately from storage — the `upscale` op is its own scope on the runtime key. ## Usage and metering [Section titled “Usage and metering”](#usage-and-metering) ```ts await nt.usage.snapshot(); // current period await nt.usage.timeseries(30); // daily points await nt.usage.keys(); // per-key breakdown ``` The Cloudinary-style consumption view: what you have stored, transformed and served. `keys()` is the one worth wiring early — when usage jumps, “which key did this” is the first question, and per-key attribution is the only cheap answer. ## OG cards — a deliberate bypass [Section titled “OG cards — a deliberate bypass”](#og-cards--a-deliberate-bypass) Social preview images have a different shape from user uploads: they are **pre-rendered at deploy time**, already the exact size, and they must not go through a resize ladder that would only re-encode them. ```plaintext POST /og-cards/upload service-to-service, Bearer OG_UPLOAD_API_KEY ``` Bytes go base64 in a JSON envelope, because the callers are build-time jobs (Vercel, CI) where a simple wire format beats multipart. **Use this only for that case.** If a human uploaded it, it belongs on the normal path. ## Video compositions [Section titled “Video compositions”](#video-compositions) Two processors that build a *new* video from pieces you already uploaded: * **Slideshow** — stills into a clip. * **Marketing composition** — stitch segments into one MP4. Both follow the same contract as any long video job: a `processing` row comes back immediately, and it flips to `ready` or `failed` when the job finishes. Poll with `waitReady` and budget minutes, not seconds — a multi-segment kit is a 10-minute timeout, not a 5-minute one. ## External systems in the path [Section titled “External systems in the path”](#external-systems-in-the-path) Worth knowing, because they explain latency and failure modes: | system | role | what happens if it is down | | -------------------- | --------------------- | ------------------------------------------- | | Object storage | the bytes | uploads fail — this is the hard dependency | | CDN | delivery | serving degrades; uploads unaffected | | The video job runner | video transcode, HLS | video stays `processing`; images unaffected | | Upscale provider | AI upscaling | that upscale fails; nothing else does | | **Your webhooks** | palette / asset-ready | **nothing.** Fire-and-forget by design | That last row is a deliberate choice: an upload does **not** fail because a downstream consumer was unavailable. You lose a notification, not an asset — reconcile with a retry or a backfill. The alternative trades a recoverable gap for an unrecoverable one. # Compression in the browser > What the compressor does, what it costs your bundle, and the one failure that used to make photos 24× heavier. Compression runs in the browser, before a byte crosses the network. A raw phone photo typically shrinks 5–10×, which is bandwidth the user does not spend and storage you do not buy. It runs in a worker on `OffscreenCanvas`, so the main thread never blocks — scrolling stays smooth while a dozen photos encode. ## What it costs your bundle [Section titled “What it costs your bundle”](#what-it-costs-your-bundle) Measured with `bun build --minify --splitting`, which is what a real bundler does. (Without `--splitting` the number is 1.38 MB and it is a lie — everything lands in one chunk whether or not you ever reach it.) | | gzipped | who pays | | ------------------------- | ------------- | ------------------------------------------------------------------------------------------------- | | the compressor, **eager** | **4,363 B** | everyone | | `compressorjs`, lazy | 4,994 B | Safari < 16.4, or a failed decode | | `heic2any`, lazy | **341,352 B** | each HEIC — **and only if the engine cannot decode it natively** | | `hash-wasm` | 7,223 B | everyone. Tree-shakes cleanly; there is no alternative, since WebCrypto has no incremental digest | That last column is the whole design. Only 4 KB is unconditional; the expensive pieces load when something actually needs them. ## HEIC: native first [Section titled “HEIC: native first”](#heic-native-first) Engines that can decode HEIC do it in about **136 ms**. The WASM fallback takes roughly **1,700 ms** — and costs 341 KB to fetch first. So the native path is tried first, and the fallback only runs where it must. That is a 12× difference on the exact file type phones produce by default, so it is worth confirming on a real device rather than in a simulator. ## WebKit cannot encode WebP at all [Section titled “WebKit cannot encode WebP at all”](#webkit-cannot-encode-webp-at-all) `canvas.convertToBlob({ type: "image/webp" })` is allowed to **ignore you**, and WebKit always does. MDN’s compatibility data records `canvas.toBlob(type="image/webp")` as **unsupported in Safari** — desktop macOS included — and every browser on iOS is WebKit underneath, so Chrome, Firefox and Edge on an iPhone inherit it. Nothing throws; you simply get another format. Two different bad outcomes came out of that, and only one of them is fixed by the engine being honest: **Left alone, it returns PNG.** Measured on an 11.9 MP photo: **PNG 21.8 MB vs JPEG 3.8 MB** — 5.7×, and 24× against a well-tuned WebP. A photo uploaded as a lossless screenshot format. **Handled, it returns JPEG.** The compressor plans a JPEG attempt behind the WebP one, so WebKit lands on the right fallback. Measured on iOS 27 / Chrome 151, a 9.1 MP photo: `2.05 MB → 743.7 kB`, labelled `jpeg`. Label by the bytes you got, never by the format you asked for Read the blob’s actual `type` after encoding and name the file from that. The fallback is correct behaviour; naming the file for the *request* is the bug — and it was found in five separate places once anyone looked, because every one of them assumed the request was the answer. ### Your visitors still get WebP [Section titled “Your visitors still get WebP”](#your-visitors-still-get-webp) This changes what crosses the wire on the way **in**, not what you serve. Every variant is re-encoded server-side: ```plaintext WebKit browser ──JPEG──▶ server ─────────▶ thumb · sm · md · lg · xl (WebP) Chromium/Firefox ──WebP──▶ server ─────────▶ thumb · sm · md · lg · xl (WebP) ``` So the cost of the fallback is a slightly larger upload and an archived `original` in JPEG — not a worse experience for anyone visiting the site. ## Rotation: a photo held upright stays upright [Section titled “Rotation: a photo held upright stays upright”](#rotation-a-photo-held-upright-stays-upright) A phone taking a portrait photo usually does **not** store portrait pixels. It writes the sensor buffer as-is — landscape — and tags it with an EXIF `Orientation` of 5–8 meaning “rotate this before showing it”. Two numbers therefore describe every such file, and they are transposes of each other: \| | 4032×3024 | the **stored** buffer | | | 3024×4032 | what it **displays** as | The compressor resolves that before it resizes, and the upload comes out portrait, at the right proportions. You do not have to strip, pre-rotate, or otherwise prepare anything: hand it the file the camera produced. This was broken between 2026-06-02 and 2026-08-28 Versions **0.6.0 – 0.6.2** computed the resize target from the *stored* pair and then asked the decoder for exactly those dimensions, while decoding with `imageOrientation: 'from-image'` — which applies the rotation first. Portrait content was forced into a landscape box: a measured **1.78× horizontal stretch** on every affected photo. It required all three of: a header the engine can parse (JPEG/PNG/WebP/GIF/BMP — **HEIC was never affected**), an EXIF orientation of **5–8**, and a long side **above** the resize box. That combination is why it looked random. **Fixed in 0.6.3.** Upgrade if you are below it. The damage happens in the browser before upload, so already-stored photos cannot be repaired server-side — they have to be uploaded again from the original. ### Reading dimensions yourself [Section titled “Reading dimensions yourself”](#reading-dimensions-yourself) If you parse image headers in your own code, the same trap is waiting. Header fields — the JPEG `SOF` marker, PNG `IHDR` — carry the **stored** pair and know nothing about EXIF. `readImageDimensions()` returns exactly that, plus the `orientation` tag, so the two spaces stay distinguishable: ```ts import { readImageDimensions } from "@nitida/asset-compressor-web"; const dims = readImageDimensions(headerBytes); // → { width: 4032, height: 3024, orientation: 6 } ``` Use the raw pair for anything orientation-invariant (area, a megapixel budget). For anything geometric — a resize target, an aspect ratio, a layout box — you want the displayed pair: transpose when `orientation` is 5, 6, 7 or 8. ⚠️ And if you resize with `createImageBitmap`, **pass ONE axis, not both.** Giving `resizeWidth` *and* `resizeHeight` resizes to exactly that box without preserving the ratio, so any disagreement between your numbers and the decoded bitmap becomes a stretch. With one axis the spec derives the other, and the proportions survive by construction — which is the second half of the 0.6.3 fix, and the reason the geometry no longer depends on reading EXIF correctly. ## When it declines [Section titled “When it declines”](#when-it-declines) Non-image inputs — video, PDF — skip compression entirely and upload raw. An image the engine cannot decode also uploads raw rather than failing the upload: the original arriving intact beats a clever error. # Uploads that survive a reload > When `aq.upload()` is not enough, and the two packages that pick up where it stops — resume in the browser, and an upload that keeps going while the app is backgrounded. `aq.upload()` sends a file in a single PUT. That is what almost every consumer needs, and you should not reach past it without a reason. The reason is **resume**. A single PUT is atomic in the worst way: interrupt it at 95% — a reload, a tunnel, an iOS app backgrounded by the user switching to Messages — and you start from zero. On a 2 GB video over a phone connection, that is not an inconvenience; it is a feature that does not work. Two packages pick up there. Both are optional: install one only if the sentence above describes your product. | | package | resumes across | | ------------------- | ----------------------------- | --------------------------------------------- | | Browser | `@nitida/asset-uploader-web` | a page reload, a crashed tab, a closed laptop | | Expo / React Native | `@nitida/asset-uploader-expo` | the app being backgrounded or killed | ## Browser [Section titled “Browser”](#browser) ```bash bun add @nitida/asset-uploader-web ``` ```ts import { UploadTask } from "@nitida/asset-uploader-web"; const task = new UploadTask({ endpoint: process.env.NEXT_PUBLIC_NITIDA_URL!, tenantCode: "your-tenant", file, // Your OWN backend's token, not a nitida API key — see "The credential" below. authToken: await getSessionToken(), onProgress: ({ sentBytes, totalBytes }) => setPct(Math.round((sentBytes / totalBytes) * 100)), }); const { assetId, sha256 } = await task.start(); ``` Construct the same `UploadTask` again for the same file and it finds the in-flight session and continues. It matches on `(tenantCode, sha256)`, not on a handle you have to keep — so a fresh page after a reload resumes without you having stored anything. ## Expo [Section titled “Expo”](#expo) ```bash bunx expo install @nitida/asset-uploader-expo ``` The JS API is deliberately the same shape, so a call site written for the web reads identically. Underneath it is `URLSession` with a background configuration on iOS and `WorkManager` on Android: the OS keeps uploading after your process is gone, and hands the result back when the app returns. It ships an Expo config plugin. Prebuild picks it up from the package root; you do not add anything to `app.json` beyond the plugin entry: ```json { "expo": { "plugins": ["@nitida/asset-uploader-expo"] } } ``` The plugin appends UIKit’s background-URLSession event handler to your Swift `AppDelegate`. **Without it, an upload that finishes while the app is suspended never fires its completion handler and the asset stays “uploading” forever** — which looks exactly like a hung server and is not one. ## The credential, and what lands in the browser [Section titled “The credential, and what lands in the browser”](#the-credential-and-what-lands-in-the-browser) ⭐ **An uploader never sees a nitida API key.** `authToken` is *your* backend’s token; the uploader forwards it to *your* endpoint, which presigns against nitida with the key it holds server-side. If you find yourself putting an `amk_*` key in `authToken`, stop: you are about to ship a platform credential to every visitor. The web uploader persists its session in IndexedDB, because that is what “resume after a reload” means. What is in there, stated so nobody has to discover it: * **The part URLs** — presigned R2 PUT URLs. These *are* bearer credentials, and the bounds are the point: write-only, to the parts of one upload the user themselves started, 60-minute TTL, IndexedDB scoped to your origin, and the row is deleted on complete **and** on abort. * **Not the `authToken`.** It lives in memory on the task and is never written down. `UploadSession` has no field for it — that is the enforcement, not the intention. A reload therefore loses it and your app supplies it again. ## When NOT to use these [Section titled “When NOT to use these”](#when-not-to-use-these) * Files that comfortably fit one PUT. `aq.upload()` is fewer moving parts, and fewer moving parts is the whole argument. * A server-side script. There is no reload to survive; retry the PUT. * “Just in case.” Both packages add real bundle weight and a native module on the Expo side. A feature nobody reaches is a cost everybody pays. # The transform benchmark > What /t/ really delivers — bytes and pixels at every gallery width, the byte cost of each quality step, and the measured answer to whether a variant ladder makes the endpoint compress an already-compressed image twice. Measured **2026-08-17** against `https://api.nitida.gofuture.space` and `https://8ok.uk`, tenant `demo`, on the five documentation photographs — five different chromatic characters, so no conclusion here rests on one kind of image. Their licences are [at the bottom](#the-photographs). ## The headline: a stored ladder makes `/t/` compress twice [Section titled “The headline: a stored ladder makes /t/ compress twice”](#the-headline-a-stored-ladder-makes-t-compress-twice) `/t/` takes a documented shortcut: when a stored variant already covers the requested size, the server decodes **that** instead of the master, because decoding a 640px `sm` for a 320px thumb is \~9× cheaper than decoding a 3840px `xl`. It is a real and sensible optimisation — and it means the bytes handed to the encoder have **already been through a WebP pass**. So: the same photograph, uploaded twice. Once with the full ladder (`["original","thumb","sm","md","lg","xl"]`), once with `["original"]` and nothing else. Same request on both: `format=webp,quality=75,width=800`. **The shortcut fires.** On all 5 photographs the laddered asset answered with `X-Transform-Source: md` — the 1280 px WebP — and the original-only asset with `X-Transform-Source: original`. That is the difference under test, and nothing else: the two assets are the same pixels (the upload deduplicates by sha256, so the second copy carries a few bytes appended *after* the JPEG EOI marker, which every decoder ignores). | photo | ladder → source | bytes | PSNR vs master | SSIM vs master | original-only → source | bytes | PSNR | SSIM | | ----------- | --------------- | -------- | -------------- | -------------- | ---------------------- | -------- | -------- | ------ | | **autumn** | `md` | 103.3 KB | 30.76 dB | 0.9455 | `original` | 112.7 KB | 33.77 dB | 0.9656 | | **glacier** | `md` | 61.9 KB | 34.06 dB | 0.9335 | `original` | 67.7 KB | 35.73 dB | 0.9511 | | **night** | `md` | 11.7 KB | 38.35 dB | 0.9405 | `original` | 12.7 KB | 39.49 dB | 0.9495 | | **snow** | `md` | 27.1 KB | 35.38 dB | 0.9834 | `original` | 29.3 KB | 38.00 dB | 0.9892 | | **spices** | `md` | 51.3 KB | 34.74 dB | 0.9304 | `original` | 56.6 KB | 36.41 dB | 0.9499 | Both sides are compared against **the master**, never against each other — two outputs measured against one another tell you they differ, not which is worse. ### The verdict [Section titled “The verdict”](#the-verdict) **Yes, it re-compresses, and it is a straight loss — 5 times out of 5.** The doubly-compressed file is *smaller* (by 7.3 – 9.4 %) **and** worse on both metrics: up to **−3.01 dB** PSNR and **−0.0200** SSIM. That combination is the signature of generation loss, not of a saving. The file shrank because the first pass had already thrown the fine detail away, so the second encoder had less to describe. You are not buying bytes with quality — you are losing both, because the bytes you “saved” bought you nothing you asked for. ### The escape hatch, also measured [Section titled “The escape hatch, also measured”](#the-escape-hatch-also-measured) The shortcut is gated on the request carrying an **explicit numeric `quality`** — auto-quality has to probe the full-resolution master, so it cannot take it. Third arm, same laddered asset, same width, `quality` simply omitted. **“pinned” = `quality=75`; “unpinned” = no `quality` in the DSL.** | photo | pinned bytes | pinned PSNR | pinned SSIM | **unpinned bytes** | **unpinned PSNR** | **unpinned SSIM** | unpinned source | | ----------- | ------------ | ----------- | ----------- | ------------------ | ----------------- | ----------------- | --------------- | | **autumn** | 103.3 KB | 30.76 | 0.9455 | 105.5 KB | 33.26 | 0.9611 | `original` | | **glacier** | 61.9 KB | 34.06 | 0.9335 | 63.6 KB | 35.42 | 0.9472 | `original` | | **night** | 11.7 KB | 38.35 | 0.9405 | 11.4 KB | 39.02 | 0.9457 | `original` | | **snow** | 27.1 KB | 35.38 | 0.9834 | 27.8 KB | 37.44 | 0.9882 | `original` | | **spices** | 51.3 KB | 34.74 | 0.9304 | 53.8 KB | 36.08 | 0.9463 | `original` | Dropping `quality` moved every request back to `original` — one pass — and recovered most of the loss for almost nothing: the byte change ranges from **-2.6 %** to **+4.7 %** (1 of 5 came back *smaller*), while SSIM improves on **5 of 5**. **If you have the ladder and you want the master’s quality, do not pin `quality`.** ## Every gallery width [Section titled “Every gallery width”](#every-gallery-width) One photo (**spices**, 6000×4000 master), `format=webp,quality=75`, both assets. `source` is the variant the encoder actually decoded. | width | delivered px | with ladder | source | original only | source | ladder vs plain | | ----- | ------------ | ----------- | ------ | ------------- | ---------- | --------------- | | 400 | 400 px | 18.0 KB | `sm` | 19.8 KB | `original` | -9.1 % | | 480 | 480 px | 23.1 KB | `sm` | 25.9 KB | `original` | -10.5 % | | 600 | 600 px | 30.6 KB | `sm` | 35.7 KB | `original` | -14.2 % | | 640 | 640 px | 43.6 KB | `sm` | 39.3 KB | `original` | 10.9 % | | 800 | 800 px | 51.3 KB | `md` | 56.6 KB | `original` | -9.4 % | | 960 | 960 px | 63.3 KB | `md` | 72.1 KB | `original` | -12.2 % | | 1080 | 1080 px | 73.8 KB | `md` | 85.0 KB | `original` | -13.2 % | | 1200 | 1200 px | 85.2 KB | `md` | 98.9 KB | `original` | -13.8 % | | 1280 | 1280 px | 110.9 KB | `md` | 112.7 KB | `original` | -1.5 % | | 1440 | 1440 px | 118.6 KB | `lg` | 134.8 KB | `original` | -12.0 % | | 1600 | 1600 px | 136.4 KB | `lg` | 157.4 KB | `original` | -13.4 % | | 1920 | 1920 px | 207.6 KB | `lg` | 203.8 KB | `original` | 1.9 % | | 2560 | 2560 px | 290.0 KB | `xl` | 321.3 KB | `original` | -9.7 % | Every width delivers exactly the pixels it promises — the ladder is a fixed list and an off-ladder number is a 400 at the edge, not a resize. The worst rungs are the ones that match a stored variant exactly **640, 1280, 1920** are the widths where the covering variant is *exactly* the requested size (`sm` = 640, `md` = 1280, `lg` = 1920), so the shortcut hands the encoder a same-size WebP and there is **no downscale in between**. A downscale is what normally hides first-pass artefacts; without one, the second encoder must spend bits describing them. The bytes say it out loud: at **640 and 1920** the laddered asset comes back **heavier** than the original-only one — 640 px: 43.6 KB vs 39.3 KB; 1920 px: 207.6 KB vs 203.8 KB. More bytes *and* a second lossy pass, where every other rung at least traded one for the other. ## Quality, and what each step costs [Section titled “Quality, and what each step costs”](#quality-and-what-each-step-costs) Same photo, `width=1200`, both assets. | quality | ladder bytes | ladder SSIM | original-only bytes | original-only SSIM | original-only PSNR | | ------- | ------------ | ----------- | ------------------- | ------------------ | ------------------ | | 60 | 70.3 KB | 0.9090 | 80.5 KB | 0.9375 | 36.00 dB | | 70 | 80.2 KB | 0.9165 | 91.9 KB | 0.9460 | 36.72 dB | | 75 | 85.2 KB | 0.9196 | 98.9 KB | 0.9505 | 37.15 dB | | 80 | 105.7 KB | 0.9313 | 123.6 KB | 0.9621 | 38.45 dB | | 85 | 132.7 KB | 0.9395 | 158.6 KB | 0.9744 | 40.06 dB | | 90 | 177.6 KB | 0.9469 | 212.1 KB | 0.9828 | 42.03 dB | **What each quality step costs, per hundredth of SSIM** (single-pass arm — the honest one): | step | extra bytes | extra SSIM | bytes per 0.01 SSIM | | ------- | ----------- | ---------- | ------------------- | | 60 → 70 | +11.5 KB | +0.0085 | **13.5 KB** | | 70 → 75 | +6.9 KB | +0.0045 | **15.3 KB** | | 75 → 80 | +24.7 KB | +0.0117 | **21.2 KB** | | 80 → 85 | +35.0 KB | +0.0123 | **28.5 KB** | | 85 → 90 | +53.5 KB | +0.0084 | **63.6 KB** | The curve is the answer to “where does it stop being worth it”: the marginal price of quality rises from **13.5 KB** per SSIM hundredth at the bottom of the range to **63.6 KB** at the top. Note what that is and is not: SSIM is an objective similarity metric, not an eye. It tells you where the *encoder* stops buying fidelity with bytes. Whether a human can still see it at 1200 px on a given screen is a perceptual question this benchmark does not answer — see [what is still open](#what-this-page-does-not-answer). Raising `quality` cannot undo the first pass On this photo the doubly-compressed output at **quality 80** (105.7 KB, SSIM 0.9313) is still **worse** than the single-pass output at **quality 60** (80.5 KB, SSIM 0.9375) — and **31.3 % heavier**. Detail that the first pass discarded is gone; a higher `quality` on the second pass just spends bytes describing the artefacts more faithfully. ## `fit` [Section titled “fit”](#fit) | fit | request | delivered | bytes | | -------- | -------------------------------------------------------------------- | --------- | ------- | | `cover` | `format=webp,quality=75,width=800,height=800,fit=cover,gravity=auto` | 800×800 | 55.8 KB | | `inside` | `format=webp,quality=75,width=800,height=800,fit=inside` | 800×533 | 51.3 KB | `cover` fills the box and crops to do it; `inside` fits the box and keeps the whole frame, so the delivered height is whatever the aspect ratio gives. ## The ceiling: the master [Section titled “The ceiling: the master”](#the-ceiling-the-master) There is no upscale. Asking for more width than the source has returns the source’s width, quietly and with a 200. | master | asked | delivered | bytes | source | | --------------------- | ----- | ----------- | -------- | ---------- | | laddered, 6000 px | 3840 | **3840 px** | 647.6 KB | `xl` | | small master, 1200 px | 1920 | **1200 px** | 64.6 KB | `original` | | small master, 1200 px | 3840 | **1200 px** | 64.6 KB | `original` | Put widths in your `srcSet` that your masters can sustain, or the browser picks a candidate that does not exist at that size and downloads a smaller image than it thinks it is getting. ## Formats [Section titled “Formats”](#formats) Same photo, `width=800`, `quality=75`: | format | status | content-type | bytes | | ------ | ------ | ------------ | -------- | | `webp` | 200 | `image/webp` | 51.3 KB | | `jpeg` | 200 | `image/jpeg` | 59.8 KB | | `png` | 200 | `image/png` | 877.6 KB | | `avif` | 200 | `image/avif` | 73.5 KB | **The platform standardises on WebP.** The DSL accepts the others; the numbers above are bytes only. Note in particular that AVIF is **heavier** than WebP here at the same *nominal* `quality` — which is a statement about the two encoders’ quality scales, not proof that AVIF compresses worse: nothing on this page measured AVIF’s fidelity. Read the row as “the number you type means different things in different encoders”, and do not switch format on a byte count alone. ## How to read this page [Section titled “How to read this page”](#how-to-read-this-page) * **If your assets have the preset ladder** (the recommended upload), an explicit `quality` puts a second lossy pass between your master and your visitor. Either drop `quality` and let auto-quality read the master, or accept the loss knowingly for the cheaper decode. * **If your assets are `["original"]` only**, none of this applies: every transform comes off the master, one pass. * **The widths that match a stored variant exactly (640, 1280, 1920) are the worst case** — there is no downscale between the two passes to hide the first one’s artefacts, and at 640 and 1920 the result is heavier as well. ## What this page does *not* answer [Section titled “What this page does not answer”](#what-this-page-does-not-answer) Stated so nobody mistakes silence for a result: 1. **Perceptibility.** PSNR and SSIM are objective metrics. Nobody sat down and compared the two 800 px files side by side at 100 % on a calibrated display, and no perceptual metric (SSIMULACRA2, butteraugli) was run. “Where the difference stops being visible” is therefore reported as *where the metric plateaus*, which is not the same claim. 2. **Sample size per case.** The double-compression A/B is n = 5 photographs and every one agreed. The width, quality, `fit`, ceiling and format sweeps are **n = 1** — one photograph, chosen for being the busiest of the five. Treat the *shape* of those curves as the finding and the exact kilobytes as one data point. 3. **Cold-path timing.** `Server-Timing` is on every response and was not collected; this page is about bytes and quality, not latency. 4. **Whether the shortcut should exist.** It is a large decode saving and this page does not price it. It measures what it costs, so that the trade can be made on purpose. ## Reproducing it [Section titled “Reproducing it”](#reproducing-it) Nothing here needs a privileged key. The probe runs against the **public** API with an ordinary **runtime** key on an ordinary tenant — the same two things [credentials](/start/credentials/) gives you — so you can re-run the whole thing on your own account: ```bash export NITIDA_KEY="…" # your runtime key export NITIDA_TENANT_CODE="…" # your tenant code ``` What the probe does, in order: 1. Uploads the same photograph twice — once with the full ladder (`["original","thumb","sm","md","lg","xl"]`), once with `["original"]` and nothing else. 2. Requests the identical transform DSL from both and records status, `content-type`, bytes and the variant the response was decoded from. 3. Sweeps width, `quality`, `fit` and format against the busiest of the five photographs, and computes PSNR/SSIM between the two arms. The first run uploads both sides of the A/B; re-runs deduplicate and only re-measure. **The cold path can answer 302 to the canonical `/v/` object** — the probe follows it and retries until it has bytes, because a naïve `fetch` records 0 KB and calls it a measurement. ## The photographs [Section titled “The photographs”](#the-photographs) All five from [Pexels](https://www.pexels.com/) under the [Pexels License](https://www.pexels.com/license/) (verified 2026-08-17: free to use, attribution not required — credited anyway). | photo | character | photographer · source | | ------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | autumn | warm / golden — backlit yellow and orange, almost no cool hue | [Ekaterina Swiss](https://www.pexels.com/@ekaterina-swiss-3802271) · [Pexels 11696183](https://www.pexels.com/photo/yellow-maple-leaves-on-a-tree-11696183/) | | glacier | cool / blue — deep cyan ice against near-black rock | [Lars H Knudsen](https://www.pexels.com/@farlight) · [Pexels 13314282](https://www.pexels.com/photo/close-up-of-a-glacier-13314282/) | | night | very dark — a low-key twilight scene, everything below mid-grey | [Andrea Bova](https://www.pexels.com/@andrea-bova-1169228) · [Pexels 5871563](https://www.pexels.com/photo/silhouette-of-trees-at-night-5871563/) | | snow | very light — a high-key scene, almost no dark pixels at all | [Perati Wattanawikkarn](https://www.pexels.com/@perati-wattanawikkarn-2149005101) · [Pexels 30471757](https://www.pexels.com/photo/serene-winter-landscape-with-snow-covered-trees-30471757/) | | spices | saturated — cones of red, orange and yellow powder, no neutrals | [Mike van Schoonderwalt](https://www.pexels.com/@mike-van-schoonderwalt-1884800) · [Pexels 5504603](https://www.pexels.com/photo/orange-and-red-spices-on-street-market-5504603/) | # What each symptom actually means > A status code here rarely means what it means elsewhere. The table that saves the afternoon. Most of these produce a *confident wrong diagnosis* rather than an error, which is why they cost hours. Read the symptom, not the intuition. | symptom | what it actually is | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `PUT failed: network error`, everything else green | your origin is not in the **bucket’s** CORS policy. The browser PUTs straight to storage, so storage answers that preflight — not your app, not any tenant setting | | **400** on an image URL | the width is not on `TRANSFORM_WIDTHS`. Deliberate: an open resize endpoint is a DoS amplifier | | **410** on a video `/t/` URL | that video has **no poster** variant. When it has one, `/t/` succeeds and returns the *poster* as an image (`x-transform-source: poster`) — never playable video. Use `urlFor(asset, "video")` | | **422** `source_undecodable` | the stored bytes are not a decodable image — a corrupt upload we stored faithfully (the sha256 matches). No retry helps; re-upload. Distinct from a **500**, which means *we* broke | | **404** on a preset you never asked for | `presets` defaults to `["original"]`, so a bare upload has no `lg`. Since 2026-08-22 `getAssetUrl` falls back to `/t/` when the DTO says the rung is missing — if you still get a 404, the DTO you passed carried no `presets` for it to check | | **404** on EVERY URL of one asset — variant, raw, ladder and `/t/` alike | the asset is `private`. Check `visibility` on the DTO **before** you check storage: everywhere else a 404 means the object was never written, here it means the door is closed. Mint a signed URL with `getPrivateAssetUrl`. See [Access and privacy](/concepts/access-and-privacy/) | | **401** on an `/a/…` signed URL | one of three, in the order worth checking: the `exp` has passed (they are meant to), the path was edited after signing (the signature covers it), or the signing key was rotated since the URL was minted | | a private asset still serves for up to a minute after the flip | the CDN refreshes its list of private assets on a **60-second** TTL. Revocation is “within a minute”, not “this instant” | | **404** on a video URL | the tenant prefix is base36, not decimal. Tenant 10 is `/a/v/`, not `/10/v/`. Invisible for tenants ≤ 9 | | **404** on an `original` URL | either it was never written (presets omitted `"original"`), or you built `-o.bin` by omitting `mime`, or the stored extension came from the filename (`-o.jpg`) and you asked for `-o.jpeg` | | **a portrait photo arrives stretched wide**, and only some do | `@nitida/asset-compressor-web` **0.6.0–0.6.2** forced the stored (pre-EXIF) dimensions onto a decode that had already applied the rotation — a measured **1.78×** stretch. Needs all three: a parseable header (**HEIC is immune**), EXIF orientation 5–8, and a long side above the box, which is why it looks random. **Fixed in 0.6.3**; the damage is pre-upload, so stored photos must be re-uploaded, not repaired. See [Compression → Rotation](/guides/compression/#rotation-a-photo-held-upright-stays-upright) | | **`width`/`height` on the DTO disagree with the image you get** | an `asset-manager` older than 2026-08-28 recorded the *stored* pair for EXIF-rotated sources while serving the *rotated* variants, so the aspect ratio came back transposed. Fixed. The **variant** dimensions were always correct — if you need one number to trust before re-processing, use the variant’s | | `process returned no assetId` | an `asset-manager` older than 2026-08-16. Fixed | | `waitReady timeout` on a video | a transcode plus the HLS ladder runs 1–2 min. The 5-minute default is a floor a 4K source can beat | | asset stuck at `processing` | fixed 2026-08-16. If you still see it, the row was written by an older deployment | | `aq.assets.variants()` returns `[]` | known: it returns empty even with an admin key while the row holds variants. **Use `dto.presets`** | | video plays at 240p for the first 8 seconds | the classic `canPlayType` check sent Chrome down the native-HLS branch. See [Video and HLS](/guides/video-and-hls/) | | an upload “worked” but nothing is retrievable | `presets: ["thumb"]` stores no original. Verify by SHA-256 round-trip, never by upload count | | a re-upload succeeds and proves nothing | presign short-circuits on bytes it has seen. Generate unique bytes when testing | ## The one that is not an error at all [Section titled “The one that is not an error at all”](#the-one-that-is-not-an-error-at-all) **A `202` on a master playlist is a success.** The ladder is built by a job; the first request returns `202` while it runs and `302`s to the cached master afterwards. No `error` event ever fires. A player that only swaps sources in an error handler will spin forever on a ladder that is still transcoding. Race a timer against `canplay` instead, and cancel it the moment `canplay` fires so healthy HLS keeps its adaptive bitrate. ## WebKit cannot encode WebP — and it does not matter as much as it looks [Section titled “WebKit cannot encode WebP — and it does not matter as much as it looks”](#webkit-cannot-encode-webp--and-it-does-not-matter-as-much-as-it-looks) Asking a canvas for `image/webp` on **any** WebKit browser yields something else. This is not an iOS quirk: MDN’s compatibility data records `canvas.toBlob(type="image/webp")` as **unsupported in Safari**, full stop — desktop Safari on macOS included — and every browser on iOS is WebKit underneath, so they all inherit it. Measured on iOS 27 / Chrome 151, a 9.1 MP photo: `2.05 MB → 743.7 kB`, labelled `jpeg`. The engine declined WebP, the compressor fell back to JPEG, and the file was named for **the bytes that came out** rather than the format that was requested. ### Why it barely matters [Section titled “Why it barely matters”](#why-it-barely-matters) **Delivery is WebP for everyone regardless.** The client format only decides what crosses the wire on the way *in*; the server re-encodes every variant: ```plaintext browser (WebKit) ──JPEG──▶ server ─────────▶ thumb/sm/md/lg/xl as WebP browser (Chromium) ─WebP──▶ server ─────────▶ thumb/sm/md/lg/xl as WebP ``` So a Safari user’s visitors still get WebP. What the fallback costs is a slightly larger upload — JPEG at the same visual quality is bigger than WebP — and an archived `original` that is JPEG rather than WebP. Label by the bytes, never by the format you asked for The failure mode is not the fallback — the fallback is correct. It is naming the file for what you *requested*. A `.webp` that is secretly a PNG breaks every downstream consumer that trusts the extension, and that exact bug was found in **five separate places** once anyone looked. # Video and HLS > Poster, progressive MP4, the adaptive ladder, and the AI proxy — plus the two mistakes everyone makes first. Video is where this stops being an image CDN. A single upload produces a poster frame, a web-safe progressive MP4, an adaptive HLS ladder, and — if you ask for it — a proxy encoded for a model to watch rather than a person. video-and-hls.ts ```ts /** * Video: upload, poster, progressive MP4 and the adaptive HLS ladder. * * The two things that bite people here: * 1. A video is served from a STORED VARIANT, never from `/t/` (a transform * URL on a stored video answers 410). * 2. A video finalizes ASYNCHRONOUSLY. `upload()` returns once the bytes are * in and a background transcode job is dispatched; the row flips to * `ready` a minute or two later. Budget a real timeout — the default * 5 min is a floor, not a promise. */ import { NitidaClient } from "@nitida/sdk"; const nt = new NitidaClient({ endpoint: process.env.NITIDA_ENDPOINT ?? "https://assets.example.com", apiKey: process.env.NITIDA_RUNTIME_KEY, tenantCode: "demo", tenantId: Number(process.env.NITIDA_TENANT_ID ?? 1), }); export async function uploadVideo(file: File) { const result = await nt.upload(file, { // `aiproxy` is the low-cost proxy an LLM analyses (5 fps, 720p, CRF 28) — // omit it if nothing downstream reads the video with a model. presets: ["original", "poster", "video", "aiproxy"], // A transcode plus the HLS ladder runs 1–2 min. Give it room. timeoutMs: 10 * 60_000, }); const asset = { sha: result.sha256 }; return { assetId: result.assetId, // The progressive MP4, off the stored variant ladder. mp4: nt.urlFor(asset, "video"), // The poster frame (sampled at 10% of the duration). poster: nt.urlFor(asset, "poster"), // The adaptive ladder's master playlist. hls: nt.streamingUrl(asset), }; } /** * Download-only clips — a reel that is never streamed — should skip the HLS * ladder. It is a second background job building 240p→1080p renditions nobody * watches. The on-demand route still self-heals HLS if someone ever does. */ export async function uploadDownloadOnlyClip(file: File) { return nt.upload(file, { presets: ["original", "poster", "video"], video: { hls: false }, timeoutMs: 10 * 60_000, }); } ``` ## Video finalizes asynchronously [Section titled “Video finalizes asynchronously”](#video-finalizes-asynchronously) `upload()` returns once the bytes are stored and a transcode job is dispatched. The row flips to `ready` a minute or two later, when the job finishes. Anything that filters on `status === "ready"` — which is what a storefront should do — will not show the asset until then. Budget for it. The default poll timeout is five minutes, which a 4K source can beat; pass a real `timeoutMs`. ## The five presets [Section titled “The five presets”](#the-five-presets) | preset | what it is | who it is for | | --------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | `poster` | frame sampled at 10% of the duration, WebP q80 | the `