The image API allows for the creation of custom spacer images by specifying size, color, opacity, and filetype. The request URL can be used— most often as the source in an HTML image tag— wherever an image resource is required.

Making Requests

Requests to the API can be made as GET requests to the URL, followed by image parameters.


Non-versioned and Legacy Requests

API requests made to (without the img subdomain or API version) will automatically be redirected to the most recent API version and processed accordingly.

Request Parameters

Parameters are appended to the URL in the same way as a typical file path. They are order-dependent and not case sensitve. If optional parameters are omitted, they will be interpereted as their defaults.

Parameter Description/Defaults Examples
:size Optional. A size in "width"×"height" format. Height is optional. If height is omitted, the spacer image will be a square. If :size is omitted, the image will be 1×1. Maximum size is 2000×2000. 300x250, 50x
:alpha Optional. Any value from 0 – 100, followed by the letter "a". If :alpha is omitted, the image will be 100% opaque (unless :color is "spacer", which will always return 100% transparent). GIF, JPG and BMP filetypes will return 100% opaque for any alpha > 0. 95a, 46a
:color Required. A color hex value or CSS color keyword. Or, to get a transparent image, set the parameter to "spacer". ff00ff, magenta, spacer
:extension Required. The extension of the desired filetype of the image. Available filetypes are GIF, PNG, JPG, BMP, WEBP and SVG. .gif, .png

Example Use

Typically, combine the parameters with the request URL and use it in an HTML image tag.

<img src="">


Add the attribute aria-hidden="true" to improve the experience of assistive technology users. Declare an empty alt attribute to silence errant screen readers and satisfy HTML validation— required in some email builders.

<img src="" aria-hidden="true" alt="">

Example Requests

Get a 25×25, transparent, spacer GIF file:

Get a 50% opacity, 1×1, purple PNG file:

Get a 30×50, 75% opacity, #c0ffee SVG file:

Response Codes

  • 200 OK: The image request was successful and the image resource is available at the URL.
  • 400 Bad Request: One or more parameters are invalid, check for the correct order and syntax.
  • 404 Not Found: The request URL is incorrect. Double check the URL and API version.
  • 405 Method Not Allowed: Only GET requests are allowed.
  • 500 Error: The API has encountered an error while handling the request.