Image by content hash — content-addressed access
const url = 'https://gib.show/image/direct/example?as=webp&format=webp&bg=ffffff&shape=circle&contrast=dark';const options = {method: 'GET'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://gib.show/image/direct/example?as=webp&format=webp&bg=ffffff&shape=circle&contrast=dark'The hash in the path names one download, so the response at a given address does not change for a raster image — a resized or transcoded variant of it is equally fixed. Because of that, a raster image here has a year-long cache: cache-control: public, max-age=31536000, immutable, in place of the shorter, configured lifetime every other route serves. A vector image (a stored .svg) gets the ordinary lifetime instead, because the operator command images resanitize can rewrite its bytes under the same address when the sanitizer is fixed. Callers making many requests for the same set of images should cache through this route rather than re-fetching by chain and address.
Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Content hash from list/token logoURI fields. A bare hash serves the stored image; an extension suffix (e.g. {hash}.svg) is a source filter — 404 when the stored image is not of that type.
Query Parameters
Section titled “Query Parameters”Convert output format. Requesting svg succeeds when the stored image already is one and is served unchanged; against a raster source it returns 404, because a raster image cannot be converted to a vector one. Every other unrecognised value is ignored and the original format is served.
Deprecated alias for as, kept because an earlier version of the published documentation named the output-format parameter format. Prefer as; when both are present as wins.
Resize width in pixels (1-2048), fit inside, never enlarged.
Resize height in pixels (1-2048), fit inside, never enlarged.
Paint a plate of this colour behind the logo: 3, 6 or 8 hex digits without #, the last two of eight being alpha (for example ffffff, f80, 00000080). Any other value answers 400. A vector image stays a vector (image/svg+xml) unless as asks for pixels. With as=svg, a vector image that has no usable viewBox cannot take a plate as a vector, and the answer is 404 and not a png. A plate drawn to pixels is never wider than 2048 pixels: a larger logo is shrunk to fit. With contrast as well, bg is the plate colour and contrast decides whether the plate appears.
The outline of the plate. Only used together with bg or contrast; on its own it is checked and then ignored. Any other value answers 400.
Say whether your page is dark or light. Gib looks at what share of the visible pixels of the logo have at least 3:1 contrast with that page, and adds a plate in the opposite tone (light on dark, dark on light) only when that share is under 25 percent, so a logo with some strong parts is left alone. Otherwise the image is served as if the parameter were absent. If the logo cannot be measured, the plain image is sent with cache-control: no-store. Any other value answers 400.
Responses
Section titled “Responses”Image content. Headers: cache-control (public, max-age=86400 with a seven-day stale-while-revalidate and stale-if-error window; year-long immutable for a raster image at /image/direct/{hash}; a vector image there uses the ordinary lifetime), x-resize (original or variant), x-uri (source when known). Every image response also carries content-security-policy (default-src ‘none’; img-src data:; style-src ‘unsafe-inline’; sandbox) and x-content-type-options: nosniff, so an image opened directly in a browser cannot run a script. A request that carries plate parameters (bg, shape or contrast) always uses the shorter lifetime, on every route, even when no plate was needed, because its answer depends on how Gib draws plates. When a plate was asked for and could not be produced (the logo cannot be measured or drawn), the plain image is sent with cache-control: no-store. cache-control: public, max-age=31536000, immutable for a raster image; the ordinary lifetime for a vector image.
No matching image.
object
Example generated
{ "error": "example"}Plated images (bg or contrast) are drawn on demand and never stored, so each image has an allowance of 30 per minute, each caller 120 and the whole service 600. A caller is named by its network address, or by the address a trusted proxy reports; behind a proxy that cannot be told apart, only the other two apply. A linked image is not downloaded for a refused request. Retry-After says how long to wait (60 seconds); the answer is never cached.
object
Example generated
{ "error": "example"}Too many plated images are being drawn at once, or this caller already has four waiting. Retry-After says how long to wait (2 seconds); the answer is never cached. Plain images, resizes, and requests that need no plate are not affected.
object
Example generated
{ "error": "example"}