A picture placed in a rectangle

In plain words

Written for anybody. It says what this puts on a sheet of paper, and asks nothing of you beyond that.

You send your photo or your logo along with your request, and you say where on the sheet it should appear. You give a frame, and the picture settles into it. You choose between two ways: it either fills the whole frame, or it keeps its original shape and centres itself in what is left, undistorted. The same picture can serve in several places, small in a corner and large on another page, without being sent twice.

For a developer

Written for somebody who writes the calling program: the model, the units, and the settings that carry the weight.

The image bytes travel with the request, in a named part of the multipart/form-data body; the image key repeats that name. It is the same pool of named parts the templates come from, so several items draw the same picture at different sizes and places, for one upload and one copy inside the produced file. The frame is a rectangle in points; the fit says whether the picture fills that rectangle or keeps its proportions. The item takes the same placement settings as the others: chosen pages, matrix, rotation and layer.

Every key, with its default

The reference: which keys are required, which are optional, what each one defaults to and which combinations the server declines.

Required keys: image, a string naming the supplied part; rect. Optional: fit, either stretch (the default, the picture fills the rectangle) or contain (the picture keeps its proportions, grows until it meets the width or the height, and centres in the rest); pages, an array of one-based integers, default empty for every page; transform, six numbers; rotate, degrees counter-clockwise about the centre of the box; layer, the name of a declared layer. Cross refusal: transform together with rotate. An image name the request leaves unsupplied answers 400.

A whole request that draws it

Post this as it stands and a PDF comes back. Nothing has been left out of it.

{
  "items": [
    {
      "type": "image",
      "image": "logo.png",
      "rect": {"llx": 72, "lly": 660, "urx": 192, "ury": 780},
      "fit": "contain"
    }
  ]
}

The line that sends it, in three languages

Glossary

byte

The unit a file's weight is counted in, the way a parcel is counted in grams. A thousand of them make a kilobyte, and a million make a megabyte — the size of one photograph taken with a telephone. A one-page PDF here weighs between six thousand and a hundred and twenty thousand, so a hundred of them fit in the space of five photographs.

request

One call to the service: you send what the document should say, and get the document back. Your bill counts these calls, one for each document. The number of pages inside a document is never counted.

template

A PDF file made once and reused as the background of new pages: your letterhead, a plain sheet for the pages that follow, the page of terms you always attach at the end. The file is laid down exactly as it stands, to the millimetre, and the new text is written on top.

multipart form

A way of packing several things into one call: each gets a name and travels in its own part, and they can be text or files alike. It is what a web page uses to upload a photograph, and what carries a document's description alongside the pictures it draws.

layer

A named group of things drawn on a page that a reader can switch on and off, like tracing paper laid over a plan. A drawing can hold its measurements on one and its notes on another, and a layer can be set to show on screen and stay off the printer.

Every word the site explains