CROP API Endpoint Documentation | PixLab Developers Handbook

API Endpoint Access URL

https://api.pixlab.io/crop

Description

Crop API endpoint extracts a specified region from an image, ideal for use with face detection and other media analysis tasks. Extract a region from a given image. This API endpoint is of particular interest especially if mixed with some media analysis endpoints such as facedetect to locate the coordinates of a human face for example and extract it via crop.

HTTP Methods

GET, POST

HTTP Parameters

Required

Fields	Type	Description
`img`	URL	Input media URL. If uploading directly from your app, submit a `multipart/form-data` POST request.
`width`	Integer	Desired crop width. If omitted, the height value will be used.
`height`	Integer	Desired crop height. If omitted, the width value will be used.
`x`	Integer	X coordinate of the cropped region's top-left corner.
`y`	Integer	Y coordinate of the cropped region's top-left corner.
`key`	String	Your PixLab API Key ↗. Alternatively, embed your key in the `WWW-Authenticate:` header.

Optional

Fields	Type	Description
`blob`	Boolean	Returns JSON with output URL by default. Set to true to receive binary image data 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 file uploads (see examples). For JSON, the file must be hosted elsewhere. Upload images first via store if needed.

HTTP Response

Fields	Type	Description
`status`	Integer	Status code 200 indicates success, any other code indicates failure.
`link`	URL	Link to the media output stored on the pixlab.xyz storage server unless custom S3 keys are configured (refer to your dashboard ↗ for configuration).
`id`	String	Unique media identifier.
`error`	String	Error description when status ≠ 200.

The API returns application/json when the optional blob parameter is omitted. When blob is enabled, the endpoint returns the raw media binary instead of JSON.

Required

Include these parameters in every request:

Parameter	Type	Description
`key`	String	Your API key from console.pixlab.io
`img`	URL/String	Input image URL or base64 encoded string

Optional

Additional parameters for advanced control:

Parameter	Type	Description
`blob`	Boolean	Return binary response when true (default: false)
`width`	Integer	Output width in pixels
`height`	Integer	Output height in pixels

Code Samples


import requests

def extract_face(image_url: str, x: int, y: int, width: int, height: int, api_key: str) -> str:
    """Extract face from image using PixLab API.
    
    Args:
        image_url: URL of the image to process
        x: X coordinate of the face rectangle
        y: Y coordinate of the face rectangle
        width: Width of the face rectangle
        height: Height of the face rectangle
        api_key: PixLab API key
        
    Returns:
        URL of the cropped image or error message
    """
    try:
        response = requests.get(
            'https://api.pixlab.io/crop',
            params={
                'img': image_url,
                'key': api_key,
                'x': x,
                'y': y,
                'width': width,
                'height': height
            },
            timeout=10
        )
        response.raise_for_status()
        data = response.json()
        
        if data['status'] != 200:
            return f"Error: {data.get('error', 'Unknown error')}"
            
        return f"Face location: {data['link']}"
        
    except requests.exceptions.RequestException as e:
        return f"Request failed: {str(e)}"
    except ValueError:
        return "Error: Invalid JSON response"
    except KeyError:
        return "Error: Malformed API response"

if __name__ == "__main__":
    result = extract_face(
        image_url='http://cf.broadsheet.ie/wp-content/uploads/2015/03/jeremy-clarkson_3090507b.jpg',
        x=164,
        y=95,
        width=145,
        height=145,
        api_key='PIXLAB_API_KEY'
    )
    print(result)


fetch('https://api.pixlab.io/crop?img=http://cf.broadsheet.ie/wp-content/uploads/2015/03/jeremy-clarkson_3090507b.jpg&key=PIXLAB_API_KEY&x=164&y=95&width=145&height=145')
    .then(response => response.json())
    .then(reply => {
        if (reply.status !== 200) {
            console.log(reply.error);
        } else {
            console.log("Face location: " + reply.link);
        }
    })
    .catch(error => console.error('Error:', error));

<?php

$params = [
    'img' => 'http://cf.broadsheet.ie/wp-content/uploads/2015/03/jeremy-clarkson_3090507b.jpg',
    'key' => 'PIXLAB_API_KEY',
    'x' => 164,
    'y' => 95,
    'width' => 145,
    'height' => 145
];

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

$response = curl_exec($ch);
if (curl_errno($ch)) {
    die('Curl error: ' . curl_error($ch));
}
curl_close($ch);

$reply = json_decode($response, true);
if ($reply['status'] != 200) {
    die($reply['error']);
} else {
    echo "Face location: " . $reply['link'];
}


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

uri = URI.parse('https://api.pixlab.io/crop')
params = {
  'img' => 'http://cf.broadsheet.ie/wp-content/uploads/2015/03/jeremy-clarkson_3090507b.jpg',
  'key' => 'PIXLAB_API_KEY',
  'x' => 164,
  'y' => 95,
  'width' => 145,
  'height' => 145
}
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 "Face location: #{reply['link']}"
end

Similar API Endpoints

newimage, scale, minify, magnify, ar, smartcrop, resize, smartresize, remap, setresolution, resample, thumbnail, merge, composite, facedetect, avatar, webfit