URL API Documentation


For usage in Javascript (either Node.js or in browser), see our Javascript API.


Example URL


Screenshot modifier options are placed before the requested URL. See below for a full list of options.



Full list of image modifier options



Image resizing API options

Our API also supports resizing images directly. This is great for creating website thumbnails! Simply add /image/ to the beginning of the URL to let our system know that your are requesting an image rather than a screenshot.



Here are some useful parameters specifically for requesting resized images:


PDF API options

Our API also supports converting PDFs into images on the fly. This is great for embedding pages of a pdf directly on a website without any of the extra viewer controls. Simply add /pdfSource/ to the beginning of the URL to let our system know that your are requesting a pdf rather than a screenshot.



Here are some useful parameters specifically for requesting resized pdfs:



Advanced API Options

This section is used to describe some of the more advanced features of our API.

Pass url by parameter

Our core API is designed for simplicity, so we allow users to append the request url to the end of the request without any encoding. Another option is to pass the url in as a url parameter. For example:

http://image.thum.io/get/?url=http%3A%2F%2Fwww.google.com%2F

This format is technically more correct and also allows us to pass additional options to the backend.

Downloading large numbers of images via a batch job

Some of our users prefer to download images using a batch job rather than embeddng them on their site directly. The most efficient way to do this is using our /prefetch/. Our prefetch API gives our users the ability to queue a large number of requests and then fetch those requests later. When you make a prefetch request, the backend will not return an image, instead it will return a message notifying you whether the image is ready to be downloaded.
For example:

http://image.thum.io/get/prefetch/http://www.google.com/

Will return "Image is cached". You can than make a follow up request without /prefetch/ in order to fetch the final image.

Prefetch also supports callbacks so you can be notified when your prefetch request has completed. To set the callback url, you can pass an HTTP header callbackUrl, or if you use the above ?url= scheme, you can pass callback as an additional url parameter.
For example, if you wanted to fetch http://www.google.com/ and receive a callback at http://myhost.com/callback you would make the following request.

http://image.thum.io/get/prefetch/width/300/?url=http%3A%2F%2Fwww.google.com%2F&callbackUrl=http%3A%2F%2Fmyhost.com%2Fcallback

Once the image is rendered, our servers will issue a request to your callback with two url parameters: urlSuffix and originalUrl:

    urlSuffix - The suffix of the url you can use to fetch your image. You should take http://image.thum.io/get/auth/{your auth} and append the value of urlSuffix in order to fetch your image. In this example, urlSuffix will be /width/300/http://www.google.com/

    originalUrl - The url of that was screenshotted. In this case http://www.google.com. This will be used when signing requests that use an md5 based key.

    In this example, you can fetch your final image at:
    http://image.thum.io/get/auth/{your auth}//width/300/http://www.google.com/

Putting it all together you can bulk request a large number of images using prefetch requests. If you choose to use callbacks, you will receive a callback as soon as each image is ready. Another option is to just wait 5-10 minutes and then download all of your images. Either way, using /prefetch/ will give you the best throughput for downloading a large number of screenshots.

Support

For any questions or feedback regarding the JS API, email support@thum.io.