HEADER API Endpoint Documentation | PixLab Developers Handbook

API Endpoint Access URL

https://api.pixlab.io/header

Description

Extract image meta information such as height, width, size, MIME type and so forth (See response object below for the list of meta-data returned).

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, then submit a `multipart/form-data` POST request.
`key`	String	Your PixLab API Key ↗. You can also embed your key in the `WWW-Authenticate:` HTTP header and omit this parameter if you want to.

POST Request Body

Use when submitting a POST request instead of a simple GET request.

Allowed Content-Types:

multipart/form-data
application/json

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

HTTP Response

Fields	Type	Description
`status`	Integer	Status code 200 indicates success, any other code indicates failure.
`width`	Integer	Width of the input image.
`height`	Integer	Height of the input image.
`type`	String	Image type format such as `JPEG`, `PNG`, `GIF`, etc.
`size`	Integer	Image size in Bytes.
`mime`	String	Image MIME type.
`channels`	Integer	Total Image channels. e.g. 3 for RGB colorspace, 1 for grayscale image, etc.
`bits`	Integer	Total bits for each color.
`html_attr`	String	String with Height & Width that takes the form `height="128" width="64"` suitable for HTML embedding.
`css_prop`	String	String with Height & Width that takes the form `height:128px;width:64px;` suitable for CSS embedding.
`error`	String	Error message if `status` != 200.

Code Samples


import requests
from typing import Dict, Any


def check_and_resize_image(image_url: str, api_key: str, target_width: int = 800, target_height: int = 600) -> None:
    """Check if an image meets size requirements and resize if necessary using PixLab API."""
    
    # Get image metadata
    header_endpoint = 'https://api.pixlab.io/header'
    header_params = {'img': image_url, 'key': api_key}
    
    try:
        response = requests.get(header_endpoint, params=header_params, timeout=10)
        response.raise_for_status()
        metadata = response.json()
        
        if metadata['status'] != 200:
            raise RuntimeError(metadata.get('error', 'Unknown error occurred'))
            
        width, height = metadata['width'], metadata['height']
        
        if width <= target_width and height <= target_height:
            print("Image is already the correct size!")
            return
            
        print(f"Resizing image from {width}x{height} to near {target_width}x{target_height}...")
        
        # Resize image
        resize_endpoint = 'https://api.pixlab.io/smartresize'
        resize_params = {
            'img': image_url,
            'key': api_key,
            'width': target_width,
            'height': target_height
        }
        
        response = requests.get(resize_endpoint, params=resize_params, timeout=10)
        response.raise_for_status()
        result = response.json()
        
        if result['status'] != 200:
            raise RuntimeError(result.get('error', 'Resizing failed'))
            
        print(f"Resized image: {result['link']}")
        
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
    except Exception as e:
        print(f"Error: {e}")


if __name__ == '__main__':
    image_url = 'https://s-media-cache-ak0.pinimg.com/736x/60/aa/e4/60aae45858ab6ce9dc5b33cc2e69baf7.jpg'
    api_key = 'PIXLAB_API_KEY'
    check_and_resize_image(image_url, api_key)


const img = 'https://s-media-cache-ak0.pinimg.com/736x/60/aa/e4/60aae45858ab6ce9dc5b33cc2e69baf7.jpg';
const key = 'PIXLAB_API_KEY';

// Obtain image metadata at first via header
fetch(`https://api.pixlab.io/header?img=${encodeURIComponent(img)}&key=${encodeURIComponent(key)}`)
    .then(response => response.json())
    .then(reply => {
        if (reply.status !== 200) {
            console.log(reply.error);
            return;
        }
        const w = reply.width;
        const h = reply.height;
        if (w > 800 || h > 600) {
            console.log(`Resizing image from ${w}x${h} to near 800x600...`);
            // Invoke smart resize...
            fetch(`https://api.pixlab.io/smartresize?img=${encodeURIComponent(img)}&key=${encodeURIComponent(key)}&width=800&height=600`)
                .then(response => response.json())
                .then(reply => {
                    if (reply.status !== 200) {
                        console.log(reply.error);
                    } else {
                        console.log(`Resized image: ${reply.link}`);
                    }
                })
                .catch(error => console.error('Error:', error));
        } else {
            console.log("Uploaded image is of the correct size!");
        }
    })
    .catch(error => console.error('Error:', error));

<?php

function checkAndResizeImage($img, $key) {
    $baseUrl = 'https://api.pixlab.io/';
    
    // Get image metadata
    $headerUrl = $baseUrl . 'header?' . http_build_query(['img' => $img, 'key' => $key]);
    $ch = curl_init($headerUrl);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    curl_close($ch);
    
    $reply = json_decode($response, true);
    if ($reply['status'] != 200) {
        die($reply['error']);
    }
    
    $w = $reply['width'];
    $h = $reply['height'];
    
    if ($w > 800 || $h > 600) {
        echo "Resizing image from " . $w . "x" . $h . " to near 800x600...\n";
        
        // Perform smart resize
        $resizeUrl = $baseUrl . 'smartresize?' . http_build_query([
            'img' => $img,
            'key' => $key,
            'width' => 800,
            'height' => 600
        ]);
        
        $ch = curl_init($resizeUrl);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        $response = curl_exec($ch);
        curl_close($ch);
        
        $reply = json_decode($response, true);
        if ($reply['status'] != 200) {
            die($reply['error']);
        } else {
            echo "Resized image: " . $reply['link'] . "\n";
        }
    } else {
        echo "Uploaded image is of the correct size!\n";
    }
}

// Usage
$img = 'https://s-media-cache-ak0.pinimg.com/736x/60/aa/e4/60aae45858ab6ce9dc5b33cc2e69baf7.jpg';
$key = 'PIXLAB_API_KEY';
checkAndResizeImage($img, $key);


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

img = 'https://s-media-cache-ak0.pinimg.com/736x/60/aa/e4/60aae45858ab6ce9dc5b33cc2e69baf7.jpg'
key = 'PIXLAB_API_KEY'

# Obtain image metadata at first via header
uri = URI.parse('https://api.pixlab.io/header')
params = { 'img' => img, 'key' => 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']
  exit
end

w = reply['width']
h = reply['height']

if w > 800 || h > 600
  puts "Resizing image from #{w}x#{h} to near 800x600..."
  # Invoke smart resize...
  uri = URI.parse('https://api.pixlab.io/smartresize')
  params = { 'img' => img, 'key' => key, 'width' => 800, 'height' => 600 }
  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 "Resized image: #{reply['link']}"
  end
else
  puts "Uploaded image is of the correct size!"
end

Similar API Endpoints

nsfw, sfw, ocr, facedetect, docscan, grayscale, rotate, crop, tagimg, mogrify, blur, faceverify ↗, facelookup ↗, screencapture