SHADE API Endpoint Documentation | PixLab Developers Handbook

API Endpoint Access URL

https://api.pixlab.io/shade

Description

Creates a 3D effect. Shines a distant light on an image to create a three-dimensional effect. You control the positioning of the light with azimuth and elevation; azimuth is measured in degrees off the x axis and elevation is measured in pixels above the Z axis.

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, submit a `multipart/form-data` POST request.
`gray`	Boolean	A value other than zero shades the intensity of each pixel.
`azimuth`	Float	Defines the light source direction.
`elevation`	Float	Defines the light source direction.
`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 a JSON Object with the output image link. Set to `true` to receive the image binary contents instead.

POST Request Body

Use this if you plan to submit a POST request instead of GET.

Allowed Content-Types:

multipart/form-data
application/json

Use multipart/form-data for direct image uploads (check the REST API code samples or The PixLab Github Repository↗ for examples). For JSON, ensure your image is already hosted. Call store to upload an image before invoking this endpoint.

HTTP Response

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

This endpoint returns a JSON Object after each call unless the blob parameter is specified, in which case the image binary contents are returned directly. The response JSON contains the following fields:

Fields	Type	Description
`status`	Integer	Status code 200 indicates success, any other code indicates failure.
`link`	URL	Link to the processed image stored on our servers unless custom S3 keys are configured (see your dashboard ↗ for configuration).
`id`	String	Unique identifier for the processed image.
`error`	String	Error message when `status` != 200.

Code Samples


import requests

def process_image():
    try:
        response = requests.get(
            'https://api.pixlab.io/shade',
            params={
                'img': 'http://cf.broadsheet.ie/wp-content/uploads/2015/03/jeremy-clarkson_3090507b.jpg',
                'gray': 1,
                'elevation': 4,
                'key': 'PIXLAB_API_KEY'
            },
            timeout=10
        )
        response.raise_for_status()
        data = response.json()
        
        if data.get('status') == 200:
            print(f"Link to the pic: {data['link']}")
        else:
            print(data.get('error', 'Unknown error occurred'))
            
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
    except ValueError:
        print("Invalid JSON response")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

if __name__ == "__main__":
    process_image()


fetch('https://api.pixlab.io/shade?img=http://cf.broadsheet.ie/wp-content/uploads/2015/03/jeremy-clarkson_3090507b.jpg&gray=1&elevation=4&key=PIXLAB_API_KEY')
    .then(response => response.json())
    .then(reply => {
        if (reply.status !== 200) {
            console.log(reply.error);
        } else {
            console.log("Link to the pic: " + reply.link);
        }
    })
    .catch(error => console.error('Error:', error));

<?php

$params = [
    'img' => 'http://cf.broadsheet.ie/wp-content/uploads/2015/03/jeremy-clarkson_3090507b.jpg',
    'gray' => 1,
    'elevation' => 4,
    'key' => 'PIXLAB_API_KEY'
];

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


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

uri = URI.parse('https://api.pixlab.io/shade')
params = {
  'img' => 'http://cf.broadsheet.ie/wp-content/uploads/2015/03/jeremy-clarkson_3090507b.jpg',
  'gray' => 1,
  'elevation' => 4,
  '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 pic: #{reply['link']}"
end

Similar API Endpoints

posterize, negate, separate, sketch, polaroid, normalize, oilpaint, orderedposterize, segment, quantize, raise, grayscale