THUMBNAIL API Endpoint Documentation | PixLab Developers Handbook

API Endpoint Access URL

https://api.pixlab.io/thumbnail

Description

Generate optimized thumbnail images by resizing and stripping profiles, ideal for web display. Use with face detection and cropping for precise results. Changes the size of an image to the given dimensions and removes any associated profiles. The goal is to produce small, low cost thumbnail images suited for display on the Web. You can use this API endpoint for example to make optimized thumbnails for a human face coordinate obtained from facedetect and cropped via crop.

HTTP Methods

GET, POST

HTTP Parameters

Required

Fields	Type	Description
`img`	URL	Input media URL. If you want to upload your image directly from your app, submit a multipart/form-data POST request.
`width`	Integer	Desired thumbnail width.
`height`	Integer	Desired thumbnail height.
`key`	String	Your PixLab API Key ↗. You can also embed your key in the `WWW-Authenticate:` HTTP header and omit this parameter.

Optional

Fields	Type	Description
`blob`	Boolean	By default, returns JSON with output image link. Set to true to receive binary media contents instead.

POST Request Body

Use when submitting POST requests instead of GET:

Allowed Content-Types:

multipart/form-data
application/json

Use multipart/form-data for direct media uploads (see REST API code samples or The PixLab Github Repository↗ for examples). For JSON, media must be pre-uploaded. Call store to upload images before invoking this endpoint.

HTTP Response

Fields	Type	Description
`status`	Integer	Status code 200 indicates success, any other code indicates failure.
`link`	URL	Link to the image output which is usually stored on the pixlab.xyz storage server unless you set your own S3 keys (refer to your dashboard ↗ on how to do that).
`id`	String	Unique media ID.
`error`	String	Error message if `status` != 200.

The API returns application/json if the optional blob parameter is not set.

This endpoint returns a JSON Object after each call only if the optional blob parameter is not set. Otherwise, the image binary contents are returned directly.

Code Samples


import requests


def generate_thumbnail(image_url: str, width: int, height: int, api_key: str) -> str:
    """Generate a thumbnail using PixLab API.
    
    Args:
        image_url: URL of the source image.
        width: Width of the thumbnail in pixels.
        height: Height of the thumbnail in pixels.
        api_key: PixLab API key.
        
    Returns:
        URL of the generated thumbnail.
        
    Raises:
        RuntimeError: If thumbnail generation fails.
    """
    params = {
        'img': image_url,
        'width': width,
        'height': height,
        'key': api_key
    }
    
    try:
        response = requests.get(
            'https://api.pixlab.io/thumbnail',
            params=params,
            timeout=10
        )
        response.raise_for_status()
        data = response.json()
        
        if data['status'] != 200:
            raise RuntimeError(data.get('error', 'Unknown error occurred'))
            
        return data['link']
        
    except requests.exceptions.RequestException as e:
        raise RuntimeError(f"API request failed: {str(e)}")


if __name__ == "__main__":
    try:
        thumbnail_url = generate_thumbnail(
            image_url='http://www.drodd.com/images15/nature31.jpg',
            width=320,
            height=240,
            api_key='My_PIXLAB_API_KEY'
        )
        print(f"Thumbnail location: {thumbnail_url}")
    except RuntimeError as e:
        print(f"Error: {str(e)}")


fetch('https://api.pixlab.io/thumbnail?img=http://www.drodd.com/images15/nature31.jpg&width=320&height=240&key=My_PIXLAB_API_KEY')
    .then(response => response.json())
    .then(data => {
        if (data.status !== 200) {
            console.log(data.error);
        } else {
            console.log("Pic location: " + data.link);
        }
    })
    .catch(error => console.error('Error:', error));

<?php

$params = [
    'img' => 'http://www.drodd.com/images15/nature31.jpg',
    'width' => 320,
    'height' => 240,
    'key' => 'My_PIXLAB_API_KEY'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.pixlab.io/thumbnail?' . http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

$response = curl_exec($ch);
curl_close($ch);

$reply = json_decode($response, true);

if ($reply['status'] != 200) {
    echo $reply['error'];
} else {
    echo "Pic location: " . $reply['link'];
}


require 'net/http'
require 'uri'
require 'json'

uri = URI.parse('https://api.pixlab.io/thumbnail')
params = {
  'img' => 'http://www.drodd.com/images15/nature31.jpg',
  'width' => 320,
  'height' => 240,
  'key' => 'My_PIXLAB_API_KEY'
}
uri.query = URI.encode_www_form(params)

response = Net::HTTP.get_response(uri)
reply = JSON.parse(response.body)

if reply['status'] != 200
  puts reply['error']
else
  puts "Pic location: #{reply['link']}"
end

Similar API Endpoints

facedetect, scale, minify, magnify, crop, resize, smartresize, remap, resample, merge, composite, avatar, emailfit, webfit, favicon, screencapture