GRAYSCALE API Endpoint Documentation | PixLab Developers Handbook

API Endpoint Access URL

https://api.pixlab.io/grayscale

Description

Convert images to grayscale with the GRAYSCALE API endpoint. Grayscale images use a single intensity value per pixel, making them efficient for tasks like face detection. Ideal for developers and creators looking for simplified image processing. Convert a given image colorspace to the gray color model. A grayscale (or graylevel) image is simply one in which the only colors are shades of gray. The reason for differentiating such images from any other sort of color image is that less information needs to be provided for each pixel. In fact a `gray' color is one in which the red, green and blue components all have equal intensity in RGB space, and so it is only necessary to specify a single intensity value for each pixel, as opposed to the three intensities needed to specify each pixel in a full color image.

Grayscale images are very common & entirely sufficient for many tasks such as face detection and so there is no need to use more complicated and harder-to-process color images. Source.

HTTP Methods

GET, POST

HTTP Parameters

Required

Fields	Type	Description
`img`	URL	Input image 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.

Optional

Fields	Type	Description
`blob`	Boolean	By default, this API endpoint returns a JSON Object holding the link to the image output. Set to `true` to return the raw image binary instead.

POST Request Body

Use when submitting via POST instead of GET:

Allowed Content-Types:

multipart/form-data
application/json

Use multipart/form-data for direct image uploads (see examples). For JSON, the image must be pre-uploaded - use the store endpoint first if needed.

HTTP Response

Fields	Type	Description
`status`	Integer	Status code 200 indicates success, any other code indicates failure.
`link`	URL	Link to the image output stored on the pixlab.xyz storage server unless custom S3 keys are configured (refer to your dashboard ↗ for setup).
`id`	String	Unique image ID.
`error`	String	Error message if `status` != 200.

The API returns JSON with application/json content type if the optional blob parameter is omitted. When blob is set, the response contains raw image binary data instead.

Required

No required parameters for this endpoint.

Optional

The following optional parameters can be included in the request:

Code Samples


import requests


def process_image_to_grayscale(image_url: str, api_key: str) -> None:
    try:
        response = requests.get(
            'https://api.pixlab.io/grayscale',
            params={'img': image_url, 'key': api_key},
            timeout=10
        )
        response.raise_for_status()
        data = response.json()
        
        if data.get('status') == 200:
            print(f"Link to the grayscale picture: {data['link']}")
        else:
            print(f"Error: {data.get('error', 'Unknown error occurred')}")
            
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
    except ValueError:
        print("Error: Invalid JSON response")
    except KeyError:
        print("Error: Unexpected response format")


if __name__ == "__main__":
    process_image_to_grayscale(
        image_url='http://www.allaboutbirds.org/guide/PHOTO/LARGE/blue_jay_8.jpg',
        api_key='PIXLAB_API_KEY'
    )


fetch('https://api.pixlab.io/grayscale?img=http://www.allaboutbirds.org/guide/PHOTO/LARGE/blue_jay_8.jpg&key=PIXLAB_API_KEY')
    .then(response => response.json())
    .then(reply => {
        if (reply.status !== 200) {
            console.log(reply.error);
        } else {
            console.log("Link to the grayscaled picture: " + reply.link);
        }
    })
    .catch(error => console.error('Error:', error));

<?php

$params = [
    'img' => 'http://www.allaboutbirds.org/guide/PHOTO/LARGE/blue_jay_8.jpg',
    'key' => 'PIXLAB_API_KEY'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.pixlab.io/grayscale?' . 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 "Link to the grayscaled picture: " . $reply['link'];
}


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

uri = URI.parse('https://api.pixlab.io/grayscale')
params = { img: 'http://www.allaboutbirds.org/guide/PHOTO/LARGE/blue_jay_8.jpg', key: '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 "Link to the grayscaled picture: #{reply['link']}"
end

Similar API Endpoints

blur, motionblur, gaussianblur, colorspace_rgb, colorspace_srgb, colorspace_cmyk, image_colorspace, crop, newimage, merge, facedetect, nsfw, ocr