Simple. Fast. Images. For Developers

Overview

Current Version

The current version of the API is v1. This is also the default version if no version is specified. A specific version should be specified using the x-img-api-version HTTP header.

As new versions of the API are released, the default version will change. So it is recommended to specify the desired version using the x-img-api-version HTTP header.

Schema

All API access is over HTTPS. The base URL for all request is http://img.local:2001.

Unsecure requests made to http:// (note the missing s) will be dropped. These unsecure requests will not be redirected to https://.

Dates

All dates are represented in ISO 8601 format e.g. 2011-07-10T18:35:16-0800.

Authentication

Requests are authorized using your API key. API keys can be specified in the following ways:

As a URL query parameter named api-key e.g. http://img.local:2001?api-key=${your-api-key}
As a cookie named img
As an HTTP header named x-img-api-key

IDs

Every image has an ID assigned by Img. These IDs are 16 character strings made up of lowercase ASCII letters and digits e.g. 7hci0z8txgvzkgkl.

In the future, assigned IDs may be as long as 48 characters.

You can optionally assign an image a custom ID. Custom IDs must be unique across all images in your account and must contain only

ASCII letters (a-zA-Z)
digits (0-9)
- (minus sign/hyphen)
_ (underscore)

Custom IDs can be up to 64 characters in length.

Supported image formats

Images

There are three considerations when creating images:

Do you want to use your own custom IDs, or do you want to use the Img assigned IDs?
Do you want to serve images immediately after the creation/upload process?
How do you want to upload the image? Public URL, file upload, or base64 encoded.

Upload

POST /image

You may specify a custom ID. See below for instructions.

File Upload

JSON

Form

Receive ID, then Upload

Uploading images can take a long time. Because of this, we offer an option where one can begin serving images even before an image is completely uploaded (of course, the request will block until the image is completely uploaded). To do this, one must

Get an pre-allocated ID (custom or assigned)
Use this ID to build an image URL (see Serving Images below)
Upload the image using the ID from step 1

Get an pre-allocated ID

GET /image/new-id

GET /image/new-id/{custom-id}

Returns an ID that can be used to create an image.

The first endpoint /image/new-id will return an assigned ID. the second endpoint /image/new-id/{custom-id} will allow one to use a custom ID.

Upload an image with a pre-allocated ID

POST /image/{id}

POST /image/{domain}/{custom-id}

{id} or {custom-id} must be an pre-allocated ID received from one of the GET /image/new-id or GET /image/new-id endpoints.

Serving Images

Images are served using a URL generated from the image's ID (assigned or custom). To generate an image URL, use the following patterns

https://img.local:2000/image/{id}
http://img.local:2000/image/{id}
https://img.local:2000/image/{domain}/{custom-id}
http://img.local:2000/image/{domain}/{custom-id}

Transformed Images

Delete

DELETE /image/{id}

DELETE /image/{domain}/{customId}

Name	Required?	Type	Description
url	Yes	String	Publicly accessible URL of image.
my-id	No	String	User specified ID

Get ID

GET /id

Returns an ID that can be used to create an image. (An ID is a 16 character string made up of lowercase ASCII letters and digits.)