DRAWPOINTS API Endpoint Documentation | PixLab Developers Handbook

API Endpoint Access URL

https://api.pixlab.io/drawpoints

Description

Draw points freely on any input image using the DRAWPOINTS API endpoint. Ideal for developers and creators looking to enhance image interactivity. Draw as much points as desired on a given input image.

HTTP Methods

POST

HTTP Parameters

Required

Fields	Type	Description
`img`	URL	Input image URL. If you want to upload your image directly from your app, call store before invoking this one.
`points`	Array	JSON array holding the coordinates of the points to be drawn (See below).
`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 return a JSON Object holding the link to the image output. But, if this parameter is set to true then the image binary contents is returned instead.
`color`	String	Global color for each point to be drawn which default to `white`. Use hex color code such as `#cef45f` if you want to.

POST Request Body

Allowed Content-Types:

application/json

Only JSON data is allowed. The field of interest here is the points parameter which must be a JSON array holding the object coordinates of each point to be drawn on the input image. The following are the required parameters for each object in the points array:

Fields	Type	Description
`x`	Integer	Point's X coordinate.
`y`	Integer	Point's Y coordinate.
`color`	String	`Optional` Color to apply for this specific point which default to `white`. Use hex color code such as `#cef45f` if you want to.

So, a typical points array should look like this (See the example section for a working snippet).


points = [
    {
      x: 200,
      y: 290
    },
    {
      x: 165,
      y: 95,
      color: 'red'
    }
]

HTTP Response

Fields	Type	Description
`status`	Integer	Status code 200 indicates success, any other code indicates failure.
`link`	URL	Link to the image output which is usually stored on the pixlab.xyz storage server unless you set your own S3 keys (refer to your dashboard ↗ on how to do that).
`id`	String	Unique image ID.
`error`	String	Error message if `status` != 200.

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

This endpoint returns a JSON Object after each call only if the optional blob parameter is not set. Otherwise, the image binary contents are returned directly.

Code Samples


import requests
import json
from typing import Dict, Any, List

def draw_points(image_url: str, api_key: str, points: List[Dict[str, Any]]) -> None:
    """Draw points on an image using the PixLab API."""
    endpoint = 'https://api.pixlab.io/drawpoints'
    headers = {'Content-Type': 'application/json'}
    payload = {
        'img': image_url,
        'key': api_key,
        'points': points
    }

    try:
        response = requests.post(
            endpoint,
            headers=headers,
            data=json.dumps(payload),
            timeout=10
        )
        response.raise_for_status()
        data = response.json()

        if data['status'] != 200:
            print(f"Error: {data.get('error', 'Unknown error')}")
        else:
            print(f"Image location: {data['link']}")

    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
    except json.JSONDecodeError:
        print("Error: Invalid JSON response")
    except KeyError:
        print("Error: Malformed API response")

if __name__ == "__main__":
    points_data = [
        {"x": 164, "y": 95},
        {"x": 250, "y": 180},
        {"x": 140, "y": 110, "color": "yellow"},
        {"x": 160, "y": 120},
        {"x": 194, "y": 130, "color": "green"},
        {"x": 199, "y": 100}
    ]
    draw_points(
        image_url='https://s3.amazonaws.com/pixlab.xyz/npi5873a69a18862.png',
        api_key='My_Key',
        points=points_data
    )


fetch('https://api.pixlab.io/drawpoints', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        'img': 'https://s3.amazonaws.com/pixlab.xyz/npi5873a69a18862.png',
        'key': 'My_Key',
        'points': [
            {
                "x": 164,
                "y": 95
            },
            {
                "x": 250,
                "y": 180
            },
            {
                "x": 140,
                "y": 110,
                "color": "yellow"
            },
            {
                "x": 160,
                "y": 120
            },
            {
                "x": 194,
                "y": 130,
                "color": "green"
            },
            {
                "x": 199,
                "y": 100
            }
        ]
    })
})
.then(response => response.json())
.then(data => {
    if (data.status !== 200) {
        console.log(data.error);
    } else {
        console.log("Pic location: " + data.link);
    }
})
.catch(error => console.error('Error:', error));

<?php

$data = [
    'img' => 'https://s3.amazonaws.com/pixlab.xyz/npi5873a69a18862.png',
    'key' => 'My_Key',
    'points' => [
        [
            'x' => 164,
            'y' => 95
        ],
        [
            'x' => 250,
            'y' => 180
        ],
        [
            'x' => 140,
            'y' => 110,
            'color' => 'yellow'
        ],
        [
            'x' => 160,
            'y' => 120
        ],
        [
            'x' => 194,
            'y' => 130,
            'color' => 'green'
        ],
        [
            'x' => 199,
            'y' => 100
        ]
    ]
];

$ch = curl_init('https://api.pixlab.io/drawpoints');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

$reply = json_decode($response, true);

if ($reply['status'] != 200) {
    echo $reply['error'];
} else {
    echo "Pic location: " . $reply['link'];
}


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

uri = URI.parse('https://api.pixlab.io/drawpoints')
request = Net::HTTP::Post.new(uri)
request.content_type = 'application/json'
request.body = JSON.dump({
  'img' => 'https://s3.amazonaws.com/pixlab.xyz/npi5873a69a18862.png',
  'key' => 'My_Key',
  'points' => [
    {
      'x' => 164,
      'y' => 95
    },
    {
      'x' => 250,
      'y' => 180
    },
    {
      'x' => 140,
      'y' => 110,
      'color' => 'yellow'
    },
    {
      'x' => 160,
      'y' => 120
    },
    {
      'x' => 194,
      'y' => 130,
      'color' => 'green'
    },
    {
      'x' => 199,
      'y' => 100
    }
  ]
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

reply = JSON.parse(response.body)
if reply['status'] != 200
  puts reply['error']
else
  puts "Pic location: #{reply['link']}"
end

Similar API Endpoints

drawlines, drawcircles, drawtext, drawrectangles, drawtextat