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
| 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:writeincludesfiles: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
GETandHEAD. Any other method on one of its addresses answers405 METHOD_NOT_ALLOWED. The one exception isOPTIONSon a public link or its variant, described under 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. |
/z/{token}/{name}.zip | A 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.jpghas links that end ina%2Fb.jpg. - A refusal has the same JSON body as an API error, with a
requestID. See The error envelope. - Every refusal (any
4xxor5xxanswer) carriesCache-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.
- How to ask for one is under For agents. The API also puts
ready-made signed links on a file:
thumbnailURLandpreviewURL, eachnulluntil 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.
- 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:
| 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-Dispositionis the file's current name, whatever name the address ends in. - A
thumb,previeworplaybacksigned link names its answer after the file with the rendition's extension: the thumbnail ofhero.pngishero.webp. nosniffand 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, ICO | SVG |
| MP4, WebM | HEIC and HEIF |
| 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.
Conditional requests
- A public link and a signed link answer
304 Not Modified, without a body, when the request'sIf-None-Matchnames the currentETag. - The
304carries theETagand the sameCache-Control. On a public link it also carries theCache-Tag. If-None-Matchmay 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
ETagchanges. A request with the old tag then gets the new bytes with200. - A signed link names one version, whose bytes never change. Its
ETagmatches for as long as the link works. A link that no longer works answers403whatever the request sends. - Image variants answer
304on 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 ContentwithContent-Range: bytes {start}-{end}/{size}. - Three forms are understood:
bytes=0-99(from, to, both included),bytes=100-(from there to the end) andbytes=-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, answers416 RANGE_NOT_SATISFIABLEwithContent-Range: bytes */{size}anddetails.sizeBytes. - A
Rangeheader the files host does not understand is ignored and the whole content is sent with200: several ranges in one header (bytes=0-9,20-29), another unit thanbytes, a start after the end, or anything malformed. If-Rangemakes a range conditional. The range is served only whenIf-Rangeis exactly the currentETag, quotes included. With any other value the whole current content is sent with200: an earlier version's tag, a weak tag (W/...) or a date. NoLast-Modifiedis 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
Rangeand 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 withIf-None-Matchand usually gets a short304.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,206and304answers, 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 off=auto, below. - A gallery page carries
Cache-Control: public, max-age=60, s-maxage=60andCache-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 ofkey=valuepairs 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
404the 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 |
vis 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 withoutv, or with an earlier number, redirects to the current one.v=0or a number above the current one is refused.wandhare upper bounds, not exact sizes. The picture is never made larger than the original. See What a variant looks like.wis always in effect. An address withoutwmeansw=1280.fit=insidescales the picture down until it fits insidewbyh, keeping its proportions. Nothing is cut off. Withh=0only the width limits it.fit=coverscales the picture down until it coverswbyhand cuts off what sticks out, around the centre. The result always has the shape ofwbyh. It needs a height:fit=coverwithh=0, or withouth, is refused.qhas three levels: 60 (smaller files), 80 (the default) and 90 (closer to the original). PNG output is lossless and has no quality: forf=pnganyqis accepted and the address always spellsq=80.fnames the format of the answer.jpegis spelledjpeg, notjpg.autopicks AVIF or WebP for the browser that asks. Seef=auto.- Numbers are 1 to 6 digits.
- Keys and values are lower case.
W=320andf=WEBPare refused. - An option given twice, an unknown option (there is no
dpr, nocrop, noblur) 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_FAILEDwith 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 Redirectto the canonical address. That covers options in another order, options left out, values that get rounded, an earliervandf=auto. - The
Locationof 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=avifworks 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'sCache-Tag. On a signed link it isprivate, 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=autonever answers a picture. It always redirects, tof=avifor tof=webp.- It redirects to
f=avifwhen the request'sAcceptheader namesimage/avif, in any letter case and not withq=0. Otherwise it redirects tof=webp. - Wildcards do not count.
Accept: image/*or*/*, or noAcceptat 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=86400on a public link (one day), andprivatefor the rest of the link's lifetime on a signed link. - A CDN therefore never keeps the
f=autoredirect, 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=avifanswers AVIF to every client, whether it can show it or not. - A browser's
<img>names the formats it shows inAccept. A script'sfetchsends*/*unless you set the header, sof=autogives 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'sthumborpreviewsigned 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
thumborpreviewcan be resized again. One to aplaybackrendition is a video and answers404. - An SVG is turned into pixels. Only static SVG can be resized:
- at most 2 MiB, in UTF-8, with
svgas 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,patternandstyle, - without a
DOCTYPE, processing instructions,<script>elements, event attributes such asonload, embedded images orforeignObject, - 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:spaceandxml:lang.xml:baseand 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.
- at most 2 MiB, in UTF-8, with
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.
- painting:
- Any other property refuses the SVG, for example
filter,animation,background,font,cursororcontent. - 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()andskewY(). - Any other function refuses the SVG, for example
calc(),image-set(),expression(),attr()orenv(). url()is accepted only as a reference to a part of the same file, written exactlyurl(#id): no quotes, no spaces, nothing before the#.- A quoted string is accepted only as a font name, in
font-familyand-inkscape-font-specification. It must stay on one line. !importantis accepted.- A custom property takes the same values as any other property.
@mediais 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, andurl(that is noturl(#id). <style>may hold its CSS as plain text or in aCDATAsection. An XML comment or an element inside<style>refuses the SVG.- Upper and lower case do not matter:
FILL:REDis read asfill:red, and@IMPORTis refused like@import. - Accepted is not always applied. Rules inside
@mediaand values that usevar()are accepted, but the resizer does not apply them: the shape is drawn as if that rule or declaration were not there. Acolor()value is skipped the same way, so a colour written twice, first as#rrggbband then ascolor(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=640comes out 612 pixels wide.X-Image-WidthandX-Image-Heighton the answer say what you got. - Proportions are kept with
fit=inside. An original of 1,200 by 800 atw=320comes 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 atw=320,h=320comes 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 atw=320,h=320comes out 300 by 300, and atw=960,h=640it 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-Typeof the answer isimage/avif,image/webp,image/jpegorimage/png, whatever the name at the end of the address says..../hero.jpgwithf=webpis 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 ModifiedwhenIf-None-Matchnames itsETag, 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-Rangesand ignoresRange. - A variant has no
Content-Dispositionand noContent-Security-Policy. It is a picture to show, opened directly it shows in the browser. HEADanswers the same headers without the picture.- A variant of a public link also carries the headers under Use from other websites.
hitormissmakes no difference to the picture. When several people ask for the same new variant at the same moment, it is rendered once: one answer saysmiss, the othershit.
Checks, in order
A request for a variant is checked in this order. The first check that fails decides the answer:
- The address has a query string:
422 VALIDATION_FAILED, "Image addresses have no query". - 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. - The link does not work:
403 FORBIDDENfor a signed link,404 NOT_FOUNDfor a public link. - The file is not of a type that can be resized:
404 NOT_FOUND. - The options are not valid:
422 VALIDATION_FAILED, "Invalid image options". - The options are valid but not canonical:
308to the canonical address. - The original is larger than 64 MiB:
422 VALIDATION_FAILED, "Image source exceeds 64 MiB". - The original is over a size limit:
422 VALIDATION_FAILED, "Image source exceeds 16,384 pixels a side or 100 million pixels". - 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. - 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. - Decoding and resizing took longer than 15 seconds:
503 UNAVAILABLEwithdetails.reasonIMAGE_RENDER_TIMED_OUTandRetry-After. See When the resizer is busy. - Otherwise the variant is answered:
200, or304for a matchingIf-None-Match.
- Because the link is checked before the options, an address with nonsense
options on an unknown or restricted public link answers
404, not422. - 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=covernever 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 UNAVAILABLEwithdetails.reasonIMAGE_SERVICE_UNAVAILABLE, the message "Temporarily unavailable; try again shortly" and aRetry-Afterheader in seconds, at least 1. - A render that runs out of its 15 seconds answers the same way, with
details.reasonIMAGE_RENDER_TIMED_OUTand aRetry-Afterof 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
503is 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 inonerror, 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, the308redirects of variants and every refusal, the404of an unknown link included. A script on another site can therefore read why a request failed, and a cross-originfetchcan 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 answers204with 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
204for any slug, known or not. The request that follows gets the real answer. *never allows credentials. No answer carriesAccess-Control-Allow-Credentials, and cookies are ignored anyway. Afetchwithcredentials: "include"is refused by the browser; leave credentials out.- A script can read these response headers across origins:
ETag,Content-Range,Accept-RangesandContent-Disposition, next to the ones every browser exposes, such asContent-TypeandContent-Length. Other headers are not readable by a script on another site:X-Image-Width,X-Image-Height,X-Image-CacheandCache-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
OPTIONSon them answers405 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.comare 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 thethumbrendition. - The preview on a file's page is its
previewURL, a signed link to thepreviewrendition. 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
playbackrendition 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:
| 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"}.variantisoriginal,thumb,previeworplayback. - The answer is
{"url": "...", "expiresAt": "..."}.urlis 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.
Worked example: a signed link, then a variant of it
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.
Building a variant address from a public link
- Read the file and take
publicURL. If it isnull, the file is not public: an owner or admin makes it public in the app. - Split it after the host:
https://files.talewrightusercontent.comand/p/{slug}/{name}. - Put
/_img/{options}between the two. - 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
wdescriptor would then promise more pixels than the picture has. Here the original is 2,400 wide, so2560is left out. widthandheightare 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>whosetypeit 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=coverfills 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
insidevariant and crop it in CSS withobject-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:
<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.
crossoriginon the preload is required, or the browser fetches the font twice.- A font opened directly downloads. Used in
@font-faceit 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
credentialsand nomodeare 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
| 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. |
| 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. |
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 and Errors 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.
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.