# Image delivery and resizing: questions and answers

Short answers about how Talewright serves files: the files host, signed
links against public links, headers, caching, byte ranges, image variants
made on request with every option and format, which sources can be resized,
limits and refusals, use from other websites, responsive images and
performance. Each answer links to the section of
[Image delivery](../files/image-delivery.md) that owns the rule.

## How files are served

### Where are files served from?

From one separate host, the files host:
`https://files.talewrightusercontent.com`. Every link to a file leads
there: signed links, public links and their image variants.

More: [Image delivery, The files host](../files/image-delivery.md#the-files-host)

### Why are files served from a different host than the app?

On purpose: nothing a file contains can act as the app. The app and the API
live on `https://app.usetalewright.com` and never serve a file inline.

More: [Image delivery, The files host](../files/image-delivery.md#the-files-host)

### Which kinds of addresses does the files host have?

Five: `/s/{token}/{name}` for a signed link, `/p/{slug}/{name}` for a public
link, `/_img/{options}/...` for an image variant of either, `/p/f/{slug}/{name}`
for the gallery page of a public folder and `/z/{token}/{name}.zip` for a
ZIP download.

More: [Image delivery, The files host](../files/image-delivery.md#the-files-host)

### Which HTTP methods does the files host answer?

`GET` and `HEAD`. Any other method answers `405 METHOD_NOT_ALLOWED`. The one
exception is `OPTIONS` on a public link or its variant, which answers a
preflight.

More: [Image delivery, The files host](../files/image-delivery.md#the-files-host)

### Does the files host use cookies?

No. It ignores cookies. A request with a cookie gets the same answer as one
without, and no answer sets a cookie.

More: [Image delivery, The files host](../files/image-delivery.md#the-files-host)

### Do I need an API key or a sign-in to open a file link?

No. Neither kind of link needs a key, a cookie or a sign-in. The link is the
whole permission. Do not send your key to the files host.

More: [Image delivery, Who can do what](../files/image-delivery.md#who-can-do-what)

### Does the file name at the end of a file address matter?

No. It is only a label, so that a saved file gets a sensible name. The files
host finds the file by the token or the slug. Any name works, and renaming
the file breaks no link.

More: [Image delivery, The files host](../files/image-delivery.md#the-files-host)

### How is a file named `a/b.jpg` written in its links?

Percent-encoded. Its links end in `a%2Fb.jpg` and work, variants included.

More: [Image delivery, The files host](../files/image-delivery.md#the-files-host)

### What does a refusal from the files host look like?

It has the same JSON body as an API error, with a `requestID`, and it
carries `Cache-Control: no-store`.

More: [Image delivery, The files host](../files/image-delivery.md#the-files-host)

### Is the files host part of the REST API or of MCP?

No. It is plain HTTP: `GET` an address. It has no MCP tools and needs no
`Authorization` header.

More: [Image delivery, For agents](../files/image-delivery.md#for-agents)

### Why does a file link answer `405 METHOD_NOT_ALLOWED`?

The request used a method other than `GET` or `HEAD`, such as `POST` or
`DELETE`, or it sent `OPTIONS` to something other than a public link or its
variant. The files host only serves.

More: [Image delivery, Errors](../files/image-delivery.md#errors)

### Does a file link check the file's state on every request?

Yes. Every request is checked against the file's state at that moment. A
file that stops being public stops answering at once.

More: [Image delivery, Public links](../files/image-delivery.md#public-links)

## Signed links and public links

### What is the difference between a signed link and a public link?

A signed link works for 10 minutes and names one version. It is how people
with access see and download files. A public link works for everyone for as
long as the file is public, and follows the current version. It is what you
put on a website.

More: [Image delivery, Summary](../files/image-delivery.md#summary)

### Which link should I put on my website, a signed one or a public one?

A public link. A signed link stops after 10 minutes. For something that
should keep working, make the file public and use its public link.

More: [Image delivery, Signed links](../files/image-delivery.md#signed-links)

### Who can get a signed link to a file?

Everyone who can open the file's workspace, or every member of the
organization for an organization folder file. A credential needs `files:read`.

More: [Image delivery, Who can do what](../files/image-delivery.md#who-can-do-what)

### Who can open a signed link once it exists?

Anyone who holds it, until it expires. No sign-in, no cookie and no API key
is checked.

More: [Image delivery, Signed links](../files/image-delivery.md#signed-links)

### Is it safe to publish or forward a signed link?

Treat a signed link like the file itself. It works for whoever holds it, so
do not publish it.

More: [Image delivery, Signed links](../files/image-delivery.md#signed-links)

### What do the signed link variants `original`, `thumb`, `preview` and `playback` serve?

`original` serves the version's own bytes. `thumb` is a WebP that fits 320
pixels. `preview` is a WebP that fits 1,600 pixels. `playback` is a video's
MP4 rendition.

More: [Image delivery, Signed links](../files/image-delivery.md#signed-links)

### Does a signed link serve a new version when the file is replaced?

No. It keeps naming the same version. If the file gets a new version, the
link still serves the version it was made for, until it expires.

More: [Image delivery, Signed links](../files/image-delivery.md#signed-links)

### What makes a signed link stop before its 10 minutes are over?

The file is moved to the trash, restored from the trash or deleted for good,
or its workspace or organization is deleted.

More: [Image delivery, Signed links](../files/image-delivery.md#signed-links)

### Does a signed link work again after its file is restored from the trash?

No. Links from before the trash stay stopped. Ask for a new one.

More: [Image delivery, Signed links](../files/image-delivery.md#signed-links)

### Can I tell from a `403` whether a signed link expired or was altered?

No. A signed link that is altered, expired or stopped answers
`403 FORBIDDEN`, and the answer does not say which of the three it was.

More: [Image delivery, Signed links](../files/image-delivery.md#signed-links)

### Why is a file's `thumbnailURL` or `previewURL` `null`?

The rendition is not ready yet, or the file is in the trash.

More: [Image delivery, Signed links](../files/image-delivery.md#signed-links)

### Can a restricted file have a signed link?

Yes. Signed links are how people and credentials with access read any file,
public or not.

More: [Image delivery, Signed links](../files/image-delivery.md#signed-links)

### What does the answer to a signed link request hold?

`{"url": "...", "expiresAt": "..."}`. `url` is on the files host and works
for 10 minutes. `expiresAt` says when it stops.

More: [Image delivery, For agents](../files/image-delivery.md#for-agents)

### Can I get a signed link to an earlier version of a file?

Yes. Any version of the file can be named, not only the current one.

More: [Image delivery, For agents](../files/image-delivery.md#for-agents)

### Where does an agent get a file's public link?

From `publicURL` on a file read on its own. It is `null` while the file is
not public. A listing says whether each file is public but does not carry
the link.

More: [Image delivery, For agents](../files/image-delivery.md#for-agents)

### Which links does the app itself use to show files?

Signed links for everything: thumbnails in listings, the preview on a file's
page, video playback and "Download". It builds no variant addresses.

More: [Image delivery, In the app](../files/image-delivery.md#in-the-app)

### Why did a thumbnail in the app fail and then come back?

Its signed link expired: a thumbnail's link works for 10 to 15 minutes.
When a thumbnail or preview fails to load, the app fetches the listing
again once to get fresh links.

More: [Image delivery, In the app](../files/image-delivery.md#in-the-app)

### May a CDN or shared cache keep the answer of a signed link?

No. A signed answer is `private`. A browser may reuse it until the link
expires. A shared cache or a CDN may not keep it.

More: [Image delivery, Signed links](../files/image-delivery.md#signed-links)

## Headers on a file answer

### Which headers does the answer to a file link carry?

`Content-Type`, `Content-Length`, `Content-Disposition`, `ETag`,
`Accept-Ranges`, `Cache-Control`, `X-Content-Type-Options`,
`Content-Security-Policy` and `x-request-id`. A public link adds
`Cache-Tag` and the cross-origin headers.

More: [Image delivery, What an answer carries](../files/image-delivery.md#what-an-answer-carries)

### How is the `Content-Type` of a served file decided?

It is the file's real type, found from its bytes when it was uploaded. It is
not the type the uploader claimed.

More: [Image delivery, What an answer carries](../files/image-delivery.md#what-an-answer-carries)

### What is the `ETag` of a served file?

The SHA-256 of the bytes, in quotes: `"sha256:{64 hex digits}"`. It is the
same value as the version's `digest` in the API.

More: [Image delivery, What an answer carries](../files/image-delivery.md#what-an-answer-carries)

### What does `Content-Disposition` on a file link hold?

`inline` or `attachment`, with the file's current name, for example
`inline; filename="hero.jpg"; filename*=UTF-8''hero.jpg`. The name is the
file's current one, whatever name the address ends in.

More: [Image delivery, What an answer carries](../files/image-delivery.md#what-an-answer-carries)

### What happens to special characters in the name of a downloaded file?

In `filename="..."`, characters outside printable ASCII, `"` and `\` are
replaced by `_`. `filename*` carries the exact name.

More: [Image delivery, What an answer carries](../files/image-delivery.md#what-an-answer-carries)

### What is the `Cache-Tag` header on a public link?

`tw-file-{fileID}`. Originals, partial answers, `304` answers, variants and
their redirects of one file all carry the same tag. It is sent on public
answers only.

More: [Image delivery, Caching](../files/image-delivery.md#caching)

### Why do file answers carry `nosniff` and a sandboxing policy?

So that a browser shows the file as the type it is, and a file opened
directly in a tab cannot run scripts. They do not affect a file used as an
image, a font or a video on a page.

More: [Image delivery, What an answer carries](../files/image-delivery.md#what-an-answer-carries)

### What is a thumbnail named when it is saved from a signed link?

After the file, with the rendition's extension. The thumbnail of `hero.png`
is `hero.webp`.

More: [Image delivery, What an answer carries](../files/image-delivery.md#what-an-answer-carries)

## Opening in the browser or downloading

### Why does a file link sometimes open in the browser and sometimes download?

It depends on the file's type. Web images, MP4, WebM and PDF open in the
browser. Everything else downloads, SVG and HEIC included.

More: [Image delivery, Inline or download](../files/image-delivery.md#inline-or-download)

### Which file types download from a link?

SVG, HEIC and HEIF, Photoshop files and raw photos, Illustrator, EPS,
InDesign and Figma files, fonts, QuickTime (`.mov`), and CSV, DOCX, XLSX,
Markdown and plain text.

More: [Image delivery, Inline or download](../files/image-delivery.md#inline-or-download)

### Why does my SVG download when I open its link?

An SVG opened directly is served as a download. A page that uses the link as
a resource is not affected: the SVG shows in an `<img>`.

More: [Image delivery, Inline or download](../files/image-delivery.md#inline-or-download)

### Why does my HEIC photo download and not show?

Browsers do not show HEIC, so the original is served as a download. Use a
variant of it, such as `f=webp` or `f=auto`: that shows everywhere.

More: [Image delivery, Inline or download](../files/image-delivery.md#inline-or-download)

### Why does a font link download when I open it?

A font opened directly downloads. Used in a stylesheet's `@font-face` it
loads as a font.

More: [Image delivery, Inline or download](../files/image-delivery.md#inline-or-download)

### Does a PDF open in the browser from its link?

Yes. A PDF is served `inline`.

More: [Image delivery, Inline or download](../files/image-delivery.md#inline-or-download)

### Does a QuickTime `.mov` file play in the browser from its link?

No. Opened directly, a `.mov` downloads. MP4 and WebM open in the browser,
and so does a video's `playback` rendition.

More: [Image delivery, Inline or download](../files/image-delivery.md#inline-or-download)

### Is the rule for opening or downloading different for signed and public links?

No. The rule is the same for both.

More: [Image delivery, Inline or download](../files/image-delivery.md#inline-or-download)

## Conditional requests

### Do file links support `If-None-Match`?

Yes. A public link and a signed link answer `304 Not Modified`, without a
body, when the request's `If-None-Match` names the current `ETag`.

More: [Image delivery, Conditional requests](../files/image-delivery.md#conditional-requests)

### When does the `ETag` of a public link change?

When the file gets a new version. A request with the old tag then gets the
new bytes with `200`.

More: [Image delivery, Conditional requests](../files/image-delivery.md#conditional-requests)

### Does a weak `ETag` such as `W/"sha256:..."` match?

Yes. The weak form a CDN may turn a tag into matches too. `If-None-Match`
may also list several tags, and `*` matches.

More: [Image delivery, Conditional requests](../files/image-delivery.md#conditional-requests)

### Which headers does a `304` answer carry?

The `ETag` and the same `Cache-Control`. On a public link it also carries
the `Cache-Tag`.

More: [Image delivery, Conditional requests](../files/image-delivery.md#conditional-requests)

### How can I check cheaply whether a public file changed?

Send its last `ETag` as `If-None-Match`. An unchanged file answers a short
`304`. The tag is the file's `currentVersion.digest` from the API, in
quotes, so an agent that mirrors public files can poll this way and download
only when the file changed.

More: [Image delivery, A conditional request](../files/image-delivery.md#a-conditional-request)

### Does a signed link answer `304`?

Yes, while the link works. A signed link names one version, whose bytes
never change, so its `ETag` matches for as long as the link works. A link
that no longer works answers `403` whatever the request sends.

More: [Image delivery, Conditional requests](../files/image-delivery.md#conditional-requests)

## Byte ranges and resuming

### Can I download only part of a file?

Yes. Signed links and public links serve one byte range per request. The
answer is `206 Partial Content` with
`Content-Range: bytes {start}-{end}/{size}`.

More: [Image delivery, Ranges](../files/image-delivery.md#ranges)

### Which forms of the `Range` header are understood?

Three: `bytes=0-99` (from, to, both included), `bytes=100-` (from there to
the end) and `bytes=-500` (the last 500 bytes).

More: [Image delivery, Ranges](../files/image-delivery.md#ranges)

### Can I ask for several byte ranges in one request?

No. A header with several ranges, such as `bytes=0-9,20-29`, is ignored and
the whole content is sent with `200`.

More: [Image delivery, Ranges](../files/image-delivery.md#ranges)

### Why does a byte range on a file link answer `416`?

The range starts at or past the end of the file, or it is `bytes=-0`. The
answer carries `Content-Range: bytes */{size}` and `details.sizeBytes` with
the real size.

More: [Image delivery, Ranges](../files/image-delivery.md#ranges)

### What happens with a range that ends past the end of the file?

The end is cut to the last byte, and the answer is `206` up to there.

More: [Image delivery, Ranges](../files/image-delivery.md#ranges)

### What happens with a `Range` header the files host does not understand?

It is ignored and the whole content is sent with `200`: another unit than
`bytes`, a start after the end, or anything malformed.

More: [Image delivery, Ranges](../files/image-delivery.md#ranges)

### How do I resume a download from a public link without mixing two versions?

Send `Range` for the missing part and the `ETag` you started with as
`If-Range`. If the file got a new version meanwhile, you get the whole new
file with `200` instead of a mix.

More: [Image delivery, Ranges](../files/image-delivery.md#ranges)

### Which values of `If-Range` make the files host serve the range?

Only the exact current `ETag`, quotes included. An earlier version's tag, a
weak tag (`W/...`) or a date gets the whole current content with `200`. No
`Last-Modified` is sent, so a date never matches.

More: [Image delivery, Ranges](../files/image-delivery.md#ranges)

### Do image variants support byte ranges?

No. Variants ignore `Range` and are always sent whole. They carry no
`Accept-Ranges`.

More: [Image delivery, Ranges](../files/image-delivery.md#ranges)

### Do public links of videos answer range requests?

Yes. A public link serves one byte range per request with `206`, whatever
the file's type.

More: [Image delivery, Ranges](../files/image-delivery.md#ranges)

## Caching

### Which `Cache-Control` does a public link send?

`public, max-age=60, s-maxage=31536000`. A browser reuses its copy for 60
seconds and then asks again with `If-None-Match`. A CDN may keep the answer
for up to a year.

More: [Image delivery, Caching](../files/image-delivery.md#caching)

### Why is there no `immutable` on a public link?

Because the same address serves a new version when the file is replaced.

More: [Image delivery, Caching](../files/image-delivery.md#caching)

### I replaced a file. Do I have to change the addresses on my site?

No. The public link and all its variant addresses stay the same and serve
the new version. Browsers pick it up within a minute.

More: [Image delivery, Caching](../files/image-delivery.md#caching)

### Why do visitors still see the old picture right after I replaced it?

A browser reuses its own copy for up to 60 seconds. After that it asks again
and gets the new one. A reload that revalidates gets the current state at
once.

More: [Image delivery, Caching](../files/image-delivery.md#caching)

### Do I have to purge a cache after replacing a public file?

No. The copies a CDN keeps of a file are dropped when what its link serves
changes, and a new current version is one of those changes.

More: [Image delivery, Caching](../files/image-delivery.md#caching)

### Which changes drop the copies a CDN keeps of a file?

A new current version. The file or a folder above it made public or
restricted. A status change or a move that starts or stops its link. The
file moved to the trash, restored or deleted for good. Its workspace or
organization deleted.

More: [Image delivery, Caching](../files/image-delivery.md#caching)

### Does a CDN keep serving a file after I restrict it?

No. Restricting a file drops the copies a CDN keeps for it, and the files
host answers `404` at once. A browser that just loaded it may show its own
copy for up to 60 seconds.

More: [Image delivery, Caching](../files/image-delivery.md#caching)

### Can the files host itself serve a stale file?

No. Every request is checked against the current state, also for variants
that were rendered earlier.

More: [Image delivery, Caching](../files/image-delivery.md#caching)

### Does the answer of a public link depend on who asks or from where?

No. No public answer carries `Vary`. The answer is the same whoever asks and
from wherever. The one exception is the redirect of `f=auto`.

More: [Image delivery, Caching](../files/image-delivery.md#caching)

### How is the answer of a signed link cached?

`Cache-Control: private, max-age={seconds}`, where the seconds are what is
left until the link stops. The browser may reuse the answer until the
link expires, and shared caches may not keep it.

More: [Image delivery, Caching](../files/image-delivery.md#caching)

### Why does a link that was refused start working without a delay?

Refusals are never kept. Every refusal carries `Cache-Control: no-store`, so
no browser or CDN holds on to it.

More: [Image delivery, Caching](../files/image-delivery.md#caching)

### Are public files served through a CDN?

Public answers are marked so that a CDN may keep them for up to a year, and
the kept copies are dropped when what the link serves changes.

More: [Image delivery, Caching](../files/image-delivery.md#caching)

## Image variants: the basics

### What is an image variant?

A resized and re-encoded copy of an image, made when it is first asked for:
the same picture, smaller, as AVIF, WebP, JPEG or PNG.

More: [Image delivery, Image variants](../files/image-delivery.md#image-variants)

### How do I resize an image by URL?

Put `/_img/{options}` in front of the path of the image's link. For example
`https://files.talewrightusercontent.com/_img/w=640/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg`
gives a WebP at most 640 pixels wide.

More: [Image delivery, The address](../files/image-delivery.md#the-address)

### Where do the options go in a variant address?

Right after the host name: `/_img/`, then the options as `key=value` pairs
separated by commas with no spaces, then the link's own path unchanged.

More: [Image delivery, The address](../files/image-delivery.md#the-address)

### Do I have to generate image sizes in advance?

No. Nothing has to be prepared. A variant is made when it is first asked
for.

More: [Image delivery, Summary](../files/image-delivery.md#summary)

### Can I pass image options as a query string, like `?w=640`?

No. Options go in the path, right after `/_img/`. A variant address with a
`?` is refused with "Image addresses have no query".

More: [Image delivery, The address](../files/image-delivery.md#the-address)

### How do I build a variant address from a public link?

1. Take the file's public link.
2. Split it after the host: `https://files.talewrightusercontent.com` and
   `/p/{slug}/{name}`.
3. Put `/_img/{options}` between the two.

More: [Image delivery, Building a variant address from a public link](../files/image-delivery.md#building-a-variant-address-from-a-public-link)

### Who can open an image variant?

Exactly the people the link is available to. The link is checked first on
every request, before any stored variant is looked at.

More: [Image delivery, The address](../files/image-delivery.md#the-address)

### Does a variant of a public link show the new version after the file is replaced?

Yes. A variant of a public link follows the current version, like the link
itself.

More: [Image delivery, The address](../files/image-delivery.md#the-address)

### What happens to image variants when the file is made restricted?

Every variant address answers `404` at once, also for variants that were
rendered before.

More: [Image delivery, The address](../files/image-delivery.md#the-address)

### Can I resize an image that is not public?

Yes. Put the options in front of the path of a signed link. The variant
works for as long as the signed link does.

More: [Image delivery, Worked example: a signed link, then a variant of it](../files/image-delivery.md#worked-example-a-signed-link-then-a-variant-of-it)

### Does the app give me variant addresses?

No. The app builds no variant addresses: those are for your own pages. Copy
the public link from "Public link" and put `/_img/{options}` after the host
name.

More: [Image delivery, In the app](../files/image-delivery.md#in-the-app)

### Is a variant address stable over time?

Yes. The canonical address of a public file's variant stays valid for as
long as the file is public. If the resizing rules change, `v` goes up and
the old address redirects to the new one.

More: [Image delivery, Options](../files/image-delivery.md#options)

### Does the file name at the end of a variant address set the output format?

No. The format comes from `f`. `.../hero.jpg` with `f=webp` is a WebP.

More: [Image delivery, What a variant looks like](../files/image-delivery.md#what-a-variant-looks-like)

### What is the shortest variant address that works?

One option is enough, for example `/_img/w=640/p/{slug}/{name}`. It
redirects to the full address of a 640-pixel WebP.

More: [Image delivery, Canonical addresses and redirects](../files/image-delivery.md#canonical-addresses-and-redirects)

## The options

### Which options does a variant address take?

Six: `v` (version of the resizing rules), `w` (greatest width), `h`
(greatest height), `q` (quality), `fit` (`inside` or `cover`) and `f`
(output format).

More: [Image delivery, Options](../files/image-delivery.md#options)

### What does the option `w` do?

It sets the greatest width in pixels. The number is raised to the next of
320, 640, 960, 1280, 1600, 2048 and 2560. `w` is always in effect: an
address without it means `w=1280`.

More: [Image delivery, Options](../files/image-delivery.md#options)

### What does the option `h` do?

It sets the greatest height in pixels, on the same ladder of steps as `w`.
`0` means no limit on height, which is also the default.

More: [Image delivery, Options](../files/image-delivery.md#options)

### What does the option `q` do?

It picks one of three quality levels: 60 for smaller files, 80 as the
default and 90 for the closest match to the original. Other numbers are
raised to the next level.

More: [Image delivery, Options](../files/image-delivery.md#options)

### What does `fit=inside` do?

It scales the picture down until it fits inside `w` by `h`, keeping its
proportions. Nothing is cut off. With `h=0` only the width limits it.

More: [Image delivery, Options](../files/image-delivery.md#options)

### What does `fit=cover` do?

It scales the picture down until it covers `w` by `h` and cuts off what
sticks out, around the centre. The result has the shape of `w` by `h`. It
needs a height.

More: [Image delivery, Options](../files/image-delivery.md#options)

### What does the option `f` do?

It names the format of the answer: `avif`, `webp`, `jpeg` or `png`. `auto`
picks AVIF or WebP for the browser that asks.

More: [Image delivery, Options](../files/image-delivery.md#options)

### What does the option `v` do?

It names the version of the resizing rules, so that an address always means
the same picture. When the rules change in a way that changes the bytes,
the number goes up. It is `3` now.

More: [Image delivery, Options](../files/image-delivery.md#options)

### What are the default values of the image options?

`v=3`, `w=1280`, `h=0`, `q=80`, `fit=inside` and `f=webp`.

More: [Image delivery, Options](../files/image-delivery.md#options)

### Why can I not get an image exactly 700 pixels wide?

So that every image has a small, fixed set of variants that can be kept
ready. Ask for 960 and let the browser scale it, or list several steps in
`srcset` and let the browser choose.

More: [Image delivery, Canonical addresses and redirects](../files/image-delivery.md#canonical-addresses-and-redirects)

### What do I get when I ask for `w=600`?

A redirect to `w=640`. Widths are rounded up to the next step of the ladder.

More: [Image delivery, Canonical addresses and redirects](../files/image-delivery.md#canonical-addresses-and-redirects)

### What do I get when I ask for `w=4000`?

A redirect to `w=2560`, the widest step. The picture is still never larger
than the original.

More: [Image delivery, Canonical addresses and redirects](../files/image-delivery.md#canonical-addresses-and-redirects)

### Is there a `dpr` option for high-density screens?

No. Ask for a wider step. For a picture shown 640 pixels wide on a 2x
screen, use `w=1280`, or list the steps in `srcset` and the browser does the
arithmetic.

More: [Image delivery, Options](../files/image-delivery.md#options)

### Can I blur, sharpen, rotate or filter an image by URL?

No. The six options are all there is. An unknown option is refused with
"Invalid image options": there is no `dpr`, no `crop` and no `blur`.

More: [Image delivery, Options](../files/image-delivery.md#options)

### Can I choose which part of the picture a crop keeps?

No. `fit=cover` cuts the picture around its centre. There is no way to
choose another focus point.

More: [Image delivery, Options](../files/image-delivery.md#options)

### Can I crop an image to any shape I like?

Not by URL. Crops come in the shapes the ladder forms, such as 640 by 640,
960 by 640 and 1280 by 960. For any other shape, ask for an `inside` variant
and crop it in CSS with `object-fit: cover`.

More: [Image delivery, A square crop](../files/image-delivery.md#a-square-crop)

### Can I crop or edit an image inside the Talewright app?

No. The app has no image editor. For a cropped copy, use a `fit=cover`
variant of the image's link. To change the picture itself, edit it outside
Talewright and upload it as a new version.

More: [Image delivery, Options](../files/image-delivery.md#options)

### Why is `fit=cover` refused without a height?

A crop needs a height. `fit=cover` with `h=0`, or without `h`, answers `422`
"Invalid image options".

More: [Image delivery, Options](../files/image-delivery.md#options)

### Why is `f=jpg` refused?

The format is spelled `jpeg`, not `jpg`. `f=jpg` answers `422` "Invalid
image options".

More: [Image delivery, Options](../files/image-delivery.md#options)

### Why is `W=320` or `f=WEBP` refused?

Keys and values are lower case. Upper-case spellings are refused.

More: [Image delivery, Options](../files/image-delivery.md#options)

### What happens when I give the same option twice?

The address is refused. An option given twice, an unknown option or an empty
item answers `422` "Invalid image options".

More: [Image delivery, Options](../files/image-delivery.md#options)

### What do I get when I ask for `q=100`?

A redirect to `q=90`, the highest level. Anything above 90 becomes 90.

More: [Image delivery, Options](../files/image-delivery.md#options)

### Does `q` change a PNG variant?

No. PNG output is lossless and has no quality. For `f=png` any `q` is
accepted and the address always spells `q=80`.

More: [Image delivery, Options](../files/image-delivery.md#options)

### What happens with `v=1` or `v=4` in a variant address?

`v=1`, an earlier number, redirects to `v=3`. `v=4`, a number above the
current one, is refused, and so is `v=0`.

More: [Image delivery, Options](../files/image-delivery.md#options)

### Why does `w=0` fail when `h=0` works?

Only `h` may be 0, where it means no limit on height. `q=0`, `w=0` and `v=0`
answer `422` "Invalid image options".

More: [Image delivery, Edge cases](../files/image-delivery.md#edge-cases)

### How many digits can a number in the image options have?

1 to 6 digits.

More: [Image delivery, Options](../files/image-delivery.md#options)

### Which quality level should I pick?

80 is the default. Use 60 for smaller files and 90 for the closest match to
the original.

More: [Image delivery, Options](../files/image-delivery.md#options)

### Can I get a variant narrower than 320 pixels?

Not by asking for it: 320 is the smallest step, and a smaller number is
raised to it. An original narrower than 320 pixels comes out at its own
width.

More: [Image delivery, Options](../files/image-delivery.md#options)

### Are `w` and `h` exact sizes?

No. They are upper bounds, not exact sizes. The picture is never made larger
than the original.

More: [Image delivery, Options](../files/image-delivery.md#options)

### Can I set the background colour for transparent areas?

No. There is no option for it. In JPEG output transparent areas become
white. AVIF, WebP and PNG keep the transparency.

More: [Image delivery, What a variant looks like](../files/image-delivery.md#what-a-variant-looks-like)

## Canonical addresses and redirects

### What is the canonical address of a variant?

The one address that answers bytes: all six options, in the order `v`, `w`,
`h`, `q`, `fit`, `f`, with the values after rounding. For example
`v=3,w=1280,h=0,q=80,fit=inside,f=webp`.

More: [Image delivery, Canonical addresses and redirects](../files/image-delivery.md#canonical-addresses-and-redirects)

### Why did my variant address answer `308`?

It was valid but not the canonical one: an option was missing, out of order
or got rounded, it named an earlier `v`, or it used `f=auto`. The `Location`
header holds the canonical address.

More: [Image delivery, Canonical addresses and redirects](../files/image-delivery.md#canonical-addresses-and-redirects)

### Does a short variant address work in an `<img>` tag?

Yes. Browsers follow the redirect by themselves, so a short address such as
`w=640,f=avif` works in an `<img>`.

More: [Image delivery, Canonical addresses and redirects](../files/image-delivery.md#canonical-addresses-and-redirects)

### How do I avoid the redirect on a variant address?

Write the canonical address. It saves the extra request.

More: [Image delivery, Canonical addresses and redirects](../files/image-delivery.md#canonical-addresses-and-redirects)

### What does the `Location` of a variant redirect hold?

A path on the files host: `/_img/{canonical options}/{the link's path as you
sent it}`.

More: [Image delivery, Canonical addresses and redirects](../files/image-delivery.md#canonical-addresses-and-redirects)

### Is the redirect of a variant address cached?

Yes. On a public link it is cached like any public answer, with the file's
`Cache-Tag`. On a signed link it is `private`, for what is left of the
link's lifetime.

More: [Image delivery, Canonical addresses and redirects](../files/image-delivery.md#canonical-addresses-and-redirects)

### How do I find the canonical address for the options I want?

Request your address once and read the `location` header of the `308`, for
example with `curl -s -o /dev/null -D -`. Store that address to skip the
redirect from then on.

More: [Image delivery, A redirect to the canonical address](../files/image-delivery.md#a-redirect-to-the-canonical-address)

### Where does `w=700,h=500,fit=cover,f=jpeg` redirect to?

To `v=3,w=960,h=640,q=80,fit=cover,f=jpeg`. Width and height are each raised
to the next step, and the missing options get their defaults.

More: [Image delivery, Canonical addresses and redirects](../files/image-delivery.md#canonical-addresses-and-redirects)

### Can a cross-origin `fetch` follow a variant's redirect?

Yes. The `308` redirects of a public link's variants carry the cross-origin
headers too.

More: [Image delivery, Use from other websites](../files/image-delivery.md#use-from-other-websites)

## Formats

### Which image format should I ask for?

`<picture>` with explicit `f=avif` and `f=webp` sources and a JPEG fallback
is the fastest. `f=auto` is the simplest: one address that gives AVIF to
browsers that ask for it and WebP to the rest. Use `f=png` only when you
need lossless output.

More: [Image delivery, Recipes](../files/image-delivery.md#recipes)

### How do I get a WebP version of an image?

Add `f=webp` to the options, or leave `f` out: WebP is the default. For
example `/_img/v=3,w=1280,h=0,q=80,fit=inside,f=webp/p/{slug}/{name}`.

More: [Image delivery, Options](../files/image-delivery.md#options)

### How do I get an AVIF version of an image?

Add `f=avif` to the options, for example
`/_img/v=3,w=1280,h=0,q=80,fit=inside,f=avif/p/{slug}/{name}`. It answers
AVIF to every client, whether it can show it or not.

More: [Image delivery, Options](../files/image-delivery.md#options)

### How do I get a JPEG version of an image?

Add `f=jpeg` to the options. Spell it `jpeg`: `f=jpg` is refused.
Transparent areas become white, because JPEG has no transparency.

More: [Image delivery, Options](../files/image-delivery.md#options)

### How do I get a PNG version of an image?

Add `f=png` to the options. PNG output is lossless and full colour and keeps
transparency. A large photo as PNG can be many times the size of the same
picture as WebP.

More: [Image delivery, What a variant looks like](../files/image-delivery.md#what-a-variant-looks-like)

### What format do I get when I leave `f` out?

WebP. The default is `f=webp`.

More: [Image delivery, Options](../files/image-delivery.md#options)

### Can a variant come out as GIF, SVG, TIFF or HEIC?

No. A variant is AVIF, WebP, JPEG or PNG. Any other value of `f` is refused,
except `auto`, which redirects to AVIF or WebP.

More: [Image delivery, Options](../files/image-delivery.md#options)

### What does `f=auto` do?

It redirects to the `f=avif` address when the browser's `Accept` header
names `image/avif`, and to the `f=webp` address otherwise. It never answers
a picture itself.

More: [Image delivery, `f=auto`](../files/image-delivery.md#fauto)

### How does `f=auto` choose between AVIF and WebP?

By the request's `Accept` header. It picks AVIF when the header names
`image/avif`, in any letter case and not with `q=0`. Wildcards such as
`image/*` or `*/*`, or no `Accept` at all, get WebP.

More: [Image delivery, `f=auto`](../files/image-delivery.md#fauto)

### Why does `f=auto` give `curl` or a script WebP?

They send `Accept: */*`, and a wildcard does not count as asking for AVIF,
because clients that cannot show AVIF send it too. A script's `fetch` gets
AVIF only if you set the `Accept` header to name `image/avif`.

More: [Image delivery, `f=auto`](../files/image-delivery.md#fauto)

### Can `f=auto` ever give JPEG or PNG?

No. It always redirects to `f=avif` or to `f=webp`.

More: [Image delivery, `f=auto`](../files/image-delivery.md#fauto)

### Is `f=auto` still a redirect when every other option is canonical?

Yes. `f=auto` never answers a picture, so even
`v=3,w=320,h=0,q=80,fit=inside,f=auto` answers `308`.

More: [Image delivery, `f=auto`](../files/image-delivery.md#fauto)

### What happens when I ask for `f=avif` from a browser that cannot show AVIF?

AVIF is answered anyway, and the picture does not show. An explicit format
ignores `Accept`. Use `<picture>` or `f=auto` to cover such browsers.

More: [Image delivery, `f=auto`](../files/image-delivery.md#fauto)

### Can a CDN hand an AVIF from `f=auto` to a browser that cannot show it?

No. The `f=auto` redirect says `Vary: accept` and may be kept only by the
browser that asked. A CDN never keeps it. The explicit address it leads to
is kept like any other variant.

More: [Image delivery, `f=auto`](../files/image-delivery.md#fauto)

### What does `f=auto` cost compared with an explicit format?

One extra request per browser per day and per address: the redirect, which
the browser remembers for a day.

More: [Image delivery, One address, the best format: `f=auto`](../files/image-delivery.md#one-address-the-best-format-fauto)

### When is `f=auto` the better choice than `<picture>`?

Where one plain address matters more than the extra request, such as in a
CMS field or an email template that only takes one URL.

More: [Image delivery, One address, the best format: `f=auto`](../files/image-delivery.md#one-address-the-best-format-fauto)

### Why is my PNG variant so much larger than the WebP one?

PNG is lossless and full colour: every colour and the transparency of the
resized picture are kept exactly. A large photo as PNG can be many times the
size of the same picture as WebP.

More: [Image delivery, What a variant looks like](../files/image-delivery.md#what-a-variant-looks-like)

### Which `Content-Type` does a variant answer with?

`image/avif`, `image/webp`, `image/jpeg` or `image/png`, as named by `f`,
whatever the name at the end of the address says.

More: [Image delivery, What a variant looks like](../files/image-delivery.md#what-a-variant-looks-like)

## Which images can be resized

### Can I resize a HEIC photo?

Yes. HEIC and HEIF originals can be resized. The variant is a WebP, AVIF,
JPEG or PNG that every browser shows.

More: [Image delivery, Which files can be resized](../files/image-delivery.md#which-files-can-be-resized)

### Does a variant of a HEIC photo lose sharpness?

It is made from the original photo, at full sharpness up to 2,560 pixels.

More: [Image delivery, Which files can be resized](../files/image-delivery.md#which-files-can-be-resized)

### Does resizing work with animated GIFs?

It gives a still. A variant of an animated image is a still picture of its
first frame.

More: [Image delivery, Which files can be resized](../files/image-delivery.md#which-files-can-be-resized)

### How do I show an animated GIF as an animation?

Use the original's link. It serves the animation as it was uploaded.
Variants are stills.

More: [Image delivery, Which files can be resized](../files/image-delivery.md#which-files-can-be-resized)

### Can I resize an SVG?

Yes, if it is static SVG. The SVG is turned into pixels and answered as
AVIF, WebP, JPEG or PNG. Styles that only set how shapes and text look are
applied.

More: [Image delivery, Which files can be resized](../files/image-delivery.md#which-files-can-be-resized)

### Which SVG features stop an SVG from being resized?

A `DOCTYPE`, processing instructions, `<script>` elements, event attributes
such as `onload`, embedded images, `foreignObject`, references to anything
outside the file, and styles that do more than set presentation.

More: [Image delivery, Which files can be resized](../files/image-delivery.md#which-files-can-be-resized)

### Can I resize an SVG that has a `<style>` block or `style` attributes?

Yes, when its styles only set presentation: fills, strokes, opacity, fonts,
transforms and the like, with any selectors. This covers the class rules and
inline styles that design tools write when they export. The styles are
applied to the picture.

More: [Image delivery, Styles in an SVG](../files/image-delivery.md#styles-in-an-svg)

### Which CSS properties can a resizable SVG use?

Painting (`fill`, `stroke` and their parts, `opacity`, `color`,
`stop-color`, `mix-blend-mode`), showing and clipping (`display`,
`visibility`, `clip-path`, `mask`), `transform`, the font and text
properties, rendering hints and custom properties. The full list is on the
feature page. Any other property refuses the SVG.

More: [Image delivery, Styles in an SVG](../files/image-delivery.md#styles-in-an-svg)

### Which CSS stops an SVG from being resized?

- `@import`, `@font-face`, `@keyframes` and every at-rule but `@media`.
- `url()` to anything but a part of the same file, written `url(#id)`.
- Any function but the colour, transform and `var()` functions, for example
  `calc()` or `image-set()`.
- A property outside the list, for example `filter`, `animation` or
  `background`.
- A backslash or a CSS comment anywhere in a style.

More: [Image delivery, Styles in an SVG](../files/image-delivery.md#styles-in-an-svg)

### Why is my SVG refused because of a CSS comment?

A style is checked before the SVG is drawn, and a comment or a backslash
could hide what the style really says. So neither is read: an SVG with
`/* ... */` or `\` in a style answers `422`. Remove the comment and replace
the file.

More: [Image delivery, Styles in an SVG](../files/image-delivery.md#styles-in-an-svg)

### Are an SVG's `@media` rules and CSS variables applied in a variant?

No. Both are accepted, so the SVG is resized, but the resizer does not apply
rules inside `@media` or values that use `var()`. The shape is drawn as if
they were not there.

More: [Image delivery, Styles in an SVG](../files/image-delivery.md#styles-in-an-svg)

### Can a resizable SVG be animated with CSS?

No. `@keyframes` and the `animation` properties refuse the SVG. A variant is
a still picture in any case.

More: [Image delivery, Styles in an SVG](../files/image-delivery.md#styles-in-an-svg)

### Which SVG elements can a resizable SVG use?

`svg`, `g`, `defs`, `symbol`, `use`, `path`, `rect`, `circle`, `ellipse`,
`line`, `polyline`, `polygon`, `text`, `tspan`, `title`, `desc`,
`linearGradient`, `radialGradient`, `stop`, `clipPath`, `mask`, `pattern`
and `style`.

More: [Image delivery, Which files can be resized](../files/image-delivery.md#which-files-can-be-resized)

### Can an SVG that references an external image or font be resized?

No. A resizable SVG may reference only parts of the same file, such as
`href="#id"` and `url(#id)`. Its variants answer `422`. Its original link is
not affected.

More: [Image delivery, Which files can be resized](../files/image-delivery.md#which-files-can-be-resized)

### My SVG cannot be resized. Does its public link still work?

Yes. Only its variants answer `422` "The image source cannot be decoded".
The original link serves the SVG as it was uploaded.

More: [Image delivery, Which files can be resized](../files/image-delivery.md#which-files-can-be-resized)

### Can I get an image variant of a PDF, a video or a Photoshop file?

No. Their variant addresses answer `404`. People and credentials with access
can get a picture of them through the `thumb` and `preview` signed links.

More: [Image delivery, Which files can be resized](../files/image-delivery.md#which-files-can-be-resized)

### Can I resize a raw photo, an ICO or a font file?

No. A variant address of any file that is not JPEG, PNG, WebP, AVIF, GIF,
SVG, HEIC or HEIF answers `404 NOT_FOUND`.

More: [Image delivery, Which files can be resized](../files/image-delivery.md#which-files-can-be-resized)

### Can I resize or transcode a video by URL?

No. Variants are for images. A variant address of a video answers `404`,
and so does one built on a signed link to a `playback` rendition.

More: [Image delivery, Which files can be resized](../files/image-delivery.md#which-files-can-be-resized)

### Is the type that decides whether a file can be resized taken from its name?

No. It is the file's real type, found from its bytes at upload, not its
name.

More: [Image delivery, Which files can be resized](../files/image-delivery.md#which-files-can-be-resized)

### Can I resize a `thumb` or `preview` signed link again?

Yes. A variant of a signed link resizes whatever that link serves. A variant
of a link to a `preview` rendition is the 1,600-pixel WebP preview, resized
again.

More: [Image delivery, Which files can be resized](../files/image-delivery.md#which-files-can-be-resized)

### Can WebP and AVIF originals be resized and converted?

Yes. JPEG, PNG, WebP, AVIF, GIF, SVG, HEIC and HEIF originals all have
variants, in any of the four output formats.

More: [Image delivery, Which files can be resized](../files/image-delivery.md#which-files-can-be-resized)

### Why does a variant address answer `404` while the original link works?

The file is not one of the eight image types that can be resized. Check the
`Content-Type` of the original.

More: [Image delivery, Checks, in order](../files/image-delivery.md#checks-in-order)

## What a variant looks like

### Why did my image not get bigger when I asked for a larger width?

A variant is scaled down, never up. An original 612 pixels wide asked for at
`w=640` comes out 612 pixels wide.

More: [Image delivery, What a variant looks like](../files/image-delivery.md#what-a-variant-looks-like)

### How do I know the real pixel size of a variant?

Read `X-Image-Width` and `X-Image-Height` on the answer. They say what you
got.

More: [Image delivery, What a variant looks like](../files/image-delivery.md#what-a-variant-looks-like)

### Are the proportions of my image kept when it is resized?

Yes, with `fit=inside`. An original of 1,200 by 800 at `w=320` comes out 320
by 213.

More: [Image delivery, What a variant looks like](../files/image-delivery.md#what-a-variant-looks-like)

### Do I get exactly the size I asked for with `fit=cover`?

Yes, when the original is at least as large as the box. An original of 800
by 1,200 at `w=320,h=320` comes out 320 by 320.

More: [Image delivery, What a variant looks like](../files/image-delivery.md#what-a-variant-looks-like)

### Is a photo taken sideways turned upright in a variant?

Yes. A photo that says in its camera data that it was taken sideways is
turned upright before resizing.

More: [Image delivery, What a variant looks like](../files/image-delivery.md#what-a-variant-looks-like)

### Do `w` and `h` apply to a rotated photo before or after it is turned upright?

After. Width and height are those of the upright picture.

More: [Image delivery, What a variant looks like](../files/image-delivery.md#what-a-variant-looks-like)

### Does a variant keep the photo's EXIF and camera data?

No. A variant is a newly encoded picture. It carries no EXIF, so no
location, no camera model and no capture date. Only the original's own link
serves that.

More: [Image delivery, What a variant looks like](../files/image-delivery.md#what-a-variant-looks-like)

### Is transparency kept when an image is resized?

Yes, in AVIF, WebP and PNG. JPEG has no transparency.

More: [Image delivery, What a variant looks like](../files/image-delivery.md#what-a-variant-looks-like)

### What happens to a transparent PNG served as JPEG?

Transparent areas become white.

More: [Image delivery, What a variant looks like](../files/image-delivery.md#what-a-variant-looks-like)

## Variant answers

### Which headers does a variant answer carry?

`Content-Type`, `Content-Length`, `ETag`, `Cache-Control`, `X-Image-Width`,
`X-Image-Height`, `X-Image-Cache` and `X-Content-Type-Options`. A variant of
a public link adds `Cache-Tag` and the cross-origin headers.

More: [Image delivery, What a variant answer carries](../files/image-delivery.md#what-a-variant-answer-carries)

### What does `X-Image-Cache: miss` or `hit` mean?

`miss` means the variant was rendered for this request. `hit` means it
already existed. The picture is the same either way.

More: [Image delivery, What a variant answer carries](../files/image-delivery.md#what-a-variant-answer-carries)

### Is the first request for a new variant slower?

Yes. Rendering a new variant takes a moment. A variant that already exists
is answered without waiting for a turn.

More: [Image delivery, When the resizer is busy](../files/image-delivery.md#when-the-resizer-is-busy)

### Does a variant download or show when I open its address?

It shows in the browser. A variant has no `Content-Disposition` and no
`Content-Security-Policy`: it is a picture to show.

More: [Image delivery, What a variant answer carries](../files/image-delivery.md#what-a-variant-answer-carries)

### Can I send `HEAD` to a variant address?

Yes. `HEAD` answers the same headers without the picture.

More: [Image delivery, What a variant answer carries](../files/image-delivery.md#what-a-variant-answer-carries)

### Do variants answer `304 Not Modified`?

Yes, when `If-None-Match` names the variant's `ETag`, also in the weak form
and in a list. This works on public and on signed links.

More: [Image delivery, What a variant answer carries](../files/image-delivery.md#what-a-variant-answer-carries)

### Is a variant's `ETag` the same as the original's?

No. It is the SHA-256 of the variant's own bytes.

More: [Image delivery, What a variant answer carries](../files/image-delivery.md#what-a-variant-answer-carries)

### What happens when many visitors ask for the same new variant at once?

It is rendered once and all of them get it. One answer says `miss`, the
others `hit`.

More: [Image delivery, What a variant answer carries](../files/image-delivery.md#what-a-variant-answer-carries)

### How are variants of a public link cached?

Like the link itself: `public, max-age=60, s-maxage=31536000`, with the
file's `Cache-Tag`. A variant of a signed link is `private` for the rest of
the link's lifetime.

More: [Image delivery, What a variant answer carries](../files/image-delivery.md#what-a-variant-answer-carries)

## Limits and refusals

### In what order is a request for a variant checked?

1. A query string: `422`, "Image addresses have no query".
2. Not a file link's path after the options: `422`, "Source must be a file
   delivery path".
3. The link does not work: `403` for a signed link, `404` for a public one.
4. Not a type that can be resized: `404`.
5. Invalid options: `422`, "Invalid image options".
6. Valid but not canonical options: `308`.
7. Then the limits on the original and on the variant, and the render time.

The first check that fails decides the answer.

More: [Image delivery, Checks, in order](../files/image-delivery.md#checks-in-order)

### Why do nonsense options on an unknown public link answer `404` and not `422`?

The link is checked before the options. An unknown or restricted public link
answers `404` whatever options are in front of it.

More: [Image delivery, Checks, in order](../files/image-delivery.md#checks-in-order)

### Why does a very tall picture fail at full width and work at a smaller one?

The variant would pass 24 million pixels. With widths capped at 2,560
pixels, that happens only for pictures more than 9,375 pixels high at full
width. A panorama of 3,000 by 14,000 pixels fails at `w=2560` and works at
`w=1280`.

More: [Image delivery, Checks, in order](../files/image-delivery.md#checks-in-order)

### Can `fit=cover` run into the limit on the size of a variant?

Not the pixel limit. `fit=cover` never reaches 24 million pixels, because
its height is at most 2,560 too.

More: [Image delivery, Checks, in order](../files/image-delivery.md#checks-in-order)

### Can a very large picture fail as PNG and work as WebP?

Yes. A lossless PNG can pass the 16 MiB limit of a variant and answer "The
resulting image is too large". Use WebP or a smaller width.

More: [Image delivery, Edge cases](../files/image-delivery.md#edge-cases)

### Does the public link of an original over 64 MiB still work?

Yes. Only its variants are refused, with "Image source exceeds 64 MiB". The
original's own link serves it.

More: [Image delivery, Edge cases](../files/image-delivery.md#edge-cases)

### Can a damaged image file be resized?

No. Its variants answer `422` "The image source cannot be decoded". The
original link is not affected. Replace the file to get variants.

More: [Image delivery, Checks, in order](../files/image-delivery.md#checks-in-order)

### Does a `503` on a variant mean something is wrong with my file?

No. It is a temporary failure of the resizer. Nothing about the file or the
link changed, and the same address works as soon as there is room.

More: [Image delivery, When the resizer is busy](../files/image-delivery.md#when-the-resizer-is-busy)

### Do original files keep working while the resizer is busy or down?

Yes. A public link and a signed link keep serving the stored bytes.

More: [Image delivery, When the resizer is busy](../files/image-delivery.md#when-the-resizer-is-busy)

### Why do some variants answer `503` when I request many new ones at once?

Only so many are rendered at once. A request for a new variant waits up to 5
seconds for its turn. If its turn does not come, the answer is `503` with a
`Retry-After` header. Asking again works.

More: [Image delivery, When the resizer is busy](../files/image-delivery.md#when-the-resizer-is-busy)

### Is a `503` from the resizer cached?

No. The `503` is never cached. The next request is tried afresh.

More: [Image delivery, When the resizer is busy](../files/image-delivery.md#when-the-resizer-is-busy)

### Does a browser retry an `<img>` whose variant failed?

No. A browser does not retry an `<img>` by itself.

More: [Image delivery, When the resizer is busy](../files/image-delivery.md#when-the-resizer-is-busy)

### How do I keep my page from showing a broken image when a variant fails?

Fall back to the original in the image's `onerror`, or to a variant that is
known to exist.

More: [Image delivery, When the resizer is busy](../files/image-delivery.md#when-the-resizer-is-busy)

### What do I do when a render keeps timing out?

Ask for a smaller width. A render that runs out of its 15 seconds is a
temporary failure, and the same picture can pass when the resizer is less
busy.

More: [Image delivery, When the resizer is busy](../files/image-delivery.md#when-the-resizer-is-busy)

### Do the limits on originals apply to a variant that already exists?

No. A variant that already exists skips the checks on the original's size,
the variant's size and the render time.

More: [Image delivery, Checks, in order](../files/image-delivery.md#checks-in-order)

### Why does a variant of a gallery or ZIP address answer `422`?

What follows the options must be a signed link's or a public link's path. A
gallery address and a ZIP address cannot be resized: "Source must be a file
delivery path".

More: [Image delivery, Checks, in order](../files/image-delivery.md#checks-in-order)

### What does a variant of an expired signed link answer?

`403 FORBIDDEN`. A variant of a signed link stops when the link stops.

More: [Image delivery, The address](../files/image-delivery.md#the-address)

## Using images and fonts on another website

### Can I use a public link as the source of an image on my website?

Yes. That is what it is for. Public links and their variants can be used
from any website: in an `<img>`, a `<picture>`, a stylesheet's `@font-face`
or a script's `fetch`.

More: [Image delivery, Use from other websites](../files/image-delivery.md#use-from-other-websites)

### Is hotlinking a public file from another site allowed?

Yes. A public link and every variant of it can be read from any website.

More: [Image delivery, Use from other websites](../files/image-delivery.md#use-from-other-websites)

### Can I limit which websites may embed my public files?

No. The answer is the same whoever asks. The cross-origin headers are the
same whether or not the request names an `Origin`, and they allow every
origin.

More: [Image delivery, Use from other websites](../files/image-delivery.md#use-from-other-websites)

### Which CORS headers does a public link send?

`Access-Control-Allow-Origin: *`,
`Access-Control-Expose-Headers: accept-ranges, content-disposition, content-range, etag`
and `Cross-Origin-Resource-Policy: cross-origin`, on every answer of a
public link and its variants.

More: [Image delivery, Use from other websites](../files/image-delivery.md#use-from-other-websites)

### Can a script on another site `fetch` a public file?

Yes. No `credentials` and no `mode` are needed. The script can read the
bytes and, on a failure, the error body.

More: [Image delivery, Reading a public file from a script on another site](../files/image-delivery.md#reading-a-public-file-from-a-script-on-another-site)

### Why does my `fetch` of a public link fail with `credentials: "include"`?

`*` never allows credentials. No answer carries
`Access-Control-Allow-Credentials`, so the browser refuses the answer. Leave
credentials out.

More: [Image delivery, Use from other websites](../files/image-delivery.md#use-from-other-websites)

### Which response headers can a script on another site read?

`ETag`, `Content-Range`, `Accept-Ranges` and `Content-Disposition`, next to
the ones every browser exposes, such as `Content-Type` and `Content-Length`.

More: [Image delivery, Use from other websites](../files/image-delivery.md#use-from-other-websites)

### Can a script on another site read `X-Image-Width` and `X-Image-Height`?

No. `X-Image-Width`, `X-Image-Height`, `X-Image-Cache` and `Cache-Tag` are
not readable by a script on another site. Read a picture's size from the
picture itself.

More: [Image delivery, Use from other websites](../files/image-delivery.md#use-from-other-websites)

### What does a preflight (`OPTIONS`) on a public link answer?

`204` with the cross-origin headers, `Access-Control-Allow-Methods: GET,
HEAD`, `Access-Control-Allow-Headers: *` and `Access-Control-Max-Age:
86400`.

More: [Image delivery, Use from other websites](../files/image-delivery.md#use-from-other-websites)

### Does a preflight tell whether a public link exists?

No. The preflight is answered without looking the file up. It answers `204`
for any slug, known or not. The request that follows gets the real answer.

More: [Image delivery, Use from other websites](../files/image-delivery.md#use-from-other-websites)

### Can I draw a public image on a `<canvas>` and read the canvas back?

Yes. Load it with `<img crossorigin="anonymous" src="...">`.

More: [Image delivery, Reading a public file from a script on another site](../files/image-delivery.md#reading-a-public-file-from-a-script-on-another-site)

### Can a script on another website read my private files?

No. Only public links and their variants are readable from other websites.
Signed links carry no cross-origin headers, so a browser blocks a script on
another site from reading them. The app and the API are not readable from
other websites either.

More: [Image delivery, Use from other websites](../files/image-delivery.md#use-from-other-websites)

### Can a script on another site read why a public link failed?

Yes. Every refusal on a public address carries the cross-origin headers too,
the `404` of an unknown link included.

More: [Image delivery, Use from other websites](../files/image-delivery.md#use-from-other-websites)

### Can I load a web font from Talewright?

Yes. Upload the font file, give it a status that allows public use, make it
public and use its public link in `@font-face`.

More: [Image delivery, A web font from a public link](../files/image-delivery.md#a-web-font-from-a-public-link)

### How do I write the `@font-face` rule for a font served by Talewright?

```css
@font-face {
  font-family: "Brand Sans";
  src: url("https://files.talewrightusercontent.com/p/8d41c06be2a94f37b5d09e6a1c7f3b22/brand-sans.woff2")
    format("woff2");
  font-display: swap;
}
```

More: [Image delivery, A web font from a public link](../files/image-delivery.md#a-web-font-from-a-public-link)

### Why does a font preload need `crossorigin`?

Without it the browser fetches the font twice. Browsers load fonts from
another site only when that site allows it, and the public link does, for
every origin.

More: [Image delivery, A web font from a public link](../files/image-delivery.md#a-web-font-from-a-public-link)

### What happens on my site when I replace a font file with a new version?

The same address serves the new version. Browsers pick it up within a
minute.

More: [Image delivery, A web font from a public link](../files/image-delivery.md#a-web-font-from-a-public-link)

### Can I use a public link as a CSS background image?

Yes. A public link can be used in CSS, and a CSS background on another site
works.

More: [Image delivery, Use from other websites](../files/image-delivery.md#use-from-other-websites)

### Can I use a public video link in a `<video>` tag?

Yes. A public link can be used in a `<video>` on any site.

More: [Image delivery, Questions and answers](../files/image-delivery.md#questions-and-answers)

### How long may a browser remember the preflight of a public link?

One day: `Access-Control-Max-Age: 86400`.

More: [Image delivery, Limits](../files/image-delivery.md#limits)

## Responsive images

### How do I make a responsive image with `srcset`?

List one variant address per width step with its `w` descriptor, and add
`sizes`:

```html
<img
  src="https://files.talewrightusercontent.com/_img/v=3,w=1280,h=0,q=80,fit=inside,f=webp/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg"
  srcset="
    https://files.talewrightusercontent.com/_img/v=3,w=640,h=0,q=80,fit=inside,f=webp/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg 640w,
    https://files.talewrightusercontent.com/_img/v=3,w=1280,h=0,q=80,fit=inside,f=webp/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg 1280w"
  sizes="(min-width: 1024px) 50vw, 100vw"
  width="2400" height="1600" alt="The harbour at dawn">
```

More: [Image delivery, A responsive image](../files/image-delivery.md#a-responsive-image)

### Which widths should I list in `srcset`?

The steps of the ladder: 320, 640, 960, 1280, 1600, 2048 and 2560. List them
only up to the original's width.

More: [Image delivery, A responsive image](../files/image-delivery.md#a-responsive-image)

### Why should I leave out `srcset` steps above the original's width?

A step above the original's width answers the original's size, and its `w`
descriptor would then promise more pixels than the picture has.

More: [Image delivery, A responsive image](../files/image-delivery.md#a-responsive-image)

### How do I write `srcset` when the variant addresses contain commas?

Keep each candidate as the address, a space, the width descriptor, then a
comma and a line break or space.

More: [Image delivery, A responsive image](../files/image-delivery.md#a-responsive-image)

### How do I serve AVIF with WebP and JPEG fallbacks?

Use `<picture>`: a `<source type="image/avif">` with `f=avif` addresses, a
`<source type="image/webp">` with `f=webp` addresses, and an `<img>` with an
`f=jpeg` address. The browser takes the first source whose type it can show.

More: [Image delivery, AVIF with a WebP and a JPEG fallback](../files/image-delivery.md#avif-with-a-webp-and-a-jpeg-fallback)

### How do I keep the page from jumping while an image loads?

Set `width` and `height` on the `<img>` to the original's proportions.

More: [Image delivery, A responsive image](../files/image-delivery.md#a-responsive-image)

### How do I make a square thumbnail?

Use `fit=cover` with equal width and height, for example
`v=3,w=320,h=320,q=80,fit=cover,f=webp`. It fills 320 by 320 and cuts off
the rest around the centre.

More: [Image delivery, A square crop](../files/image-delivery.md#a-square-crop)

### How do I find out the original's width and height?

Read the file through the API. Its `currentVersion.media` holds the
original's `width` and `height`.

More: [Image delivery, Building a variant address from a public link](../files/image-delivery.md#building-a-variant-address-from-a-public-link)

## Performance

### What is the fastest way to serve images from Talewright?

`<picture>` with explicit, canonical `f=avif` and `f=webp` addresses and a
JPEG fallback. It has no redirects and does not depend on `Accept`, and
every answer can be kept by a CDN.

More: [Image delivery, AVIF with a WebP and a JPEG fallback](../files/image-delivery.md#avif-with-a-webp-and-a-jpeg-fallback)

### How do I make the images on my page smaller in bytes?

Ask for a narrower step with `w`, use `q=60`, and serve AVIF or WebP rather
than PNG. A large photo as PNG can be many times the size of the same
picture as WebP.

More: [Image delivery, Options](../files/image-delivery.md#options)

### Should I link the original or a variant on a web page?

Both work. The original's link serves the file byte for byte as it was
uploaded. A variant is the same picture, smaller, in a format you choose.

More: [Image delivery, Summary](../files/image-delivery.md#summary)

### Does asking for many different sizes slow things down?

Each new variant is rendered once, when it is first asked for. After that it
already exists and is answered without waiting. The rounding keeps the set
of variants of one image small and fixed.

More: [Image delivery, Canonical addresses and redirects](../files/image-delivery.md#canonical-addresses-and-redirects)

### How often does a returning visitor's browser ask for a public image again?

After 60 seconds it asks again with `If-None-Match` and usually gets a short
`304` without the picture.

More: [Image delivery, Caching](../files/image-delivery.md#caching)

## Agents and images

### How does an agent get an image small enough to look at?

Ask for a signed link to the `original` and put
`/_img/v=3,w=640,h=0,q=80,fit=inside,f=webp` in front of its path, or use
the `thumb` or `preview` signed link directly.

More: [Image delivery, Worked example: a signed link, then a variant of it](../files/image-delivery.md#worked-example-a-signed-link-then-a-variant-of-it)

### How does an agent write a variant address that does not redirect?

In canonical form:
`v=3,w={step},h={step or 0},q={60|80|90},fit={inside|cover},f={format}`.

More: [Image delivery, Building a variant address from a public link](../files/image-delivery.md#building-a-variant-address-from-a-public-link)

### What should an agent do when a file's `publicURL` is `null`?

The file is not public. An owner or admin makes it public in the app. Until
then the agent can use a signed link.

More: [Image delivery, Building a variant address from a public link](../files/image-delivery.md#building-a-variant-address-from-a-public-link)
