SEPARATE API Endpoint Documentation | PixLab Developers Handbook

API Endpoint Access URL

https://api.pixlab.io/separate

Description

Separates a channel from the given image and returns a grayscale image. A channel is a particular color component of each pixel in the image.

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 with the output image link. Set to true to receive the raw image binary instead.
`channel`	Integer	Color channel constant (See channel constants table below).

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 image uploads (check the REST API code samples or The PixLab Github Repository↗ for implementation examples). For JSON requests, the image must be pre-uploaded. Use the store endpoint for image uploads before calling this endpoint.

Channels Constant

Recommended to omit this parameter and let PixLab process all channels automatically.

Fields	Value
CHANNEL_RED	1
CHANNEL_GRAY	1
CHANNEL_CYAN	1
CHANNEL_GREEN	2
CHANNEL_MAGENTA	2
CHANNEL_BLUE	4
CHANNEL_YELLOW	4
CHANNEL_ALPHA	8
CHANNEL_OPACITY	8
CHANNEL_MATTE	8
CHANNEL_BLACK	32
CHANNEL_INDEX	32
CHANNEL_ALL	134217727

HTTP Response

The SEPARATE 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 raw image binary is returned instead. 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 pixlab.xyz storage server. You can configure custom S3 storage via PixLab console.
`id`	String	Unique identifier for the processed image.
`error`	String	Error description when status ≠ 200.

Code Samples


import requests

def separate_image(image_url: str, channel: int, api_key: str) -> str:
    """Separate image using PixLab API and return the processed image URL."""
    params = {
        'img': image_url,
        'channel': channel,
        'key': api_key
    }
    
    try:
        response = requests.get(
            'https://api.pixlab.io/separate',
            params=params,
            timeout=10
        )
        response.raise_for_status()
        data = response.json()
        
        if data.get('status') != 200:
            raise ValueError(data.get('error', 'Unknown error occurred'))
            
        return data['link']
        
    except requests.exceptions.RequestException as e:
        raise ConnectionError(f"API request failed: {e}") from e
    except (KeyError, ValueError) as e:
        raise ValueError(f"API response error: {e}") from e

# Example usage:
if __name__ == "__main__":
    try:
        processed_url = separate_image(
            image_url='http://www.drodd.com/images15/nature31.jpg',
            channel=7,
            api_key='PIXLAB_API_KEY'
        )
        print(f"Link to the pic: {processed_url}")
    except Exception as e:
        print(f"Error: {e}")


fetch('https://api.pixlab.io/separate?img=http://www.drodd.com/images15/nature31.jpg&channel=7&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://www.drodd.com/images15/nature31.jpg',
    'channel' => 7,
    'key' => 'PIXLAB_API_KEY'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.pixlab.io/separate?' . 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 'json'

uri = URI('https://api.pixlab.io/separate')
params = {
  'img' => 'http://www.drodd.com/images15/nature31.jpg',
  'channel' => 7,
  '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

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