Talewright Docs Open the app

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.

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. How a person downloads files is in Downloading.

Who can do what

ActionWhoSessionCredential (scope)
Get a signed link for a version of a workspace fileEveryone who can open the workspaceYesYes (files:read)
Get a signed link for a version of an organization folder fileEvery member of the organizationYesYes (files:read)
Open a signed link, or a variant of itAnyone who holds the link, until it expiresNot neededNot needed
Open a public link, or a variant of itAnyoneNot neededNot needed
Read a public link or its variant from a page on another websiteAnyoneNot neededNot needed
Make a file public or restrictedOwners and admins, in a browserYesNo
  • 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.
  • Making a file public is described in Sharing and public links.

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.
  • It has five kinds of addresses:
AddressWhat 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.
/z/{token}/{name}.zipA ZIP download. See Downloading.
  • {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.
  • 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.
  • 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.
  • How to ask for one is under 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.
  • 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.
  • 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.
  • 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:

HeaderValue
Content-TypeThe file's real type, found from its bytes when it was uploaded. Not the type the uploader claimed.
Content-LengthThe number of bytes in this answer.
Content-Dispositioninline or attachment, with the file's current name: inline; filename="hero.jpg"; filename*=UTF-8''hero.jpg.
ETagThe 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-Rangesbytes
Cache-Controlprivate, max-age={seconds} on a signed link. public, max-age=60, s-maxage=31536000 on a public link.
Cache-Tagtw-file-{fileID}, on a public link only.
X-Content-Type-Optionsnosniff
Content-Security-Policysandbox; default-src 'none'; style-src 'unsafe-inline'
x-request-idThe 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.

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, ICOSVG
MP4, WebMHEIC and HEIF
PDFPhotoshop (PSD, PSB) and raw photos
Every thumb, preview and playback renditionIllustrator, 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.

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.

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:

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

OptionMeaningValuesDefault
vVersion of the resizing rules.33
wGreatest 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
hGreatest 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
qQuality.A whole number from 1. It is raised to the next of the three levels 60, 80, 90. Anything above 90 becomes 90.80
fitHow the picture fills w by h.inside or coverinside
fOutput format.avif, webp, jpeg, png or autowebp
  • 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.
  • 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.
  • 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 forYou are redirected to
w=320v=3,w=320,h=0,q=80,fit=inside,f=webp
f=avif,w=320v=3,w=320,h=0,q=80,fit=inside,f=avif
w=319,q=77,v=3v=3,w=320,h=0,q=80,fit=inside,f=webp
w=700,h=500,fit=cover,f=jpegv=3,w=960,h=640,q=80,fit=cover,f=jpeg
w=5000v=3,w=2560,h=0,q=80,fit=inside,f=webp
v=1,w=320,h=0,q=80,fit=inside,f=webpv=3,w=320,h=0,q=80,fit=inside,f=webp
w=320,q=90,f=pngv=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.
  • 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,
    • 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

HeaderValue
Content-Typeimage/avif, image/webp, image/jpeg or image/png.
Content-LengthThe size of the variant.
ETag"sha256:{64 hex digits}" of the variant's own bytes.
Cache-ControlAs for the link: public, max-age=60, s-maxage=31536000 on a public link, private, max-age={seconds} on a signed link.
Cache-Tagtw-file-{fileID}, on a public link only.
X-Image-Width, X-Image-HeightThe size of the variant in pixels.
X-Image-Cachemiss when the variant was rendered for this request, hit when it already existed.
X-Content-Type-Optionsnosniff
  • 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.
  • 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.
  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:
HeaderValue
Access-Control-Allow-Origin*
Access-Control-Expose-Headersaccept-ranges, content-disposition, content-range, etag
Cross-Origin-Resource-Policycross-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:
HeaderValue
Access-Control-Allow-MethodsGET, HEAD
Access-Control-Allow-Headers*
Access-Control-Max-Age86400
  • 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.

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:

WhatWhere it comes from
A public linkpublicURL 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 linkworkspace.files.signed_url or library.files.signed_url, or thumbnailURL and previewURL on a file.
OperationCapability IDMCP toolScope
POST /v1/workspaces/{workspaceID}/files/{fileID}/versions/{versionID}/signed-urlworkspace.files.signed_urlworkspace_files_signed_urlfiles:read
POST /v1/organizations/{organizationID}/library/files/{fileID}/versions/{versionID}/signed-urllibrary.files.signed_urllibrary_files_signed_urlfiles: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 and MCP.
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"}'
{
  "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:

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

<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

<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

<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

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

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

<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

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

curl -s -o /dev/null -D - \
  "https://files.talewrightusercontent.com/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg" \
  -H 'If-None-Match: "sha256:9b1c7e0a4d2f58c36a1be07d94c5f2a8e6d3b0c1f7a9482e5d6c3b0a1f8e7d24"'
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

curl -s -o first-kilobyte.bin -D - \
  "https://files.talewrightusercontent.com/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg" \
  -H "Range: bytes=0-1023"
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

curl -s -o /dev/null -D - \
  "https://files.talewrightusercontent.com/_img/w=600,f=avif/p/3f9c2a71b84e4d0f9a6c5e1d7b2048ac/hero.jpg"
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

SituationWhat happensWhy
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 renamedOld links keep working. Content-Disposition carries the new name.Same reason.
A public file is replaced with a new versionThe 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 versionThe 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 minutes403 FORBIDDEN.It expired. Ask for a new one.
One character of a signed link's token is changed403 FORBIDDEN.An altered link is not valid.
A file is moved to the trash while someone holds a signed linkThe link answers 403 at once.Trashing stops every signed link of the file.
That file is restoredThe old signed link still answers 403.Restoring does not bring old signed links back. New ones work.
A public file is trashed and restoredThe public link answers 404 while trashed and works again after the restore, at the same address.See Sharing and public links.
A request carries the app's session cookieThe 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 AuthorizationIt 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 link304, 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 link304, 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-29200 with the whole content.Only one range per request is served.
Range: bytes=5-2 or Range: items=0-9200 with the whole content.A range that makes no sense is ignored.
Range: bytes=0-999999999 on a small file206 up to the last byte.The end is cut to the content's end.
Range starting at or past the file's size416 RANGE_NOT_SATISFIABLE with Content-Range: bytes */{size}.No byte of the range exists.
Range with If-Range naming an earlier version's tag200 with the whole current file.Parts of two versions must not be mixed.
Range with If-Range as a date or a weak tag200 with the whole current file.Only the exact current tag matches.
Range on a variant200 with the whole variant.Variants are always sent whole.
POST or DELETE on any files host address405 METHOD_NOT_ALLOWED.The files host only serves.
OPTIONS on a public link from any site204 with the allow headers.Other websites may read public files.
OPTIONS on a public link whose slug does not exist204 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 address405 METHOD_NOT_ALLOWED, no allow headers.Those are not readable from other websites.
A script on another site fetches a signed linkThe 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 link404, readable by the script.Refusals on public addresses carry the cross-origin headers too.
A variant is asked for with w=600308 to w=640.Widths are rounded up to the ladder.
A variant is asked for with w=4000308 to w=2560.2560 is the widest step.
w=640 on an original 612 pixels wideA 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 wideTwo addresses, both answering a 300-pixel picture.Same rule. Do not list steps above the original's width.
h=200308 to h=320.Heights use the same ladder as widths.
fit=cover without h, or with h=0422, "Invalid image options".A crop needs a height.
f=jpg422, "Invalid image options".The format is spelled jpeg.
q=100308 to q=90.90 is the highest level.
q=0, w=0 or v=0422, "Invalid image options".Only h may be 0.
f=png with q=60 or q=90308 to the same address with q=80.PNG has no quality, so it has one address.
v=1308 to v=3.An earlier version redirects to the current one.
v=4422, "Invalid image options".That version does not exist.
w=320,w=640, dpr=2 or W=320422, "Invalid image options".Each option once, known options only, lower case.
A variant address with ?width=300422, "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 exist404 NOT_FOUND.The link is checked before the options.
A variant of a public PDF, video, font or Photoshop file404 NOT_FOUND.Only the eight image types have variants.
A variant of a HEIC photoA WebP, AVIF, JPEG or PNG that every browser shows.HEIC and HEIF originals can be resized.
The public link of that HEIC photo itselfIt downloads as HEIC.Browsers do not show HEIC, so the original is an attachment.
A variant of an animated GIFA still picture of the first frame.Variants are stills. The original link serves the animation.
A transparent PNG as f=jpegTransparent areas are white.JPEG has no transparency.
A transparent PNG as f=webp, f=avif or f=pngTransparency is kept.Those formats carry it.
A photo with location data, as a variantThe variant holds no location and no other camera data.A variant is newly encoded. Only the original carries camera data.
A photo taken sidewaysThe 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=2560422, "The resulting image is too large". At w=1280 it works.The variant would pass 24 million pixels.
A very large picture as f=pngIt 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 MiBIts 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 pixels422, "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 fontsIt 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 addressIts 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 backslashSame.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 styleSame.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 fontSame.An SVG may only reference parts of itself.
f=auto from a browser that shows AVIF308 to the f=avif address.Its Accept names image/avif.
f=auto with Accept: */*, or from curl308 to the f=webp address.A wildcard does not count as asking for AVIF.
f=auto with Accept: image/avif;q=0, image/webp308 to the f=webp address.q=0 means "not this".
f=avif from a browser that cannot show AVIFAVIF 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 renderedEvery 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 momentThey 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 momentIt is rendered once and all twenty get it.Requests for the same new variant share one render.
A variant answered 503Nothing is kept. The next request is tried afresh.Refusals carry Cache-Control: no-store.
A variant of a signed link to a preview renditionThe 1,600-pixel WebP preview, resized again.A variant resizes what the link serves.
A file named a/b.jpgIts 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 deleted404. 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.

CodeStatusWhenWhat to do
FORBIDDEN403A 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_FOUND404A 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_ALLOWED405Any method other than GET and HEAD. OPTIONS on anything but a public link or its variant.Use GET.
RANGE_NOT_SATISFIABLE416A 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"422The options part of a variant address breaks a rule. details.field is options.See Options.
VALIDATION_FAILED, "Image addresses have no query"422A variant address has a ?. details.field is image.Put options in the path.
VALIDATION_FAILED, "Source must be a file delivery path"422What 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"422The 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"422The 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"422The 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"422The 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_UNAVAILABLE503The 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_OUT503Decoding 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.
TIMEOUT503The request ran past its time limit.Ask again.
INTERNAL500An unexpected failure on our side.Ask again. Quote the requestID if it persists.

See Errors on the files host and Errors for the shape of every error.

Limits

WhatValue
Lifetime of a signed link10 minutes
Lifetime of thumbnailURL and previewURL10 to 15 minutes; the same link within five minutes
Browser cache of a public link or its variant60 seconds (max-age=60)
Longest a CDN may keep a public answer1 year (s-maxage=31536000), dropped earlier when the link's content changes
Browser cache of an f=auto redirect on a public link1 day (max-age=86400), browser only
Cache of a gallery page60 seconds, browser and CDN
How long a browser may remember a preflight1 day (Access-Control-Max-Age: 86400)
Byte ranges per request1
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 addressUp to 160 characters; numbers of 1 to 6 digits
Source types with variantsJPEG, PNG, WebP, AVIF, GIF, SVG, HEIC, HEIF
Largest original that can be resized64 MiB; an SVG 2 MiB
Largest picture that can be resized100 million pixels and 16,384 pixels a side
Largest SVG that can be resized10,000 elements, nested 128 deep
Largest variant24 million pixels and 16 MiB
Longest render15 seconds, then 503
Longest wait for a render to start5 seconds, then 503
Thumbnail (thumb) and preview (preview) renditionsWebP that fits 320 and 1,600 pixels

More limits of downloads and delivery are in Limits.

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.

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.

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

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.

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.