Skip to content

Token image converted to a specific format via path extension

GET
/image/{chainId}/{address}.{ext}
curl --request GET \
--url 'https://gib.show/image/eip155-369/0xA1077a294dDE1B09bB078844df40758a5D0f9a27.png?bg=ffffff&shape=circle&contrast=dark'

The extension converts the output, equivalent to ?as=. Requesting .svg when the token has no SVG source responds 404; extensions outside the supported set (e.g. .bmp) respond 406.

chainId
required
string

Chain identifier — prefixed form (eip155-369) or bare numeric (369). Chain 0 uses the asset namespace (asset-0). Algorand ARC-25 ids 4160 and 416001 (bare or eip155-) are aliases of algorand-283.

address
required
string

Token contract address (checksummed or lowercase).

ext
required
string
Allowed values: png webp jpg avif svg

Output format. SVG output requires an SVG source.

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.

Media type: image/*
string format: binary

No matching image.

Media type: application/json
object
error
string

Example generated

{
"error": "example"
}

Unsupported output extension (e.g. .bmp).

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"
}