Dynamic imaging API

31/03/2009

ZetaPrints web-to-print system can be used for template based dynamic imaging. This interface is simplified for preview-only process. An open-source e-cards plugin is hosted under Google Code and utilizes this API.

Client based calls

The user agent, be it a web page with JavaScript or a Flash application can post data to

http://[domain name]/?page=template-preview-ecard;TemplateID=[template id]

and include optional parameters as HTTP POST fields

  • <input type=”hidden” name=”ID” value=”[user ID if known]” />
  • <input type=”hidden” name=”From” value=”[page number for multi-page templates,  default 1]” />
  • <input type=”hidden” name=”Width” value=”[max width of the preview image in pixels, <500px, in 50px increments]” />
  • <input type=”hidden” name=”Height” value=”[max height of the preview image in pixels, <500px, in 50px increments]” />
  • <input type=”hidden” name=”Preserve” value=”yes” /> – optional field to preserve field text and images where no user input is provided

Important: this interface should be used only for direct interaction with a user client, not for server to server communications.

Server based calls

This call can be made by applications to impersonate a user. The server needs to calculate an MD5 hash of user password and caller’s IP.

http://[domain name]/API.aspx?page=api-preview

and include parameters as HTTP POST fields

  • <input type=”hidden” name=”ApiKey” value=”[API key, required]” />
  • <input type=”hidden” name=”TemplateID” value=”[template ID, required]” />
  • <input type=”hidden” name=”ID” value=”[user ID, required]” />
  • <input type=”hidden” name=”Hash” value=”[MD5 hash of user password, required]” />
  • <input type=”hidden” name=”From” value=”[page number for multi-page templates,  default 1, optional]” />
  • <input type=”hidden” name=”Width” value=”[max width of the preview image in pixels, <500px, in 50px increments, optional]” />
  • <input type=”hidden” name=”Height” value=”[max height of the preview image in pixels, <500px, in 50px increments, optional]” />
  • <input type=”hidden” name=”Preserve” value=”yes” /> – optional field to preserve field text and images where no user input is provided

Important: this interface should be used only for direct interaction between an application and ZetaPrints dynamic imaging generator so that the API key is not revealed.

Response

On success – URL of the generated image

On failure – an error message of some kind

User ID

It is best to avoid sending user ID unless you are confident that one of the following is true:

  • the ID does not exist
  • the ID exists, belongs to this user and the user is currently logged in

ZetaPrints dynamic imaging generator will add a new ID as a cookie to the response if no ID was supplied. The client is expected to use this ID during the session.

Text fields

Templates have text fields are provided in Template Details feed under Fields section. Every text field has attribute FieldName. User input should be posted with the field name after underscore character (_).

E.g.  for field <Field FieldName=”Top Greeting” Page=”1″ Multiline=”1″ Hint=”Appears at the top of the page”/> the input field should look like this:

  • <input type=”text” name=”_Top Greeting” title=”Appears at the top of the page” />

The value of the input field would be user input. A blank value or not submitting the field would clear the text in the template, unless Preserve=yes.

Image fields

Only image fields with stock photos are supported at the moment. The site will not accept files posted with the request.

Image fields are provided in Template Details feed under Images section. Every image field has attribute Name and a list of stock images as <StockImage /> element. Append image name to “#” before submitting.

Source data example:

<Image Name="Choose Your Background" Width="1800" Height="1200">
   <StockImage FileID="6CAB2649-8C0B-490B-87CD-33E2FB79D8FF" MIME="image/jpg" Thumb="4b461602-ac60-450c-86c5-12b72023c927.jpg"/>
   <StockImage FileID="C16EAF32-632F-4434-9BE7-0FF3C82A7988" MIME="image/jpg" Thumb="e3035786-992f-4d0e-9109-475d7099bc77.jpg"/>
   <StockImage FileID="8ED88275-4935-40FA-A708-2B6692629F94" MIME="image/jpg" Thumb="31820673-dce5-415a-8156-148caf7f21f4.jpg"/>
   <StockImage FileID="8E15E01B-97EA-40FC-90A5-547D17B2D4CC" MIME="image/jpg" Thumb="c51e7579-77de-4345-81c7-6a000e5f81b0.jpg"/>
</Image>

FileID – the value to submit with the request if the file was chosen by the user

Thumb – thumb file name, http://[domain name]/photothumbs/[value of attribute Thumb]

Image selection form example:

  • <input type=”radio” name=”#Choose Your Background” value=”6CAB2649-8C0B-490B-87CD-33E2FB79D8FF” /><img src=”http://img.example.com/photothumbs/4b461602-ac60-450c-86c5-12b72023c927.jpg” />
  • <input type=”radio” name=”#Choose Your Background” value=”C16EAF32-632F-4434-9BE7-0FF3C82A7988″ /><img src=”http://img.example.com/photothumbs/e3035786-992f-4d0e-9109-475d7099bc77.jpg” />
  • <input type=”radio” name=”#Choose Your Background” value=”8ED88275-4935-40FA-A708-2B6692629F94″ /><img src=”http://img.example.com/photothumbs/31820673-dce5-415a-8156-148caf7f21f4.jpg” />
  • <input type=”radio” name=”#Choose Your Background” value=”8E15E01B-97EA-40FC-90A5-547D17B2D4CC” /><img src=”http://img.example.com/photothumbs/c51e7579-77de-4345-81c7-6a000e5f81b0.jpg” />

Basically, you show the list of stock images to a user and submit FileID of the selected image as part of the request.

Valid values

  • file id as a GUID, e.g. C16EAF32-632F-4434-9BE7-0FF3C82A7988
  • RGB value of a solid fill color (7 chars), e.g. #ffffff
  • CMYK value of a solid fill color (13 chars), e.g. #255255255255
  • no value to clear the field
  • # (just a single #, 1 char) to retain the default image / color from the template

Image resizing

Image resizing on the client doesn’t always produce the best quality. Consider using our server-side image resizing feature for initial previews and stock images.

See also: