Skip to content

Image by content hash — content-addressed access

GET
/image/direct/{imageHash}
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.

imageHash
required
string

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.

as
string
Allowed values: webp png jpg jpeg avif

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.

format
deprecated
string
Allowed values: webp png jpg jpeg avif

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.

w
integer
>= 1 <= 2048

Resize width in pixels (1-2048), fit inside, never enlarged.

h
integer
>= 1 <= 2048

Resize height in pixels (1-2048), fit inside, never enlarged.

bg
string
/^([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/

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.

shape
string
default: circle
Allowed values: circle rounded square

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.

contrast
string
Allowed values: dark light

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.

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.

Media type: image/*
string format: binary

No matching image.

Media type: application/json
object
error
string

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.

Media type: application/json
object
error
string

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.

Media type: application/json
object
error
string

Example generated

{
"error": "example"
}