Image library API

22/01/2010

Web-to-print users can upload images into their image libraries to be used in templates. Once an image is uploaded it is validated to be of an accepted type and a small preview is generated. The preview is usually within 600px x 600px. Uploaded images cannot be downloaded.

We offer a set of web-to-print API functions to upload and manipulate the images.

Common response format

All image library and image manipulation functions return a common XML structure:

<Images OwnerID=”03376BB6-913F-4373-B521-6EC172E3612C”>
<Image Folder=”Default” ImageID=”B8B7F7F3-D21D-4309-8FD5-9AA6BB62578A” Created=”2009-10-01T10:25:46.013″ Used=”2009-10-01T09:26:12.013″ Updated=”” MIME=”image/png” Thumb=”21261bc0-6d78-42f8-a975-06206cd7259b.png” ThumbWidth=”215″ ThumbHeight=”150″ ImageWidth=”215″ ImageHeight=”150″ Description=”” Length=”3837″/>
</Images>

There can be up to 50 Image elements inside Images container. Some attributes are explained in the list below:

  • OwnerID – ID of the user the image belongs to
  • Used – last time the file was used to generate a preview or output files
  • Updated – the last time the file was edited
  • Thumb – file name in http://[domain name]/photothumbs folder
  • Width/Height attributes – dimensions of the original and a resized versions of the image in pixels
  • Length – size of the original file in bytes

List of user images

Use an HTTP POST with an API key and user credentials to request last 50 images. The actual library can contain many more images, but only the last used 50 images are returned.

E.g. http://order.example.com/API.aspx?page=api-imgs;ApiKey=79d87451-5a22-4694-a0b4-26ad489d0a87

Format: http://[domain name]/API.aspx?page=api-imgs;ApiKey=[your api key]

Parameters:

  • ApiKey – see API page in your ZetaPrints account (required)
  • UserID – a GUID generated by a remote system (required)
  • Hash – a hash value for user password and server IP (required)
  • ImageFolder – a name of the folder to request images from or none for images from all folders (optional)

Response:

The response is an XML document with a list of up to 50 images, if there are any in the user library.

Single image details

Use an HTTP POST with an API key, user credentials and an image ID to request single image details. This function works only of you supply credentials of the image owner.

E.g. http://order.example.com/API.aspx?page=api-img;ApiKey=79d87451-5a22-4694-a0b4-26ad489d0a87

Format: http://[domain name]/API.aspx?page=api-img;ApiKey=[your api key]

Parameters:

  • ApiKey – see API page in your ZetaPrints account (required)
  • UserID – ID of an user who owns this image (required)
  • Hash – a hash value for user password and server IP (required)
  • ImageID – image id (required)

Response:

The response is an XML document with at most one Image element

Upload a new image

It is not possible to upload a new image as HTTP PUT or multipart POST operation, but you can instruct ZetaPrints dynamic imaging system to download an image from another server.

For this API to work the web server that hosts the image you want to put in the image library must provide a correct MIME type and the exact length of the file.

This function can be called to download from any web server, not necessary the one the request originates from.

Format: http://[domain name]/API.aspx?page=api-img-new;ApiKey=[your api key]

Parameters:

  • ApiKey – see API page in your ZetaPrints account (required)
  • UserID – ID of an user who owns this image (required)
  • Hash – a hash value for user password and server IP (required)
  • URL – a fully qualified URL where the image is located (required)
  • ImageFolder – an arbitrary name for a folder to place an image in (optional)
  • Comments – a title of the image or a short description (optional)

Response:

The response is an XML document with a single Image element containing details of the uploaded image.

Delete image

Use an HTTP POST with an API key, user credentials and an image ID to an image from a library. There is no undo or restore for this operation.

Format: http://[domain name]/API.aspx?page=api-img-delete;ApiKey=[your api key]

Parameters:

  • ApiKey – see API page in your ZetaPrints account (required)
  • UserID – ID of an user who owns this image (required)
  • Hash – a hash value for user password and server IP (required)
  • ImageID – image id (required)

Response:

An empty image details structure as XML. The operation failed if the structure is not empty.

See also: