Lightspun.com

DOCUMENTATIONAPI Pricing Performance Security FAQ

Basic Request Format

Requests should be made to:

http://img.lightspun.com/

with parameters specified below. Usually, requests would be made from an img tag, but can be made in other ways too if needed. See the examples section.

Command Parameters

One or more of the following command parameters must be included. Multiple commands can be combined, though the resize and thumbnail commands cannot be used together.

flip=X

where X is one of: horizontal, h, vertical, or v

format=F

where F is a supported format: gif, jpg, tif, png, png8, png24, or png32

resize=WxH

where W and H are pixel dimensions and are separated by an "x" (e.g., "75x200"). See the description of the shape parameter for a discussion of what happens when you resize the image to a different aspect ratio.

rotate=D

where D is between -360.0 and 360.0 but not 0

thumbnail=WxH

Required Parameters

key=K

where K is your API key

src|source=URL

where URL is a URL to an image on your server

Optional Parameters

background=C

where C is a color in hex notation without a hash symbol (e.g., "ff00ff"), or a color in rgb syntax (e.g., "rgb(255, 0, 255)") or in argb syntax to specify the alpha transparency level (e.g., "argb(175, 255, 0, 255)"). This is used when rotating an image to a non-right-angle (unless the image type is PNG) or when resizing an image with the pad option.

cache=S

where S is either url or none

This parameter determines whether or not to cache the transformed image. Specifying url means that the image will be cached based on the URL (so if the image changes but the URL doesn't, the original version may be returned). Specifying none means that no caching will take place. Other caching mechanisms may be supported in the future. This value defaults to url when the request is a GET and to none when the request is a POST.

quality=Q

where Q is an integer between 0 and 100. This is the compression quality and is only allowed for JPG images. 0 is the lowest image quality and highest compression, and 100 is the highest image quality and least compression. By default, the quality is guessed based on the estimated quality of the input file.

progressive=P

where P is either true or false. If true, the image is converted to a progressive JPEG. If false, the image is converted to a non-progressive JPEG. If not supplied, the image's progressiveness will be left alone.

This parameter is only valid for files whose format is set to JPEG.

shape=S

where S is one of: preserve, cut, or pad

This parameter is used when resizing an image to determine what to do if the requested aspect ratio does not match the original aspect ratio.

preserve means that the original image's aspect ratio is kept, regardless of the aspect ratio declared by the W and H parameters.

cut means that the new image will have the exact size declared by the W and H parameters and that whatever doesn't fit gets cropped.

pad means that the new image will have the exact size declared by the W and H parameters and the new image will have some padding if the original aspect ratio doesn't match the new aspect ratio. Use the background parameter to specify the background color to use when padding. If you want the background to be transparent, omit the background parameter and set the format to png.

For the resize command, shape defaults to preserve and for the thumbnail command, it defaults to cut.

signature=S

where S is the HMAC-SHA1 signature of your request. This parameter is required if you have set "Signature Required" in your account settings. See the Security section of the documentation for more details.

Optional S3-Related Parameters

destination-s3-key=KEY

where KEY is the Amazon S3 key (a.k.a. file path) under which the transformed image should be stored

If this parameter is specified, the destination-s3-bucket parameter must also be specified.

Additionally, you are strongly encouraged to specify destination-s3-owner-id and destination-s3-owner-display-name. Failure to specify those parameters will result in your transformed files having undesirable S3 permissions.

destination-s3-bucket=BUCKET

where BUCKET is the Amazon S3 bucket into which the transformed image should be stored

If this parameter is specified, the destination-s3-key parameter must also be specified.

destination-s3-host=HOST

where HOST is the name of the S3 host. Valid values include s3-us-west-1.amazonaws.com (US-Northern California), s3-eu-west-1.amazonaws.com (EU-Ireland), and s3-ap-southeast-1.amazonaws.com (APAC-Singapore).

This parameter is not required for buckets in the US Standard region. It is required when your bucket is in any other region.

destination-s3-owner-id=ID

where ID is the bucket owner's AWS Canonical User ID, which can be found on the AWS Security Credentials page.

This parameter is strongly encouraged if any of the other destination-s3-* parameters are specified. Failure to specify this parameter will result in your transformed files having undesirable S3 permissions.

Additionally, this parameter is required if destination-s3-owner-display-name is specified.

destination-s3-owner-display-name=NAME

where NAME is the bucket owner's Amazon.com (not AWS) profile name, which can be found on the Amazon.com profile page page.

Additionally, this parameter is required if destination-s3-owner-display-id is specified.

destination-s3-public-read=R

where R is true if the file should have public-read permissions, or false if not.

This defaults to true.

This parameter can only be specified if destination-s3-owner-display-name and destination-s3-owner-id are specified.

Supported File Formats

Source images can be PNG, JPEG, GIF, TIFF or PDF format. Images can be converted to any of those formats except for PDF.

Supported HTTP Request Methods

Currently, only HTTP GET requests are allowed. HTTP POST requests (for form uploads) are coming soon.

Obfuscated Query Strings

If you wish, you may obfuscate your request by using the underscore parameter. The value of the parameter should be your query string after it has been URL-encoded and Base64-encoded.

Note that the obfuscated query string can be easily decoded by others. This feature is not intended to provide any sort of security.

For example, starting with this URL:

http://img.lightspun.com/?src=http://example.com/dog.jpg&resize=10x10

Take just the query string:

src=http://example.com/dog.jpg&resize=10x10

And Base64 encode it:

c3JjPWh0dHA6Ly9leGFtcGxlLmNvbS9kb2cuanBnJnJlc2l6ZT0xMHgxMA==

And then URL encode that:

c3JjPWh0dHA6Ly9leGFtcGxlLmNvbS9kb2cuanBnJnJlc2l6ZT0xMHgxMA%3D%3D

And then create a new query string, assigning the encoded value to the _ param:

http://img.lightspun.com/?_=c3JjPWh0dHA6Ly9leGFtcGxlLmNvbS9kb2cuanBnJnJlc2l6ZT0xMHgxMA%3D%3D

Error Codes

400

The source URL was not found

401

The domain name of the source image was not associated with the account, or the account requires a signature for each request and the signature is missing or incorrect. To fix this, edit your account and enter the domain name of the source image in the 'Valid Domain Names' section and/or include a valid signature (see the security section of the documentation).

500

An internal error occurred. This is often due to a malformed image or unrecognized image format.

Examples

Image Tag

Perhaps the easiest way to use the service is to create an img tag in your HTML whose src parameter is a URL to this service:

Resizes dog.jpg to 100x100 pixels, and changes the format to png.

Resizes dog.jpg to 150x150 pixels, flips horizontal, and changes the format to png.

Creates a 75x75 PNG image of the first page of a PDF file called report.pdf.

Exploring The API

Try using an API tool like whurl.heroku.com to explore the API.