# Image delivery

## Summary

Files are shown and embedded from one separate host, the files host:
`https://files.talewrightusercontent.com`. The app and the API live on
`https://app.usetalewright.com` and never serve a file inline. The API's own
download operation answers a file as an attachment; see
[Downloading](downloading.md).

The files host answers two kinds of links:

- A **signed link** works for 10 minutes for whoever holds it. The app and
  the API hand these out to people and credentials that may read the file.
- A **public link** works for anyone, for as long as the file is public. It
  always serves the file's current version.

On top of both, the files host resizes and converts images on request. You
put options in front of a link, such as a width and a format, and get an
**image variant**: the same picture, smaller, as AVIF, WebP, JPEG or PNG.
Nothing has to be prepared in advance.

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`.

This page covers how files are answered (headers, caching, conditional
requests, ranges), image variants in full, use from other websites and
ready-made recipes. Who may make a file public, and what starts and stops a
public link, is in [Sharing and public links](sharing.md). How a person
downloads files is in [Downloading](downloading.md).

## Who can do what

| Action | Who | Session | Credential (scope) |
| --- | --- | --- | --- |
| Get a signed link for a version of a workspace file | Everyone who can open the workspace | Yes | Yes (`files:read`) |
| Get a signed link for a version of an organization folder file | Every member of the organization | Yes | Yes (`files:read`) |
| Open a signed link, or a variant of it | Anyone who holds the link, until it expires | Not needed | Not needed |
| Open a public link, or a variant of it | Anyone | Not needed | Not needed |
| Read a public link or its variant from a page on another website | Anyone | Not needed | Not needed |
| Make a file public or restricted | Owners and admins, in a browser | Yes | No |

- The files host never asks who you are. It has no sign-in, reads no cookie
  and sets none. The link is the whole permission.
- `files:write` includes `files:read`, so a credential with either scope
  gets signed links. See
  [Credentials and scopes](../agents/credentials.md#scopes).
- Making a file public is described in
  [Sharing and public links](sharing.md#the-strict-rule).

## How it works

### The files host

- Every link to a file leads to the files host: signed links, public links
  and their variants. It is a different host from the app on purpose:
  nothing a file contains can act as the app.
- The files host ignores cookies. A request with a cookie gets the same
  answer as one without, and no answer sets a cookie.
- It answers `GET` and `HEAD`. Any other method on one of its addresses
  answers `405 METHOD_NOT_ALLOWED`. The one exception is `OPTIONS` on a
  public link or its variant, described under
  [Use from other websites](#use-from-other-websites).
- It has five kinds of addresses:

| Address | What it is |
| --- | --- |
| `/s/{token}/{name}` | A signed link to one version of a file. |
| `/p/{slug}/{name}` | The public link of a file. |
| `/_img/{options}/s/{token}/{name}` and `/_img/{options}/p/{slug}/{name}` | An image variant of a signed or a public link. |
| `/p/f/{slug}/{name}` | The gallery page of a public folder. See [Sharing and public links](sharing.md#public-folders). |
| `/z/{token}/{name}.zip` | A ZIP download. See [Downloading](downloading.md). |

- `{name}` 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.
- In the links Talewright hands out, the name is percent-encoded. A file
  named `a/b.jpg` has links that end in `a%2Fb.jpg`.
- A refusal has the same JSON body as an API error, with a `requestID`. See
  [The error envelope](../reference/errors.md#the-error-envelope).
- Every refusal (any `4xx` or `5xx` answer) carries
  `Cache-Control: no-store`. A browser or a CDN never keeps a refusal, so a
  link that starts working answers at once.

### Signed links

- A signed link names one version of one file and one variant of it:
  - `original`: the version's own bytes,
  - `thumb`: a WebP that fits 320 pixels,
  - `preview`: a WebP that fits 1,600 pixels,
  - `playback`: a video's MP4 rendition.
- It works for 10 minutes from the moment it is made. The answer that hands
  it out says when it stops, in `expiresAt`.
- It works for whoever holds it. No sign-in, no cookie and no API key is
  checked. Treat a signed link like the file itself: do not publish it.
- It keeps naming the same version. If the file gets a new version, the
  link still serves the version it was made for.
- It stops working before the 10 minutes are over when:
  - the file is moved to the trash,
  - the file is restored from the trash (links from before the trash stay
    stopped; ask for a new one),
  - the file is deleted for good,
  - its workspace or its organization is deleted.
- A signed link that is altered, expired or stopped answers
  `403 FORBIDDEN`. The answer does not say which of the three it was.
- An answer to a signed link carries
  `Cache-Control: private, max-age={seconds}`, where the seconds are what is
  left until the link stops. A browser may reuse the answer until the
  link expires. A shared cache or a CDN may not keep it.
- Signed links are for people and programs that may read the file. They are
  not readable by scripts of other websites. See
  [Use from other websites](#use-from-other-websites).
- How to ask for one is under [For agents](#for-agents). The API also puts
  ready-made signed links on a file: `thumbnailURL` and `previewURL`, each
  `null` until the rendition is ready or while the file is in the trash.
  These two work for 10 to 15 minutes: they stop on a five-minute mark of
  the clock, so every read within the same five minutes carries the same
  link and a browser shows the image it already has.

### Public links

- A file that is public has a public link of the form
  `https://files.talewrightusercontent.com/p/{slug}/{name}`. The slug is 32
  hexadecimal digits.
