Image options
These options apply to the token image routes. The resize and format options also work on the network image route and on /image/direct/{imageHash}.
Options
Section titled “Options”| Parameter | Type | Default | Description |
|---|---|---|---|
w |
integer, 1 to 2048 | none | Target width in pixels. |
h |
integer, 1 to 2048 | none | Target height in pixels. |
as |
string | original format | Output format: webp, png, jpg, jpeg or avif. svg succeeds only when the stored image already is a vector image. Against a raster source it answers 404. Any other value is ignored, and Gib serves the original format. |
format |
string | none | A deprecated alias for as. An earlier version of the documentation used this name. When both are present, as wins. |
only |
vector or raster |
none | Keep only source images of this type, before Gib chooses one. |
providerKey |
string | none | Use only these providers, for example trustwallet or coingecko. Separate several with commas. |
listKey |
string | none | Use only these list keys. Separate several with commas. |
license |
string | none | Allow only images with these licences. See Ask for licensed artwork only. |
bg |
hex colour | none | Paint a plate behind the logo. See Put a logo on a plate. |
shape |
circle, rounded or square |
circle |
The outline of the plate. |
contrast |
dark or light |
none | Add a plate only when the logo is hard to see on a dark or light page. |
mode |
link |
none | With mode=link, Gib answers 302 and redirects to the original source address instead of sending the image. Without it, Gib sends the image bytes. |
How resizing works
Section titled “How resizing works”walone resizes in proportion.halone resizes in proportion.wandhtogether fit the image inside those bounds and keep the aspect ratio.- Gib never enlarges an image. If the source is smaller than you asked for, you get the original.
- A vector image (
svg) that has aviewBoxpasses through unchanged. It is already independent of resolution. - A vector image without a
viewBoxis rasterised topng. aswithoutworhconverts the format and keeps the original size.
Put a logo on a plate
Section titled “Put a logo on a plate”Some logos are dark and almost vanish on a dark page. Add a plate, a solid shape behind the logo, to fix that. Three parameters control it. They work on every image route.
bgis the plate colour. Write 3, 6 or 8 hex digits without#. Eight digits end with alpha, so00000080is half-transparent black. Any other value answers 400.shapeis the outline:circle(the default),roundedorsquare. It has an effect only together withbgorcontrast. On its own it is checked, so a typo still answers 400, and then ignored.contrasttells Gib what your page looks like:darkorlight. Gib draws the logo small and checks each visible pixel against a typical page of that tone. A pixel stands out when its contrast ratio is at least 3:1, the minimum the Web Content Accessibility Guidelines set for graphics. Gib adds a plate in the opposite tone (white on a dark page, near-black on a light page) only when fewer than a quarter of the visible pixels stand out. A logo with some strong parts, such as a coloured disc with a white symbol, is served unchanged.
When you send bg and contrast together, bg is the plate colour and contrast decides whether the plate appears. With bg alone the plate is always drawn.
# Add a light plate only if the logo is too dark for a dark pagecurl "https://gib.show/image/25?contrast=dark"
# Always paint a white rounded platecurl "https://gib.show/image/25?bg=ffffff&shape=rounded"
# A plate drawn to pixels, 128 by 128, as webpcurl "https://gib.show/image/25?bg=ffffff&as=webp&w=128"How the plate is drawn:
- A vector image with a
viewBoxstays a vector. The answer isimage/svg+xml: a new image with the plate behind and the original inside it, centred. Gib adds nothing from your query to it except the validated colour.wandhhave no effect on a vector, as before. - Any other source, or any request with
as, is drawn to pixels. The plate is a square,wbyw(or the smaller ofwandh). Without a size, a vector source is drawn 256 pixels wide and a raster source keeps its size plus room for the padding. The logo is fitted inside the shape with space around it, more forcirclethan forsquare, and is never enlarged. A circle or rounded plate has transparent corners, except injpg, which has no transparency and gets white corners. - A vector without a
viewBoxis drawn to pixels aspng, because it has no size to nest it by. - A plate is never wider than 2048 pixels, the same limit as
wandh. A raster source so large that its own size plus padding passes 2048 is drawn at 2048, with the logo shrunk to fit. - Gib does not store plated images, and a plated request never receives a plain image or the other way round. The response
ETagfollows the bytes, and the logo’s brightness is measured once and remembered by the server. If Gib cannot decode a source to measure or draw it, you get the plain image withcache-control: no-store, so a cache does not keep the plain image in place of the plate. A logo kept at a remote address (a linked image) is read by Gib for the plate, up to 512 KB, and is cleaned before it is drawn; a larger file, or one that cannot be read, is redirected to its own address. - Any request with
bg,shapeorcontrastcarries the shortercache-controllifetime, including on/image/direct/{hash}, and also whencontrastfinds no plate is needed. The year-long immutable lifetime is for bytes that cannot change, and the answer to a plate request depends on how Gib draws plates. as=svgtogether with a plate gives a vector only for a vector image that has a usableviewBox. For any other source the answer is 404, not a png.- Drawing is limited, because it is done on demand. Each image may have 30 plated draws a minute, each caller 120, and the whole service 600; past that the answer is 429 with
Retry-After: 60. A caller is named by its network address. When too many plates are being drawn at once, or one caller already has four waiting, the answer is 503 withRetry-After: 2. A request that needs no plate (for examplecontraston a logo that is already easy to see) spends nothing and never waits behind a draw. Neither answer is cached. An edge cache that holds the full address, query included, answers repeat requests for the same plate without reaching Gib, so a page that shows the same plates again and again does not spend this allowance. - A source that asks that its artwork is not copied is redirected, as described above. It gets no plate.
Response headers
Section titled “Response headers”| Header | Meaning |
|---|---|
x-resize |
original when no resize was applied. WxH (for example 72x72) when the image was resized to those dimensions. transcoded when only the format changed. |
x-source-uri |
The address of the original source file. |
x-uri |
The same value as x-source-uri. It is kept for older callers. |
x-provider |
The key of the collector that supplied the image. |
x-provider-name |
The display name of that provider. |
x-license |
The licence Gib identified, or unknown. |
x-license-url |
Where to read that licence. Sent only when the licence is known. |
x-attribution |
The notice you must reproduce, when the licence requires one. |
content-security-policy |
default-src 'none'; img-src data:; style-src 'unsafe-inline'; sandbox, on every response that carries image bytes. A stored vector image comes from outside, so a browser that opens it directly must not run anything in it. Images shown in an img element or as a CSS background are not affected. |
x-content-type-options |
nosniff, on every response that carries image bytes. |
link |
A link to the licence terms page of the instance. On the public instance it is https://gib.show/terms. |
x-resolved-chain |
Network image route only. The prefixed identifier the request resolved to. |
cache-control |
See Caching. |
link and x-license are always present. The other provenance headers appear when the information is known. Browser code can read them across origins.
When a source asks that its artwork is not copied, Gib stores only the address and answers with a redirect to the source. Those responses carry the same provenance headers. A resize or a format change is also a copy, so for these sources w, h and as have no effect: you get the redirect.
Read the terms page of the instance you use for what you must do with each licence. The public instance publishes them at gib.show/terms. A licence on a file is not a licence to a trademark.
Ask for licensed artwork only
Section titled “Ask for licensed artwork only”Add license to any token or chain image route to receive only artwork under licences you accept. The value is matched without regard to case. Repeat the parameter or separate values with commas:
curl "https://gib.show/image/1/0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599?license=MIT&license=Apache-2.0"curl "https://gib.show/image/1/0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599?license=MIT,Apache-2.0"When you send license:
- Only images whose effective licence is in your set are candidates. The effective licence is the one on the list entry itself, checked against where the image actually lives. It is never a provider’s licence by default.
- Gib serves the best-ranked image among those candidates. You do not get a miss just because a higher-ranked image was unlicensed.
- A licence that Gib has not verified is
unknown. Unknown is never treated as permitted, so it never matches. - When no candidate qualifies, you get the ordinary 404 answer for the route. You never get an unlicensed image.
Sprite sheets
Section titled “Sprite sheets”A sprite sheet combines many images from many sources, so it cannot carry one image’s licence. It carries only the link to the terms page. See Sprite sheets.