Documentation

Contents

Overview

Miniature.io is a cloud API for capturing online resources as pictures.

Features

Online Website Screenshots

Website Screenshots

Project offers the simplest way to capture a snapshot of an online resource and display it as an image on your own website or application. Forget installing custom software on your server! With Miniature.io you can simply hotlink images directly from our API and customize experience to fit your project's needs.


Online Image Thumbnailer

Image Thumbnailer

Since 2011 we have served billions of images for customers worldwide.
Our goal is to convert any online resource to an image, that also means we can process online images. For example you can scale down or crop photos displayed on your website to save your viewers bandwidth and reduce page load time. You can use all these features directly on your website.


Online PDF Generator

PDF Generator

With Miniature.io you can efortlessly render PDF document using a regular HTML website as a source. For example you can easily generate good looking PDF invoices directly from your website and provide a link to your customers. No need for any backend solution and you can try our API right away!


Miniature.io API

Basic Usage

Let's say you want to display a screenshot of some website on yours.

With Miniature.io API it is really easy. All you need to do is to use HTML's <img .../> tag and hotlink an image directly from api.miniature.io. We will take care of all the rest including rendering website's content and scalling it down.

Ubuntu Screenshot

Copy the following code snippet into your website's HTML to display a screenshot of Ubuntu landing page. You can, of course, change the website to any other.

<img src="http://api.miniature.io/?url=ubuntu.com" />

API Endpoints

Our API is publicly available and you can use it directly on your website or in your custom applications. In order to use it, you need to call one of the production endpoints.

The production Miniature.io API base URLs are the following:

API Syntax

The Miniature.io API uses a simple HTTP Query syntax.

You can use one of the endpoints and provide parameters to direct what API should do. If you don't specify any parameters API will return the default 300x300 pixels placeholder image.

API options are passed as HTTP Query parameters:

http://api.miniature.io/?width=...&height=...&url=...

For example, to display this facebook.com 100x50 screenshot of facebook.com use this URL:

https://api.miniature.io/?width=100&height=50&url=facebook.com

Full list of parameters is available in each section.


Website Screenshots

Website Screenshots is the default mode of the Miniature.io API and is available at the default / endpoint.

Following parameters apply to Website Screenshots:

  • url - URL of the website to render
  • width - Width of the result picture in pixels
  • height - Height of the result picture in pixels
  • screen - Horizontal screen width
  • delay - How long to wait to render

Customize thumbnail size

We know there is no one-size-fits-all, so with Miniature.io API you can adjust the size of generated thumbnails to your needs. You can customize the size of the website thumbnail by specifying width and height parameters in pixels, examples:

Size API Result
50x50 https://api.miniature.io/?width=50&height=50&url=http://apple.com 50x50
100x50 https://api.miniature.io/?width=100&height=50&url=http://apple.com 100x50
50x100 https://api.miniature.io/?width=50&height=100&url=http://apple.com 50x100
100x100 https://api.miniature.io/?width=100&height=100&url=http://apple.com 100x100

Adjust screen resolution

Various websites render differently on different devices with different screen resolution. With Miniature.io you can choose the screen horizontal resolution by specifying the screen parameter in either pixels or by a predefined name. Screen width will be aligned to the nearest larger predefined screen size, examples:

Screen API Result
1024 https://api.miniature.io/?width=100&height=100&screen=1024&url=http://apple.com 1024
fhd https://api.miniature.io/?width=100&height=100&screen=fhd&url=http://apple.com fhd


Image Thumbnailer

Before capturing content as an image, the Miniature.io API performs a check to detect type of content. If the remote resource is an image the Image Thumbnailer mode is being turned on. Following content types are currently supported image/jpeg, image/png, image/gif.

Image Thumbnailer is available on the / endpoint. By default the fit mode is turned on.

Following parameters apply to Website Screenshots:

  • url - URL of the website to render
  • width - Width of the result picture in pixels
  • height - Height of the result picture in pixels
  • thumb - Thumbnailer mode, fit or resize

