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 API 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
:api Optional. The version number of the API, preceded by the letter "v". If :api is omitted, the most recent API version will be used. The most recent version is v1. v1
: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 2500×2500. 300x250, 50x
:alpha Optional. An integer value from 0 – 100, followed by the letter "a". If the requested filetype (:ext) supports transparency, the image will return with this alpha transparency. If :alpha is omitted, the image will be 100% opaque, unless :color is "spacer", which will a return 100% transparent asset regardless of :alpha. 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
:ext 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. Here is an example with all parameters in use:

<img src="">

Improving Accessibility

Images used for formatting— or that would be invisible to everyone— must be implemented in a way that can be ignored by assistive technology. Add the attribute aria-hidden="true" to improve the experience of assistive technology users. Declare an empty alt attribute to silence older screen readers.

<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.

API Status

While we strive for maximum uptime, sometimes unexpected things happen. Outage incidents and uptime reports can be checked on our status page at UptimeRobot.