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
Param |
Type |
Description |
width/[val]/ |
Number |
Thumbnail width in pixels
(Default: 600 (1/2 of the viewportWidth) )
|
crop/[val]/ |
Number |
Height of original screenshot in pixels
(Default: 1200 )
|
maxAge/[val]/ |
Number |
Refresh the thumbnail if the cached image is older than this amount, in hours
|
allowJPG/ |
|
Return a JPG instead of PNG format when possible. JPG
images are smaller but are not as high quality. This is the default for images
with a width of 320px or less.
(Recommended for thumbnails and smaller, particularly when a large number of screenshots are
embeded on a single page.)
|
png/ |
|
Return a PNG format regardless of the resolution.
PNG images are larger but have degredation due to compression.
|
noanimate/ |
|
Don't animate the resulting image, just return the final png.
(Good for batch jobs that download images.)
|
fullpage/ |
|
Return an image containing the full page, not just the visible area.
(Only available to "better" plan users. These requests will not display a
loading spinner but instead will block until the final png is ready.)
|
wait/[val]/ |
|
Wait for the specified number of seconds after the webpage
has loaded before taking a screen shot. This is useful for pages that have
animations or other ajax based components that load asyncrhonously.
(Only available to "better" plan users.)
|
viewportWidth/[val]/ |
|
Set the viewportWidth of the browser. Maximum value is 2400.
(Only available to "better" plan users)
(Default: 1200 )
|
iphone5/ |
|
Emulate an iPhone 5.
(Only available to "better" plan users.)
|
iphone6/ |
|
Emulate an iPhone 6.
(Only available to "better" plan users.)
|
iphone6plus/ |
|
Emulate an iPhone 6 Plus.
(Only available to "better" plan users.)
|
iphoneX/ |
|
Emulate an iPhone X.
(Only available to "better" plan users.)
|
iphone12pro/ |
|
Emulate an iPhone 12 Pro.
(Only available to "better" plan users.)
|
iphone14promax/ |
|
Emulate an iPhone 14 Pro Max.
(Only available to "better" plan users.)
|
galaxys5/ |
|
Emulate a Galaxy S5.
(Only available to "better" plan users.)
|
width/[val]/
(Number)
Thumbnail width in pixels
(Default: 600 (1/2 of the viewportWidth) )
|
crop/[val]/
(Number)
Height of original screenshot in pixels
(Default: 1200 )
|
maxAge/[val]/
(Number)
Refresh the thumbnail if the cached image is older than this amount, in hours
|
allowJPG/
Return a JPG instead of PNG format when possible. JPG
images are smaller but are not as high quality. This is the default for images
with a width of 320px or less.
(Recommended for thumbnails and smaller, particularly when a large number of screenshots are
embeded on a single page.)
|
png/
Return a PNG format regardless of the resolution.
PNG images are larger but have degredation due to compression.
|
noanimate/
Don't animate the resulting image, just return the final png.
(Good for batch jobs that download images.)
|
fullpage/
Return an image containing the full page, not just the visible area.
(Only available to "better" plan users. These requests will not display a
loading spinner but instead will block until the final png is ready.)
|
wait/[val]/
Wait for the specified number of seconds after the webpage
has loaded before taking a screen shot. This is useful for pages that have
animations or other ajax based components that load asyncrhonously.
(Only available to "better" plan users.)
|
viewportWidth/[val]/
Set the viewportWidth of the browser. Maximum value is 2400.
(Only available to "better" plan users)
(Default: 1200 )
|
iphone5/
Emulate an iPhone 5.
(Only available to "better" plan users.)
|
iphone6/
Emulate an iPhone 6.
(Only available to "better" plan users.)
|
iphone6plus/
Emulate an iPhone 6 Plus.
(Only available to "better" plan users.)
|
iphoneX/
Emulate an iPhone X.
(Only available to "better" plan users.)
|
iphone12pro/
Emulate an iPhone 12 Pro.
(Only available to "better" plan users.)
|
iphone14promax/
Emulate an iPhone 14 Pro Max.
(Only available to "better" plan users.)
|
galaxys5/
Emulate a Galaxy S5.
(Only available to "better" plan users.)
|
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:
Param |
Type |
Description |
image/width/[width]/ |
Number |
Resize the image to [width] pixels wide (preserve aspect-ration)
|
image/fit/[width]x[height]/ |
Dimensions |
Resize and crop the image so that it completely fills an image that is width x height
|
image/width/[width]/
(Number)
Resize the image to [width] pixels wide (preserve aspect-ration)
|
image/fit/[width]x[height]/
(Dimensions)
Resize and crop the image so that it completely fills an image that is width x height
|
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 screenshot of a pdf rather than a
screenshot of webpage.
Here are some useful parameters specifically for requesting resized pdfs:
Param |
Type |
Description |
pdfSource/width/[width]/ |
Number |
Convert the first page of a pdf to an image and resize to 300px wide (preserve aspect ratio)
|
pdfSource/page/[pageNumber]/ |
Number |
Convert page [pageNumber] of a PDF into an image
|
pdfSource/meta/ |
Number |
Return meta json meta data about the pdf including number of pages.
|
pdfSource/callback/[function] |
String |
Return meta json meta data about the pdf including number of pages wrapped in an invocation of [function] (i.e. JSONP invocation).
|
pdfSource/width/[width]/
(Number)
Convert the first page of a pdf to an image and resize to 300px wide (preserve aspect ratio)
|
pdfSource/page/[pageNumber]/
(Number)
Convert page [pageNumber] of a PDF into an image
|
pdfSource/meta/
(Number)
Return meta json meta data about the pdf including number of pages.
|
pdfSource/callback/[function]
(String)
Return meta json meta data about the pdf including number of pages wrapped in an invocation of [function] (i.e. JSONP invocation).
|
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 embedding 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.