- The link is permanent for the file and always serves its current version.
  The rules for when a file is public, and what stops and brings back its
  link, are in [Sharing and public links](sharing.md#the-public-link).
- The link serves the stored original, byte for byte. Nothing is removed or
  re-encoded, so a photo keeps its camera data. See
  [Location data](sharing.md#location-data).
- A link whose file is not public right now answers `404 NOT_FOUND`. A
  restricted file, a trashed file, a file whose status does not allow public
  use and a slug that never existed all get the same answer. Nobody can
  tell them apart from outside.
- Every request is checked against the file's state at that moment. A file
  that stops being public stops answering at once.

### What an answer carries

An answer with stored bytes, from a signed link or a public link, carries
these headers:

| Header | Value |
| --- | --- |
| `Content-Type` | The file's real type, found from its bytes when it was uploaded. Not the type the uploader claimed. |
| `Content-Length` | The number of bytes in this answer. |
| `Content-Disposition` | `inline` or `attachment`, with the file's current name: `inline; filename="hero.jpg"; filename*=UTF-8''hero.jpg`. |
| `ETag` | 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. |
| `Accept-Ranges` | `bytes` |
| `Cache-Control` | `private, max-age={seconds}` on a signed link. `public, max-age=60, s-maxage=31536000` on a public link. |
| `Cache-Tag` | `tw-file-{fileID}`, on a public link only. |
| `X-Content-Type-Options` | `nosniff` |
| `Content-Security-Policy` | `sandbox; default-src 'none'; style-src 'unsafe-inline'` |
| `x-request-id` | The ID of the request. |

- In `filename="..."`, characters outside printable ASCII, `"` and `\` are
  replaced by `_`. `filename*` carries the exact name.
- The name in `Content-Disposition` is the file's current name, whatever
  name the address ends in.
- A `thumb`, `preview` or `playback` signed link names its answer after the
  file with the rendition's extension: the thumbnail of `hero.png` is
  `hero.webp`.
- `nosniff` and the sandboxing policy mean 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.
- Answers on a public link also carry the headers under
  [Use from other websites](#use-from-other-websites).

### Inline or download

Whether a link opens in the browser or downloads depends on the file's type:

| Opens in the browser (`inline`) | Downloads (`attachment`) |
| --- | --- |
| JPEG, PNG, GIF, WebP, AVIF, ICO | SVG |
| MP4, WebM | HEIC and HEIF |
| PDF | Photoshop (PSD, PSB) and raw photos |
| Every `thumb`, `preview` and `playback` rendition | Illustrator, EPS, InDesign, Figma |
| | Fonts (WOFF, WOFF2, TTF, OTF) |
| | QuickTime (`.mov`) |
| | CSV, DOCX, XLSX, Markdown, plain text |

- This is about a link opened directly, for example pasted into the address
  bar. A page that uses the link as a resource is not affected: a font
  loads through `@font-face`, and an SVG shows in an `<img>`.
- The rule is the same for signed links and public links.
- A HEIC or HEIF original downloads, but its image variants show in every
  browser. See [Image variants](#image-variants).

### Conditional requests

- 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`.
- The `304` carries the `ETag` and the same `Cache-Control`. On a public
  link it also carries the `Cache-Tag`.
- `If-None-Match` may list several tags. The weak form a CDN may turn a tag
  into (`W/"sha256:..."`) matches too, and so does `*`.
- When the file gets a new version, the `ETag` changes. A request with the
  old tag then gets the new bytes with `200`.
- A signed link names one version, whose bytes never change. Its `ETag`
  matches for as long as the link works. A link that no longer works
  answers `403` whatever the request sends.
- Image variants answer `304` on both kinds of links. See
  [What a variant answer carries](#what-a-variant-answer-carries).

### Ranges

- Signed links and public links serve one byte range per request. The
  answer is `206 Partial Content` with
  `Content-Range: bytes {start}-{end}/{size}`.
- Three forms are understood: `bytes=0-99` (from, to, both included),
  `bytes=100-` (from there to the end) and `bytes=-500` (the last 500
  bytes).
- An end past the last byte is cut to the last byte.
- A range that starts past the end, or `bytes=-0`, answers
  `416 RANGE_NOT_SATISFIABLE` with `Content-Range: bytes */{size}` and
  `details.sizeBytes`.
- A `Range` header the files host does not understand is ignored and the
  whole content is sent with `200`: several ranges in one header
  (`bytes=0-9,20-29`), another unit than `bytes`, a start after the end, or
  anything malformed.
- `If-Range` makes a range conditional. The range is served only when
  `If-Range` is exactly the current `ETag`, quotes included. With any other
  value the whole current content is sent with `200`: an earlier version's
  tag, a weak tag (`W/...`) or a date. No `Last-Modified` is sent, so a date
  never matches.
- This is what makes resuming a download safe on a public link. If the file
  got a new version between two parts, the client gets the whole new file
  instead of a mix of two versions.
- Image variants ignore `Range` and are always sent whole.

### Caching

- **Signed links** are private. `Cache-Control: private, max-age={seconds}`
  lets the browser reuse the answer until the link expires and forbids
  shared caches from keeping it.
- **Public links** and their variants carry
  `Cache-Control: public, max-age=60, s-maxage=31536000`.
  - `max-age=60`: a browser reuses its copy for 60 seconds. After that it
    asks again with `If-None-Match` and usually gets a short `304`.
  - `s-maxage=31536000`: a CDN may keep the answer for up to a year.
  - There is no `immutable`: the same address serves a new version when the
    file is replaced.
- Public answers carry `Cache-Tag: tw-file-{fileID}`. Originals, `206` and
  `304` answers, variants and their redirects of one file all carry the
  same tag.
- The copies a CDN keeps of a file are dropped when what its link serves
  changes:
  - the file gets a new current version,
  - the file or a folder above it is made public or restricted,
  - a status change starts or stops its link,
  - the file or a folder above it is moved so that its link starts or
    stops,
  - the file is moved to the trash, restored or deleted for good,
  - its workspace or its organization is deleted.
- The files host itself never serves a stale answer. Every request is
  checked against the current state, also for variants that were rendered
  earlier.
- After a change, a browser may still show its own copy for up to 60
  seconds. A reload that revalidates gets the current state.
- Refusals are never kept: every one carries `Cache-Control: no-store`.
- No public answer carries `Vary`. The answer is the same whoever asks and
  from wherever. The one exception is the redirect of `f=auto`, below.
- A gallery page carries `Cache-Control: public, max-age=60, s-maxage=60`
  and `Cache-Tag: tw-folder-{folderID}`, so a rename inside shows within a
  minute.

### Image variants

A variant is a resized and re-encoded copy of an image, made when it is
first asked for.

#### The address

Put `/_img/{options}` in front of the path of a signed link or a public
link:

```text
https://files.talewrightusercontent.com/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg
https://files.talewrightusercontent.com/_img/v=3,w=1280,h=0,q=80,fit=inside,f=webp/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg
```

- The first address is the original. The second is the same picture at
  most 1,280 pixels wide, as WebP.
- `{options}` is a list of `key=value` pairs separated by commas, with no
  spaces.
- Everything after the options is the link's own path, unchanged:
  `/p/{slug}/{name}` or `/s/{token}/{name}`.
- A variant address has no query string. One with a `?` is refused.
- A variant is available to exactly the people the link is available to.
  The link is checked first on every request, before any stored variant is
  looked at. A variant of a signed link stops when the link stops. A
  variant of a public link answers `404` the moment the file stops being
  public.
- A variant of a public link follows the current version, like the link
  itself.

#### Options

| Option | Meaning | Values | Default |
| --- | --- | --- | --- |
| `v` | Version of the resizing rules. | `3` | `3` |
| `w` | Greatest width in pixels. | A whole number from 1. It is raised to the next of 320, 640, 960, 1280, 1600, 2048, 2560. Anything above 2560 becomes 2560. | `1280` |
| `h` | Greatest height in pixels. `0` means no limit on height. | `0`, or a whole number from 1, raised to the next step of the same ladder as `w`. | `0` |
| `q` | Quality. | A whole number from 1. It is raised to the next of the three levels 60, 80, 90. Anything above 90 becomes 90. | `80` |
| `fit` | How the picture fills `w` by `h`. | `inside` or `cover` | `inside` |
| `f` | Output format. | `avif`, `webp`, `jpeg`, `png` or `auto` | `webp` |

- **`v`** is part of every address so that an address always means the same
  picture. When the rules change in a way that changes the bytes, the
  number goes up. An address without `v`, or with an earlier number,
  redirects to the current one. `v=0` or a number above the current one is
  refused.
- **`w`** and **`h`** are upper bounds, not exact sizes. The picture is
  never made larger than the original. See
  [What a variant looks like](#what-a-variant-looks-like).
- **`w`** is always in effect. An address without `w` means `w=1280`.
- **`fit=inside`** 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.
- **`fit=cover`** scales the picture down until it covers `w` by `h` and
  cuts off what sticks out, around the centre. The result always has the
  shape of `w` by `h`. It needs a height: `fit=cover` with `h=0`, or
  without `h`, is refused.
- **`q`** has three levels: 60 (smaller files), 80 (the default) and 90
  (closer to the original). PNG output is lossless and has no quality: for
  `f=png` any `q` is accepted and the address always spells `q=80`.
- **`f`** names the format of the answer. `jpeg` is spelled `jpeg`, not
  `jpg`. `auto` picks AVIF or WebP for the browser that asks. See
  [`f=auto`](#fauto).
- Numbers are 1 to 6 digits.
- Keys and values are lower case. `W=320` and `f=WEBP` are refused.
- An option given twice, an unknown option (there is no `dpr`, no `crop`,
  no `blur`) or an empty item is refused.
- The whole options part is at most 160 characters of letters, digits, `=`
  and `,`.
- A refused options part answers `422 VALIDATION_FAILED` with the message
  "Invalid image options".

#### Canonical addresses and redirects

- Every variant has exactly one address that answers bytes: all six
  options, in the order `v`, `w`, `h`, `q`, `fit`, `f`, with the values
  after rounding. This is the canonical address:
  `v=3,w=1280,h=0,q=80,fit=inside,f=webp`.
- Any other valid spelling answers `308 Permanent Redirect` to the
  canonical address. That covers options in another order, options left
  out, values that get rounded, an earlier `v` and `f=auto`.
- The `Location` of the redirect is a path on the files host:
  `/_img/{canonical options}/{the link's path as you sent it}`.
- Examples:

| You ask for | You are redirected to |
| --- | --- |
| `w=320` | `v=3,w=320,h=0,q=80,fit=inside,f=webp` |
| `f=avif,w=320` | `v=3,w=320,h=0,q=80,fit=inside,f=avif` |
| `w=319,q=77,v=3` | `v=3,w=320,h=0,q=80,fit=inside,f=webp` |
| `w=700,h=500,fit=cover,f=jpeg` | `v=3,w=960,h=640,q=80,fit=cover,f=jpeg` |
| `w=5000` | `v=3,w=2560,h=0,q=80,fit=inside,f=webp` |
| `v=1,w=320,h=0,q=80,fit=inside,f=webp` | `v=3,w=320,h=0,q=80,fit=inside,f=webp` |
| `w=320,q=90,f=png` | `v=3,w=320,h=0,q=80,fit=inside,f=png` |

- Browsers follow the redirect by themselves, so a short address such as
  `w=640,f=avif` works in an `<img>`. Writing the canonical address saves
  the extra request.
- On a public link the redirect is cached like any public answer:
  `Cache-Control: public, max-age=60, s-maxage=31536000`, with the file's
  `Cache-Tag`. On a signed link it is `private`, for what is left of the
  link's lifetime.
- The rounding keeps the set of variants of one image small and fixed: 7
  widths, 7 heights or none, 3 qualities, 2 fits and 4 formats.

#### `f=auto`

- `f=auto` never answers a picture. It always redirects, to `f=avif` or to
  `f=webp`.
- It redirects to `f=avif` when the request's `Accept` header names
  `image/avif`, in any letter case and not with `q=0`. Otherwise it
  redirects to `f=webp`.
- Wildcards do not count. `Accept: image/*` or `*/*`, or no `Accept` at
  all, gets WebP, because clients that cannot show AVIF send those too.
- This is the only answer on the files host that depends on a request
  header. It says so with `Vary: accept`, and it may be kept only by the
  browser that asked: `Cache-Control: private, max-age=86400` on a public
  link (one day), and `private` for the rest of the link's lifetime on a
  signed link.
- A CDN therefore never keeps the `f=auto` redirect, and never hands AVIF
  to a browser that did not ask for it. The explicit address the redirect
  leads to is kept like any other variant.
- An explicit format ignores `Accept`. `f=avif` answers AVIF to every
  client, whether it can show it or not.
- A browser's `<img>` names the formats it shows in `Accept`. A script's
  `fetch` sends `*/*` unless you set the header, so `f=auto` gives a script
  WebP.

#### Which files can be resized

- Variants exist for files of these types: JPEG, PNG, WebP, AVIF, GIF,
  SVG, HEIC and HEIF.
- The type is the file's real type, found from its bytes at upload, not
  its name.
- A variant address of any other file answers `404 NOT_FOUND`: a PDF, a
  video, a Photoshop file, a raw photo, an ICO, a font. Use the file's
  `thumb` or `preview` signed link for a picture of those. See
  [Downloading](downloading.md).
- A HEIC or HEIF variant is made from the original photo, at full
  sharpness up to 2,560 pixels. The original's own link still downloads as
  HEIC.
- An animated image gives a still variant of its first frame. To show the
  animation, use the original's link.
- A variant of a signed link resizes whatever that link serves. A signed
  link to a `thumb` or `preview` can be resized again. One to a `playback`
  rendition is a video and answers `404`.
- An SVG is turned into pixels. Only static SVG can be resized:
  - at most 2 MiB, in UTF-8, with `svg` as its outermost element,
  - made of `svg`, `g`, `defs`, `symbol`, `use`, `path`, `rect`, `circle`,
    `ellipse`, `line`, `polyline`, `polygon`, `text`, `tspan`, `title`,
    `desc`, `linearGradient`, `radialGradient`, `stop`, `clipPath`, `mask`,
    `pattern` and `style`,
  - without a `DOCTYPE`, processing instructions, `<script>` elements,
    event attributes such as `onload`, embedded images or `foreignObject`,
  - with references only to parts of the same file (`href="#id"`,
    `url(#id)`),
  - with styles that only set how shapes and text look. See
    [Styles in an SVG](#styles-in-an-svg),
  - with attributes of SVG itself, `xlink:href`, `xml:space` and
    `xml:lang`. `xml:base` and attributes of other vocabularies are refused,
  - with at most 10,000 elements, nested at most 128 deep.
  An SVG outside these rules answers `422` "The image source cannot be
  decoded". Its original link is not affected.

#### Styles in an SVG

An SVG may carry CSS: rules in `<style>` elements and declarations in
`style` attributes, as design tools write them when they export. The styles
are applied when the SVG is turned into pixels. A style may only set
presentation. Anything that could load a file, reach the network or run
code refuses the whole SVG.

- **Selectors** may take any form: `.cls-1`, `#logo`, `svg > g rect`,
  `rect:not(.a)`, `[data-name="Layer 1"]`.
- **Properties** are limited to this list:
  - painting: `fill`, `fill-opacity`, `fill-rule`, `stroke`, `stroke-width`,
    `stroke-opacity`, `stroke-linecap`, `stroke-linejoin`,
    `stroke-dasharray`, `stroke-dashoffset`, `stroke-miterlimit`, `opacity`,
    `color`, `stop-color`, `stop-opacity`, `paint-order`, `vector-effect`,
    `mix-blend-mode`, `isolation`,
  - showing and clipping: `display`, `visibility`, `overflow`, `clip-path`,
    `clip-rule`, `mask`, `mask-type`,
  - position: `transform`, `transform-origin`, `transform-box`,
  - rendering hints: `shape-rendering`, `text-rendering`,
    `color-rendering`, `image-rendering`, `color-interpolation`,
    `color-interpolation-filters`,
  - text: `font-family`, `font-size`, `font-weight`, `font-style`,
    `font-stretch`, `font-variant`, `font-variant-ligatures`,
    `font-variant-caps`, `font-variant-numeric`, `font-variant-position`,
    `font-variant-east-asian`, `text-anchor`, `text-align`, `text-indent`,
    `text-transform`, `text-decoration`, `text-decoration-line`,
    `text-decoration-style`, `text-decoration-color`, `text-orientation`,
    `dominant-baseline`, `alignment-baseline`, `baseline-shift`,
    `letter-spacing`, `word-spacing`, `line-height`, `white-space`,
    `writing-mode`, `direction`,
  - what Illustrator and Inkscape add: `enable-background`, `marker`,
    `marker-start`, `marker-mid`, `marker-end`, `solid-color`,
    `solid-opacity`, `block-progression`, `-inkscape-font-specification`,
    `-inkscape-stroke`,
  - custom properties, such as `--brand`.
- Any other property refuses the SVG, for example `filter`, `animation`,
  `background`, `font`, `cursor` or `content`.
- **Values** are made of keywords, numbers, lengths, percentages, `#`
  colours and commas, and of these functions only: `rgb()`, `rgba()`,
  `hsl()`, `hsla()`, `color()`, `var()`, `matrix()`, `translate()`,
  `translateX()`, `translateY()`, `scale()`, `scaleX()`, `scaleY()`,
  `rotate()`, `skew()`, `skewX()` and `skewY()`.
- Any other function refuses the SVG, for example `calc()`, `image-set()`,
  `expression()`, `attr()` or `env()`.
- `url()` is accepted only as a reference to a part of the same file,
  written exactly `url(#id)`: no quotes, no spaces, nothing before the `#`.
- A quoted string is accepted only as a font name, in `font-family` and
  `-inkscape-font-specification`. It must stay on one line.
- `!important` is accepted.
- A custom property takes the same values as any other property.
- **`@media`** is the only at-rule accepted, with ordinary rules inside and
  nested at most 4 deep. Its query is made of words, numbers and
  parentheses, such as `@media (min-width: 600px)`.
- Every other at-rule refuses the SVG: `@import`, `@font-face`,
  `@namespace`, `@charset`, `@keyframes`, `@supports`, `@page`, `@layer`.
- These refuse the SVG wherever they stand in a style, also inside a
  quoted string: a backslash, a CSS comment (`/* ... */`), a `<`, an `@`
  that does not start `@media`, and `url(` that is not `url(#id)`.
- `<style>` may hold its CSS as plain text or in a `CDATA` section. An XML
  comment or an element inside `<style>` refuses the SVG.
- Upper and lower case do not matter: `FILL:RED` is read as `fill:red`,
  and `@IMPORT` is refused like `@import`.
- Accepted is not always applied. Rules inside `@media` and values that use
  `var()` are accepted, but the resizer does not apply them: the shape is
  drawn as if that rule or declaration were not there. A `color()` value is
  skipped the same way, so a colour written twice, first as `#rrggbb` and
  then as `color(display-p3 ...)`, is drawn from the first.

#### What a variant looks like

- **Never larger than the original.** A variant is scaled down, never up.
  An original 612 pixels wide asked for at `w=640` comes out 612 pixels
  wide. `X-Image-Width` and `X-Image-Height` on the answer say what you
  got.
- **Proportions are kept** with `fit=inside`. An original of 1,200 by 800
  at `w=320` comes out 320 by 213.
- **Exact crops** with `fit=cover`, 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.
- **Smaller crops of the same shape** with `fit=cover`, when the original
  is smaller than the box on a side. The crop is the largest one of the
  box's shape that the original holds without being enlarged: an original
  of 400 by 300 at `w=320,h=320` comes out 300 by 300, and at
  `w=960,h=640` it comes out 400 by 267.
- **Upright.** A photo that says in its camera data that it was taken
  sideways is turned upright before resizing. Width and height are those
  of the upright picture.
- **No camera data.** A variant is a newly encoded picture. It carries
  nothing of the original's camera data: no EXIF, so no location, no
  camera model and no capture date. Only the original's own link serves
  that.
- **Transparency is kept** in AVIF, WebP and PNG.
- **JPEG has no transparency.** Transparent areas become white.
- **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.
- **Stills only.** The variant of an animated image is its first frame.
- **Format is what you named.** The `Content-Type` of the answer is
  `image/avif`, `image/webp`, `image/jpeg` or `image/png`, whatever the
  name at the end of the address says. `.../hero.jpg` with `f=webp` is a
  WebP.

#### What a variant answer carries

| Header | Value |
| --- | --- |
| `Content-Type` | `image/avif`, `image/webp`, `image/jpeg` or `image/png`. |
| `Content-Length` | The size of the variant. |
| `ETag` | `"sha256:{64 hex digits}"` of the variant's own bytes. |
| `Cache-Control` | As for the link: `public, max-age=60, s-maxage=31536000` on a public link, `private, max-age={seconds}` on a signed link. |
| `Cache-Tag` | `tw-file-{fileID}`, on a public link only. |
| `X-Image-Width`, `X-Image-Height` | The size of the variant in pixels. |
| `X-Image-Cache` | `miss` when the variant was rendered for this request, `hit` when it already existed. |
| `X-Content-Type-Options` | `nosniff` |

- A variant answers `304 Not Modified` when `If-None-Match` names its
  `ETag`, also in the weak form (`W/`) and in a list. This works on public
  and on signed links.
- A variant is always sent whole. It has no `Accept-Ranges` and ignores
  `Range`.
- A variant has no `Content-Disposition` and no `Content-Security-Policy`.
  It is a picture to show, opened directly it shows in the browser.
- `HEAD` answers the same headers without the picture.
- A variant of a public link also carries the headers under
  [Use from other websites](#use-from-other-websites).
- `hit` or `miss` makes no difference to the picture. When several people
  ask for the same new variant at the same moment, it is rendered once: one
  answer says `miss`, the others `hit`.

#### Checks, in order

A request for a variant is checked in this order. The first check that
fails decides the answer:

1. The address has a query string: `422 VALIDATION_FAILED`, "Image
   addresses have no query".
2. What follows the options is not a signed link's or a public link's
   path: `422 VALIDATION_FAILED`, "Source must be a file delivery path".
   A gallery address and a ZIP address cannot be resized.
3. The link does not work: `403 FORBIDDEN` for a signed link, `404
   NOT_FOUND` for a public link.
4. The file is not of a type that can be resized: `404 NOT_FOUND`.
5. The options are not valid: `422 VALIDATION_FAILED`, "Invalid image
   options".
6. The options are valid but not canonical: `308` to the canonical
   address.
7. The original is larger than 64 MiB: `422 VALIDATION_FAILED`, "Image
   source exceeds 64 MiB".
8. The original is over a size limit: `422 VALIDATION_FAILED`, "Image
   source exceeds 16,384 pixels a side or 100 million pixels".
9. The original cannot be turned into a picture: `422 VALIDATION_FAILED`,
   "The image source cannot be decoded". This covers a damaged file and an
   SVG outside the rules above.
10. The variant asked for would be too large: `422 VALIDATION_FAILED`, "The
    resulting image is too large". The limits are 24 million pixels and 16
    MiB. Ask for a smaller width or a height.
11. Decoding and resizing took longer than 15 seconds: `503 UNAVAILABLE`
    with `details.reason` `IMAGE_RENDER_TIMED_OUT` and `Retry-After`. See
    [When the resizer is busy](#when-the-resizer-is-busy).
12. Otherwise the variant is answered: `200`, or `304` for a matching
    `If-None-Match`.

- Because the link is checked before the options, an address with nonsense
  options on an unknown or restricted public link answers `404`, not `422`.
- With widths capped at 2,560 pixels, the pixel limit is reached only by
  very tall pictures: more than 9,375 pixels high at full width. `fit=cover`
  never reaches it.
- A variant that already exists skips checks 7 to 11.

#### When the resizer is busy

- Rendering a new variant takes a moment, and 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, or the resizer cannot be reached, the answer
  is `503 UNAVAILABLE` with `details.reason` `IMAGE_SERVICE_UNAVAILABLE`,
  the message "Temporarily unavailable; try again shortly" and a
  `Retry-After` header in seconds, at least 1.
- A render that runs out of its 15 seconds answers the same way, with
  `details.reason` `IMAGE_RENDER_TIMED_OUT` and a `Retry-After` of 30
  seconds. It is a temporary failure: the same picture can pass when the
  resizer is less busy. If it keeps failing, ask for a smaller width.
- The `503` is never cached. The same address works as soon as there is
  room. Nothing about the file or the link changed.
- A variant that already exists is answered without waiting for a turn.
- Originals are not affected. A public link and a signed link keep serving
  the stored bytes while the resizer is busy or down.
- A browser does not retry an `<img>` by itself. A page that must not show
  a broken picture can fall back to the original in `onerror`, or to a
  variant that is known to exist.

### Use from other websites

- A public link and every variant of it can be read from any website. This
  is what makes a web font, a script's `fetch`, a `<canvas>` or a CSS
  background on another site work.
- Every answer on `/p/{slug}/{name}` and on `/_img/{options}/p/{slug}/{name}`
  carries these three headers:

| Header | Value |
| --- | --- |
| `Access-Control-Allow-Origin` | `*` |
| `Access-Control-Expose-Headers` | `accept-ranges, content-disposition, content-range, etag` |
| `Cross-Origin-Resource-Policy` | `cross-origin` |

- "Every answer" includes `200`, `206`, `304`, the `308` redirects of
  variants and every refusal, the `404` of an unknown link included. A
  script on another site can therefore read why a request failed, and a
  cross-origin `fetch` can follow a variant's redirect.
- The headers are the same whether or not the request names an `Origin`.
  Nothing varies by who asks, so a copy kept by a CDN works for every
  site.
- A preflight (`OPTIONS`) on those addresses answers `204` with the three
  headers above and:

| Header | Value |
| --- | --- |
| `Access-Control-Allow-Methods` | `GET, HEAD` |
| `Access-Control-Allow-Headers` | `*` |
| `Access-Control-Max-Age` | `86400` |

- 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.
- `*` never allows credentials. No answer carries
  `Access-Control-Allow-Credentials`, and cookies are ignored anyway. A
  `fetch` with `credentials: "include"` is refused by the browser; leave
  credentials out.
- A script can read these response headers across origins: `ETag`,
  `Content-Range`, `Accept-Ranges` and `Content-Disposition`, next to the
  ones every browser exposes, such as `Content-Type` and `Content-Length`.
  Other headers are not readable by a script on another site:
  `X-Image-Width`, `X-Image-Height`, `X-Image-Cache` and `Cache-Tag`. Read
  a picture's size from the picture itself.
- **Not readable from other websites:** signed links, variants of signed
  links, gallery pages and ZIP downloads. They carry none of these headers,
  and `OPTIONS` on them answers `405 METHOD_NOT_ALLOWED`. They still work
  as a plain link, in an `<img>` or as a download. A script on another site
  cannot read their bytes.
- The app and the API on `https://app.usetalewright.com` are not readable
  from other websites either.

## In the app

The app uses signed links for everything it shows. It builds no variant
addresses: those are for your own pages.

- **Thumbnails in listings** are each file's `thumbnailURL`, a signed link
  to the `thumb` rendition.
- **The preview on a file's page** is its `previewURL`, a signed link to
  the `preview` rendition. While it is being made the page says "Preparing
  preview". When there is none it says "Preview unavailable".
- **Expired thumbnails.** A thumbnail's signed link stops after 10 to 15
  minutes, and the app reads the listing again every 9. When a
  thumbnail or preview fails to load, the app fetches the listing again
  once to get fresh links. It does not retry in a loop.
- **Video** plays from a signed link: the `playback` rendition once it is
  ready, otherwise the original. While the rendition is made the page says
  "Preparing video". A video that cannot play says "This video cannot play
  here. Download it instead."
- **"Download"** uses a signed link to the original of the current version.
- **The public link** of a public file is in the textbox "Public link" in
  the "Sharing" section or card and in the "Share {name}" dialog, with the button
  "Copy public link". Copying says "Copied the link". If the browser
  refuses: "Could not copy. Select the link and copy it."
- The button "Copy link for members" copies the file's address in the
  app, which only people with access can open, whether or not the file is
  public.
- **A public folder's gallery page** shows a thumbnail for each picture.
  Those thumbnails are variants of each file's public link:
  `v=3,w=320,h=0,q=80,fit=inside,f=webp`. SVG files show their extension
  instead of a thumbnail.

To use a variant, copy the public link from "Public link" and put
`/_img/{options}` after the host name, as in the [recipes](#recipes).

## For agents

The files host is not part of the REST API and has no MCP tools. It is
plain HTTP: `GET` an address. It needs no `Authorization` header, so do not
send an API key to it.

Two things lead to an address:

| What | Where it comes from |
| --- | --- |
| A public link | `publicURL` on a file read with `workspace.files.get` or `library.files.get`. It is `null` while the file is not public. A listing says whether each file is public (`public`) but does not carry the link. |
| A signed link | `workspace.files.signed_url` or `library.files.signed_url`, or `thumbnailURL` and `previewURL` on a file. |

| Operation | Capability ID | MCP tool | Scope |
| --- | --- | --- | --- |
| `POST /v1/workspaces/{workspaceID}/files/{fileID}/versions/{versionID}/signed-url` | `workspace.files.signed_url` | `workspace_files_signed_url` | `files:read` |
| `POST /v1/organizations/{organizationID}/library/files/{fileID}/versions/{versionID}/signed-url` | `library.files.signed_url` | `library_files_signed_url` | `files:read` |

- The body is `{"variant": "original"}`. `variant` is `original`, `thumb`,
  `preview` or `playback`.
- The answer is `{"url": "...", "expiresAt": "..."}`. `url` is on the files
  host and works for 10 minutes.
- Any version of the file can be named, not only the current one.
- Its refusals (a trashed file, a preview that is not ready, an unknown
  variant) are in [Downloading](downloading.md) and
  [MCP](../agents/mcp.md#files).

### Worked example: a signed link, then a variant of it

```sh
curl -s -X POST \
  "$TALEWRIGHT/v1/workspaces/$WORKSPACE_ID/files/$FILE_ID/versions/$VERSION_ID/signed-url" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variant": "original"}'
```

```json
{
  "url": "https://files.talewrightusercontent.com/s/AZL4.../hero.jpg",
  "expiresAt": "2026-11-14T12:10:00Z"
}
```

Download the original, or ask for a 640-pixel WebP of it by putting the
options in front of the link's path:

```sh
curl -s -o hero.jpg \
  "https://files.talewrightusercontent.com/s/AZL4.../hero.jpg"

curl -s -o hero-640.webp \
  "https://files.talewrightusercontent.com/_img/v=3,w=640,h=0,q=80,fit=inside,f=webp/s/AZL4.../hero.jpg"
```

- Both work without any header, for 10 minutes.
- A private image can be analysed this way without downloading a
  multi-megabyte original: ask for the smallest width that is enough.

### Building a variant address from a public link

1. Read the file and take `publicURL`. If it is `null`, the file is not
   public: an owner or admin makes it public in the app.
2. Split it after the host: `https://files.talewrightusercontent.com` and
   `/p/{slug}/{name}`.
3. Put `/_img/{options}` between the two.
4. Write the options in canonical form to avoid a redirect:
   `v=3,w={step},h={step or 0},q={60|80|90},fit={inside|cover},f={format}`.

The file's `currentVersion.media` holds the original's `width` and
`height`. Do not ask for steps far above the original's width: they all
answer the original's size.

### Recipes

The examples use the public link
`https://files.talewrightusercontent.com/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg`
of a photo 2,400 pixels wide. Every variant address in them is canonical.

#### A responsive image

```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=320,h=0,q=80,fit=inside,f=webp/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg 320w,
    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=960,h=0,q=80,fit=inside,f=webp/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg 960w,
    https://files.talewrightusercontent.com/_img/v=3,w=1280,h=0,q=80,fit=inside,f=webp/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg 1280w,
    https://files.talewrightusercontent.com/_img/v=3,w=1600,h=0,q=80,fit=inside,f=webp/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg 1600w,
    https://files.talewrightusercontent.com/_img/v=3,w=2048,h=0,q=80,fit=inside,f=webp/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg 2048w"
  sizes="(min-width: 1024px) 50vw, 100vw"
  width="2400" height="1600"
  alt="The harbour at dawn">
```

- The widths are the steps of the ladder. Any other number redirects to
  the next step.
- The addresses hold commas. Keep each candidate as `address`, a space,
  the width, then a comma and a line break or space, as above.
- List steps only up to the original's width. A step above it answers the
  original's size, and its `w` descriptor would then promise more pixels
  than the picture has. Here the original is 2,400 wide, so `2560` is left
  out.
- `width` and `height` are the original's proportions, so the page does
  not jump while the picture loads.

#### AVIF with a WebP and a JPEG fallback

```html
<picture>
  <source
    type="image/avif"
    srcset="
      https://files.talewrightusercontent.com/_img/v=3,w=640,h=0,q=80,fit=inside,f=avif/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg 640w,
      https://files.talewrightusercontent.com/_img/v=3,w=1280,h=0,q=80,fit=inside,f=avif/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg 1280w,
      https://files.talewrightusercontent.com/_img/v=3,w=2048,h=0,q=80,fit=inside,f=avif/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg 2048w"
    sizes="100vw">
  <source
    type="image/webp"
    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,
      https://files.talewrightusercontent.com/_img/v=3,w=2048,h=0,q=80,fit=inside,f=webp/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg 2048w"
    sizes="100vw">
  <img
    src="https://files.talewrightusercontent.com/_img/v=3,w=1280,h=0,q=80,fit=inside,f=jpeg/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg"
    width="2400" height="1600"
    alt="The harbour at dawn">
</picture>
```

- The browser takes the first `<source>` whose `type` it can show. Every
  address is explicit, so every answer can be kept by a CDN.
- This is the fastest setup: no redirects and no dependence on `Accept`.

#### One address, the best format: `f=auto`

```html
<img
  src="https://files.talewrightusercontent.com/_img/w=1280,f=auto/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg"
  alt="The harbour at dawn">
```

- The browser is redirected to the AVIF or the WebP variant, and remembers
  that for a day.
- It costs one extra request per browser per day and per address. Use it
  where one plain address matters more than that, such as in a CMS field
  or an email template that only takes one URL.

#### A square crop

```html
<img
  src="https://files.talewrightusercontent.com/_img/v=3,w=320,h=320,q=80,fit=cover,f=webp/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg"
  width="320" height="320" alt="">
```

- `fit=cover` fills 320 by 320 and cuts off the rest around the centre.
- Crops come in the shapes the ladder forms, such as 640 by 640, 960 by
  640 (3:2), 1280 by 960 (4:3) and 1280 by 640 (2:1). For any other shape,
  ask for an `inside` variant and crop it in CSS with `object-fit: cover`.

#### A web font from a public link

Upload the font file, give it a status that allows public use and make it
public. Then:

```html
<link
  rel="preload" as="font" type="font/woff2" crossorigin
  href="https://files.talewrightusercontent.com/p/8d41c06be2a94f37b5d09e6a1c7f3b22/brand-sans.woff2">
<style>
  @font-face {
    font-family: "Brand Sans";
    src: url("https://files.talewrightusercontent.com/p/8d41c06be2a94f37b5d09e6a1c7f3b22/brand-sans.woff2")
      format("woff2");
    font-display: swap;
  }
  body { font-family: "Brand Sans", system-ui, sans-serif; }
</style>
```

- Browsers load fonts from another site only when that site allows it.
  The public link does, for every origin.
- `crossorigin` on the preload is required, or the browser fetches the
  font twice.
- A font opened directly downloads. Used in `@font-face` it loads as a
  font.
- When you replace the font with a new version, the same address serves
  it. Browsers pick it up within a minute.

#### Reading a public file from a script on another site

```js
const address =
  "https://files.talewrightusercontent.com/_img/v=3,w=640,h=0,q=80,fit=inside,f=webp/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg";
const response = await fetch(address);
if (!response.ok) {
  const { error, requestID } = await response.json();
  throw new Error(`${error.code}: ${error.message} (${requestID})`);
}
console.log(response.headers.get("etag"));
const picture = await createImageBitmap(await response.blob());
```

- No `credentials` and no `mode` are needed.
- To draw a public image on a `<canvas>` and read the canvas back, load it
  with `<img crossorigin="anonymous" src="...">`.

#### A conditional request

```sh
curl -s -o /dev/null -D - \
  "https://files.talewrightusercontent.com/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg" \
  -H 'If-None-Match: "sha256:9b1c7e0a4d2f58c36a1be07d94c5f2a8e6d3b0c1f7a9482e5d6c3b0a1f8e7d24"'
```

```text
HTTP/1.1 304 Not Modified
etag: "sha256:9b1c7e0a4d2f58c36a1be07d94c5f2a8e6d3b0c1f7a9482e5d6c3b0a1f8e7d24"
cache-control: public, max-age=60, s-maxage=31536000
cache-tag: tw-file-0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01
access-control-allow-origin: *
```

The tag is the file's `currentVersion.digest` from the API, in quotes. An
agent that mirrors public files can poll this way and download only when
the file changed.

#### A byte range

```sh
curl -s -o first-kilobyte.bin -D - \
  "https://files.talewrightusercontent.com/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg" \
  -H "Range: bytes=0-1023"
```

```text
HTTP/1.1 206 Partial Content
content-type: image/jpeg
content-length: 1024
content-range: bytes 0-1023/482113
accept-ranges: bytes
etag: "sha256:9b1c7e0a4d2f58c36a1be07d94c5f2a8e6d3b0c1f7a9482e5d6c3b0a1f8e7d24"
```

To resume safely, send the tag you started with as `If-Range`. If the file
was replaced meanwhile, you get the whole new file with `200`.

#### A redirect to the canonical address

```sh
curl -s -o /dev/null -D - \
  "https://files.talewrightusercontent.com/_img/w=600,f=avif/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg"
```

```text
HTTP/1.1 308 Permanent Redirect
location: /_img/v=3,w=640,h=0,q=80,fit=inside,f=avif/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg
cache-control: public, max-age=60, s-maxage=31536000
cache-tag: tw-file-0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01
access-control-allow-origin: *
```

Add `-L` to follow it. Read `location` once and store the canonical
address to skip the redirect from then on.

## Edge cases

| Situation | What happens | Why |
| --- | --- | --- |
| A public link is opened with another name at the end (`/p/{slug}/anything.png`) | The same file is served. | The name is a label. The slug finds the file. |
| A public file is renamed | Old links keep working. `Content-Disposition` carries the new name. | Same reason. |
| A public file is replaced with a new version | The same link, and every variant address, serves the new version. The `ETag` changes. | A public link follows the current version. |
| A signed link was made, then the file got a new version | The link still serves the version it was made for, until it expires. | A signed link names one version. |
| A signed link is used after 10 minutes | `403 FORBIDDEN`. | It expired. Ask for a new one. |
| One character of a signed link's token is changed | `403 FORBIDDEN`. | An altered link is not valid. |
| A file is moved to the trash while someone holds a signed link | The link answers `403` at once. | Trashing stops every signed link of the file. |
| That file is restored | The old signed link still answers `403`. | Restoring does not bring old signed links back. New ones work. |
| A public file is trashed and restored | The public link answers `404` while trashed and works again after the restore, at the same address. | See [Sharing and public links](sharing.md#the-public-link). |
| A request carries the app's session cookie | The answer is the same as without it, and no cookie is set. | The files host ignores cookies. |
| An API key is sent to the files host in `Authorization` | It is ignored. A valid link works, an invalid one does not. | The link is the whole permission. |
| `If-None-Match` with the current tag on a public link | `304`, no body. | Nothing changed. |
| `If-None-Match` with `W/"sha256:..."` | `304` when the tag inside matches. | A CDN may weaken a tag on the way. |
| `If-None-Match` with the current tag on a signed link | `304`, no body, while the link works. An expired or stopped link answers `403`. | The link is checked before the tag. |
| `Range: bytes=0-9,20-29` | `200` with the whole content. | Only one range per request is served. |
| `Range: bytes=5-2` or `Range: items=0-9` | `200` with the whole content. | A range that makes no sense is ignored. |
| `Range: bytes=0-999999999` on a small file | `206` up to the last byte. | The end is cut to the content's end. |
| `Range` starting at or past the file's size | `416 RANGE_NOT_SATISFIABLE` with `Content-Range: bytes */{size}`. | No byte of the range exists. |
| `Range` with `If-Range` naming an earlier version's tag | `200` with the whole current file. | Parts of two versions must not be mixed. |
| `Range` with `If-Range` as a date or a weak tag | `200` with the whole current file. | Only the exact current tag matches. |
| `Range` on a variant | `200` with the whole variant. | Variants are always sent whole. |
| `POST` or `DELETE` on any files host address | `405 METHOD_NOT_ALLOWED`. | The files host only serves. |
| `OPTIONS` on a public link from any site | `204` with the allow headers. | Other websites may read public files. |
| `OPTIONS` on a public link whose slug does not exist | `204` all the same. The `GET` after it answers `404`. | A preflight is answered without looking the file up. |
| `OPTIONS` on a signed link, a gallery or a ZIP address | `405 METHOD_NOT_ALLOWED`, no allow headers. | Those are not readable from other websites. |
| A script on another site fetches a signed link | The browser blocks reading the answer. | Signed links carry no cross-origin headers. |
| A script fetches a public link with `credentials: "include"` | The browser refuses the answer. | `*` never allows credentials. |
| A script on another site fetches a restricted file's old public link | `404`, readable by the script. | Refusals on public addresses carry the cross-origin headers too. |
| A variant is asked for with `w=600` | `308` to `w=640`. | Widths are rounded up to the ladder. |
| A variant is asked for with `w=4000` | `308` to `w=2560`. | 2560 is the widest step. |
| `w=640` on an original 612 pixels wide | A variant 612 pixels wide. `X-Image-Width: 612`. | A variant is never larger than the original. |
| `w=320` and `w=2560` on an original 300 pixels wide | Two addresses, both answering a 300-pixel picture. | Same rule. Do not list steps above the original's width. |
| `h=200` | `308` to `h=320`. | Heights use the same ladder as widths. |
| `fit=cover` without `h`, or with `h=0` | `422`, "Invalid image options". | A crop needs a height. |
| `f=jpg` | `422`, "Invalid image options". | The format is spelled `jpeg`. |
| `q=100` | `308` to `q=90`. | 90 is the highest level. |
| `q=0`, `w=0` or `v=0` | `422`, "Invalid image options". | Only `h` may be 0. |
| `f=png` with `q=60` or `q=90` | `308` to the same address with `q=80`. | PNG has no quality, so it has one address. |
| `v=1` | `308` to `v=3`. | An earlier version redirects to the current one. |
| `v=4` | `422`, "Invalid image options". | That version does not exist. |
| `w=320,w=640`, `dpr=2` or `W=320` | `422`, "Invalid image options". | Each option once, known options only, lower case. |
| A variant address with `?width=300` | `422`, "Image addresses have no query". | Options go in the path. |
| `/_img/w=320/p/f/{slug}/{name}` (a gallery) | `422`, "Source must be a file delivery path". | Only file links can be resized. |
| Nonsense options on a public link that does not exist | `404 NOT_FOUND`. | The link is checked before the options. |
| A variant of a public PDF, video, font or Photoshop file | `404 NOT_FOUND`. | Only the eight image types have variants. |
| A variant of a HEIC photo | A WebP, AVIF, JPEG or PNG that every browser shows. | HEIC and HEIF originals can be resized. |
| The public link of that HEIC photo itself | It downloads as HEIC. | Browsers do not show HEIC, so the original is an attachment. |
| A variant of an animated GIF | A still picture of the first frame. | Variants are stills. The original link serves the animation. |
| A transparent PNG as `f=jpeg` | Transparent areas are white. | JPEG has no transparency. |
| A transparent PNG as `f=webp`, `f=avif` or `f=png` | Transparency is kept. | Those formats carry it. |
| A photo with location data, as a variant | The variant holds no location and no other camera data. | A variant is newly encoded. Only the original carries camera data. |
| A photo taken sideways | The variant is upright, and `w` and `h` apply to the upright picture. | The orientation is applied before resizing. |
| A panorama of 3,000 by 14,000 pixels at `w=2560` | `422`, "The resulting image is too large". At `w=1280` it works. | The variant would pass 24 million pixels. |
| A very large picture as `f=png` | It may answer `422`, "The resulting image is too large". | A lossless PNG can pass 16 MiB. Use WebP or a smaller width. |
| An original of 70 MiB | Its public link works. Its variants answer `422`, "Image source exceeds 64 MiB". | Only originals up to 64 MiB can be resized. |
| A picture of 20,000 by 20,000 pixels | `422`, "Image source exceeds 16,384 pixels a side or 100 million pixels". | It is over both limits. One is enough. |
| An SVG with class rules in `<style>` and `style` attributes that set fills, strokes and fonts | It is resized, with the styles applied. | Styles that only set presentation are accepted. |
| An SVG whose style holds `@import`, `@font-face` or a `url()` to another file or address | Its variants answer `422`, "The image source cannot be decoded". Its original link works. | A style may not load anything. |
| An SVG whose style holds a CSS comment or a backslash | Same. | Either could hide what the style really says, so neither is read. |
| An SVG animated by CSS (`@keyframes`, `animation`) | Same. | Only the listed properties and `@media` are accepted. |
| An SVG that sets `filter` in a style | Same. | `filter` is not in the list, and `filter` elements are not accepted either. |
| An SVG with rules inside `@media (prefers-color-scheme: dark)` | It is resized. Those rules are not applied. | `@media` is accepted, but the resizer applies nothing inside it. |
| An SVG that paints with `fill: var(--brand)` | It is resized. The shape gets the default fill, black. | `var()` is accepted, but the resizer does not apply it. |
| An SVG that references an external image or font | Same. | An SVG may only reference parts of itself. |
| `f=auto` from a browser that shows AVIF | `308` to the `f=avif` address. | Its `Accept` names `image/avif`. |
| `f=auto` with `Accept: */*`, or from `curl` | `308` to the `f=webp` address. | A wildcard does not count as asking for AVIF. |
| `f=auto` with `Accept: image/avif;q=0, image/webp` | `308` to the `f=webp` address. | `q=0` means "not this". |
| `f=avif` from a browser that cannot show AVIF | AVIF is answered anyway. The picture does not show. | An explicit format ignores `Accept`. Use `<picture>` or `f=auto`. |
| `v=3,w=320,h=0,q=80,fit=inside,f=auto` (every other option canonical) | Still a `308`. | `f=auto` never answers a picture. |
| A file is restricted after its variants were rendered | Every variant address answers `404` at once. | The link is checked on every request, before any stored variant. |
| Many new variants are asked for at the same moment | They wait their turn, up to 10 seconds; past that, some answer `503 UNAVAILABLE` with `Retry-After`. Asking again works. | Only 4 are rendered at once. A folder of large photos fills in over a minute or so; the web app shimmers in their place meanwhile. |
| Twenty visitors open the same new variant at the same moment | It is rendered once and all twenty get it. | Requests for the same new variant share one render. |
| A variant answered `503` | Nothing is kept. The next request is tried afresh. | Refusals carry `Cache-Control: no-store`. |
| A variant of a signed link to a `preview` rendition | The 1,600-pixel WebP preview, resized again. | A variant resizes what the link serves. |
| A file named `a/b.jpg` | Its links end in `a%2Fb.jpg` and work, variants included. | The name is percent-encoded in every link Talewright hands out. |
| A public link whose workspace was deleted | `404`. After the workspace is restored, the same link works. | Nothing in a deleted workspace is public. |

## Errors

Refusals on the files host use the API's error envelope. None is cached.

| Code | Status | When | What to do |
| --- | --- | --- | --- |
| `FORBIDDEN` | 403 | A signed link, a variant of one or a ZIP link is altered, expired, or stopped because the file was trashed, restored or deleted. | Ask the API for a new signed link. |
| `NOT_FOUND` | 404 | A public link whose file is restricted, trashed, blocked by its status, deleted or unknown. A variant of a file that is not one of the eight image types. An address the files host does not have. | Check the file's `public` and `publicURL` in the API. For a variant, check the file's type. |
| `METHOD_NOT_ALLOWED` | 405 | Any method other than `GET` and `HEAD`. `OPTIONS` on anything but a public link or its variant. | Use `GET`. |
| `RANGE_NOT_SATISFIABLE` | 416 | A byte range starts at or past the end. `details.sizeBytes` and `Content-Range: bytes */{size}` give the size. | Ask for a range inside the size. |
| `VALIDATION_FAILED`, "Invalid image options" | 422 | The options part of a variant address breaks a rule. `details.field` is `options`. | See [Options](#options). |
| `VALIDATION_FAILED`, "Image addresses have no query" | 422 | A variant address has a `?`. `details.field` is `image`. | Put options in the path. |
| `VALIDATION_FAILED`, "Source must be a file delivery path" | 422 | What follows the options is not `/s/{token}/{name}` or `/p/{slug}/{name}`. `details.field` is `image`. | Resize a file's link, not a gallery or a ZIP. |
| `VALIDATION_FAILED`, "Image source exceeds 64 MiB" | 422 | The original is larger than 64 MiB. `details.field` is `image`. | Use the original, or upload a smaller master. |
| `VALIDATION_FAILED`, "Image source exceeds 16,384 pixels a side or 100 million pixels" | 422 | The original is over one of those limits. `details.field` is `image`. | Use the original link, or upload a smaller master. |
| `VALIDATION_FAILED`, "The image source cannot be decoded" | 422 | The original is damaged, or an SVG outside the rules. `details.field` is `image`. | Use the original link, or replace the file. |
| `VALIDATION_FAILED`, "The resulting image is too large" | 422 | The variant would pass 24 million pixels or 16 MiB. `details.field` is `image`. | Ask for a smaller `w`, set an `h`, or use WebP instead of PNG. |
| `UNAVAILABLE`, reason `IMAGE_SERVICE_UNAVAILABLE` | 503 | The resizer is busy or cannot be reached. `Retry-After` gives the seconds to wait. | Wait that long and ask again. Originals are not affected. |
| `UNAVAILABLE`, reason `IMAGE_RENDER_TIMED_OUT` | 503 | Decoding and resizing the picture took longer than 15 seconds. `Retry-After` gives the seconds to wait. | Ask again. If it keeps failing, ask for a smaller `w`. |
| `TIMEOUT` | 503 | The request ran past its time limit. | Ask again. |
| `INTERNAL` | 500 | An unexpected failure on our side. | Ask again. Quote the `requestID` if it persists. |

See [Errors on the files host](../reference/errors.md#errors-on-the-files-host)
and [Errors](../reference/errors.md) for the shape of every error.

## Limits

| What | Value |
| --- | --- |
| Lifetime of a signed link | 10 minutes |
| Lifetime of `thumbnailURL` and `previewURL` | 10 to 15 minutes; the same link within five minutes |
| Browser cache of a public link or its variant | 60 seconds (`max-age=60`) |
| Longest a CDN may keep a public answer | 1 year (`s-maxage=31536000`), dropped earlier when the link's content changes |
| Browser cache of an `f=auto` redirect on a public link | 1 day (`max-age=86400`), browser only |
| Cache of a gallery page | 60 seconds, browser and CDN |
| How long a browser may remember a preflight | 1 day (`Access-Control-Max-Age: 86400`) |
| Byte ranges per request | 1 |
| Widths (`w`) | 320, 640, 960, 1280, 1600, 2048, 2560 |
| Heights (`h`) | 0 (no limit), 320, 640, 960, 1280, 1600, 2048, 2560 |
| Qualities (`q`) | 60, 80, 90 |
| Formats (`f`) | `avif`, `webp`, `jpeg`, `png`; `auto` redirects to `avif` or `webp` |
| Options part of a variant address | Up to 160 characters; numbers of 1 to 6 digits |
| Source types with variants | JPEG, PNG, WebP, AVIF, GIF, SVG, HEIC, HEIF |
| Largest original that can be resized | 64 MiB; an SVG 2 MiB |
| Largest picture that can be resized | 100 million pixels and 16,384 pixels a side |
| Largest SVG that can be resized | 10,000 elements, nested 128 deep |
| Largest variant | 24 million pixels and 16 MiB |
| Longest render | 15 seconds, then `503` |
| Longest wait for a render to start | 5 seconds, then `503` |
| Thumbnail (`thumb`) and preview (`preview`) renditions | WebP that fits 320 and 1,600 pixels |

More limits of downloads and delivery are in
[Limits](../reference/limits.md#downloading-and-delivery).

## Questions and answers

**What is the difference between a signed link and a public link?**
A signed link works for 10 minutes for whoever holds it 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.

**Can I use a public link in an `<img>` on my website?**
Yes. That is what it is for. It can also be used in CSS, as a font, in a
`<video>` and from scripts, on any site.

**How do I get a smaller version of an image?**
Put `/_img/w=640/` after the host name of its link. You are redirected to
the full address of a 640-pixel WebP. See the [recipes](#recipes).

**Which sizes can I ask for?**
Widths of 320, 640, 960, 1280, 1600, 2048 and 2560 pixels. Any other
number is rounded up to the next one.

**Why can I not ask for exactly 700 pixels?**
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.

**Why did I get `308`?**
Your address was valid but not the canonical one: an option was missing,
out of order or got rounded, or you used `f=auto`. The `Location` header
holds the canonical address. Browsers follow it by themselves.

**I asked for `w=2560` and the picture is no bigger than before. Why?**
The original is smaller than that. A variant is never larger than the
original. `X-Image-Width` on the answer says how wide it is.

**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.

**Which format should I use?**
`<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.

**What does `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
rounded up to the next level. PNG ignores it.

**Can I crop?**
Yes, with `fit=cover` and both `w` and `h`. The picture is cut around its
centre. The shapes are those the ladder forms. There is no way to choose
another focus point.

**Can I get a 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.

**My HEIC photo downloads instead of showing. Why?**
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.

**What happens with animated GIFs?**
A variant is a still picture of the first frame. The original link serves
the animation as it was uploaded.

**Does a variant keep the photo's location and other camera data?**
No. A variant carries no camera data. The original's own public link
serves the file as it was uploaded, with everything in it. See
[Location data](sharing.md#location-data).

**I replaced the 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.

**Visitors still see the old picture after I replaced it. Why?**
A browser reuses its own copy for up to 60 seconds. After that it asks
again and gets the new one.

**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.

**Is a variant address stable?**
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.

**What does `X-Image-Cache: miss` mean?**
The variant was rendered for this request. `hit` means it already existed.
The picture is the same either way.

**I get `503` with `IMAGE_SERVICE_UNAVAILABLE`. What now?**
The resizer is busy. Wait the number of seconds in `Retry-After` and ask
again. The answer is never cached, and the original link keeps working
meanwhile.

**Why does my variant 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.

**Why does my variant answer "The image source cannot be decoded"?**
The picture is damaged, or an SVG that uses scripts, outside references
or styles outside [the rules](#styles-in-an-svg). A picture that is too large answers "Image source exceeds 16,384 pixels a side or 100 million pixels" instead.
The original link is not affected either way.

**Can a script on another site read my private files?**
No. Only public links and their variants are readable from other websites.
Signed links are not, and the app and the API are not.

**Can I load a web font from Talewright?**
Yes. Make the font file public and use its public link in `@font-face`.
See [A web font from a public link](#a-web-font-from-a-public-link).

**Can I resume a large download?**
Yes. Send `Range` for the missing part and the `ETag` you started with as
`If-Range`. If the file changed, you get the whole new file instead.

**Why does a 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. See
[Inline or download](#inline-or-download).

**Do I need an API key to open a link?**
No. Neither kind of link needs a key, a cookie or a sign-in. Do not send
your key to the files host.

**Can I make a signed link last longer than 10 minutes?**
No. Ask for a new one when you need it. For something that should keep
working, make the file public and use its public link.

**Can I pass options as a query string, like `?w=640`?**
No. Options go in the path, right after `/_img/`. A variant address with a
query string is refused.

**Does the name at the end of an address matter?**
No. It only labels a saved file. `hero.jpg`, `x.png` or the file's new
name after a rename all reach the same file. The format of a variant comes
from `f`, not from the name.

**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.

## Related pages

- [Sharing and public links](sharing.md)
- [Statuses](statuses.md#allows-public-use)
- [Downloading](downloading.md)
- [Versions and history](versions.md)
- [Uploading](uploading.md)
- [Trash and restore](trash.md)
- [Files & Assets overview](overview.md)
- [MCP](../agents/mcp.md#files) and [The REST API](../agents/rest-api.md)
- [Credentials and scopes](../agents/credentials.md#scopes)
- [Roles and permissions](../reference/permissions.md#files-in-a-workspace)
- [Limits](../reference/limits.md#downloading-and-delivery) and
  [Errors](../reference/errors.md#errors-on-the-files-host)