Fit thumbnails

The thumb=fit will enable fitting thumbnailer, it means the API will crop the output image to keep original aspect ratio. The crop is positioned in the center of image's gravity. Consider this Paxillus involutus picture from Wikipedia for examples:

Size API Result
150x150 http://api.miniature.io/?thumb=fit&width=150&height=150&url=... result
150x100 http://api.miniature.io/?thumb=fit&width=150&height=100&url=... result
100x150 http://api.miniature.io/?thumb=fit&width=100&height=150&url=... result

Resize thumbnails

The thumb=resize will enable resizing thumbnailer which takes entire input image and scales it to the expected output size ignoring the original aspect ratio, examples:

Size API Result
150x150 http://api.miniature.io/?thumb=resize&width=150&height=150&url=... result
150x100 http://api.miniature.io/?thumb=resize&width=150&height=100&url=... result
100x150 http://api.miniature.io/?thumb=resize&width=100&height=150&url=... result


PDF Generator

This is an experimental feature of Miniature.io.

The Miniature.io API can convert Website Screenshots to PDF. Quality of the result depends greately on the rendered website, if you intend to use this feature in your own applications, we recommend to keep the source HTML as simple as possible to avoid PDF rendering issues.

The PDF Renderer is available on the /pdf endopoint.

Rendering PDF will block API to ensure the PDF is returned, there is no placeholder. In case of error a JSON response is being returned with details about the problem. Rendering time depends on the remote content download speed.

Examples:

Source API Result
Hacker News https:/api.miniature.io/pdf?url=news.ycombinator.com
Reddit https:/api.miniature.io/pdf?url=reddit.com

Following parameters are available:

  • url - Specify the URL of the content to render
  • screen - Horizontal screen width
  • delay - Time to wait to render
  • orientation - PDF orientation portrait or landscape
  • paper_size - PDF paper size: a3, a4, letter, tabloid


Parameters Reference

Image Parameters

Following parameters apply to Website Screenshots and Image Thumbnailer.

  • url

    URL of the resource, if not specified a default 300x300 image will be displayed. If URL does not start with http:// or https:// the http:// is added.

    Required: yes

    Supported resource protocols:

    • http://
    • https://

    Supported resource content types:

    • text/html
    • text/xml
    • text/plain
    • image/jpeg
    • image/png
    • image/gif

  • width, height

    Size of the output image in pixels.

    Required: no

    Minimum: 1

    Maximum: 2560

    Default: 300


Website Screenshots Specific

Following parameters apply to Website Screenshots.

  • screen

    Size of the screen for a website screenshot. if value is a number it is aligned to the nearest greater size.

    Required: no

    Values:

    • xs - represents 480 pixels
    • sm - represents 768 pixels
    • md - represents 992 pixels
    • lg - represents 1200 pixels
    • hd - represents 1366 pixels
    • hdp - represents 1600 pixels
    • fhd - represents 1920 pixels
    • qhd - represents 2560 pixels
    • 800 - 800 pixels
    • 1024 - 1024 pixels
    • 1280 - 1280 pixels
    • 1366 - 1366 pixels
    • 1650 - 1650 pixels
    • 1920 - 1920 pixels
    • 2560 - 2560 pixels

  • delay

    How long to wait for a website to render? Value is in seconds.

    Required: no

    Minimum: 1

    Maximum: 60

    Default: 5


Image Thumbnails Specific

Following parameters apply to Image Thumbnailer

  • thumb

    How to crop an image if the remote resource is a picture.

    Required: no

    Values:

    • fit - Keep aspect ratio and crop to the maximum size with gravity in the center of the image.
    • resize - Resize input image to the requested size without keeping aspect ratio.

    Default: fit


PDF Generator Specific

Following parameters apply to PDF Generator

  • paper_size

    PDF paper size.

    Required: no

    Default: a4

    Values:

    • a4
    • a3
    • letter
    • tabloid

  • orientation

    PDF orientation.

    Required: no

    Default: portrait

    Values:

    • portrait
    • landscape