logo

Version 1.9.72 (Release Notes)


This page define the Rest API interface to PixLab. This is not a tutorial. This page is designed to be precise. Although easy to read.

For a tutorial introduction see Getting Started with PixLab and The PixLab Code Samples Set. You’re welcome to copy/paste and run these examples to see the API in action.

The PixLab API is built on HTTP/TLS. Our API is RESTful and it:

  • Uses built-in HTTP capabilities for passing parameters and authentication.

  • Responds with standard HTTP response codes to indicate errors.

  • Always returns JSON for each request whether successful or not.

Features


PixLab Logo

 Access to over 130 battle tested, intelligent API endpoints and growing...

 99.9*% uptime guaranty. 24/7 friendly support assistance.

 No hidden fees, no contract. Cancel your plan at anytime!

 Rich Documentation, Production Ready Code Samples & Open source Advocates

API Access Point URL


  • The PixLab API’s base endpoint is located at https://api.pixlab.io/.

  • The request URL scheme is https://api.pixlab.io/cmd?param=val&param2=val2 where cmd is the API Endpoint you want to call such as FACEDETECT (for face detection), DOCSCAN (for Passports & ID scanning), MOGRIFY (for face blurring), NSFW (for adult & bloody content detection), ROTATE, and hundreds of others and param=val are the endpoint parameters (if any).

  • Each endpoint may handle both GET & POST requests at the same time. PixLab is shipped with over 130 endpoints and all of them are invoked using exactly the same way.

  • Health & Status dashboard is located at status.faceio.net (a PixLab product) for real-time monitoring.

Summary

Access Point URL api.pixlab.io
API Status Endpoint api.pixlab.io/status
Architecture RESTFul
HTTP & TLS Protocols Version 1.1/2 (Optional TLS 1.2/3)
Authentication Key Based
Network Cloudflare, AWS & OVH
HTTP Response MIME Type application/json or BLOBs
HTTP Status & Error Codes See Below
API Endpoints Listed Here

Authentication


When you sign up for an account, you are given an API key. You authenticate to the PixLab API by providing your API key in the request. You can manage your keys via the API Keys tab of the Console.

Authentication Methods

Authentication to the API occurs via two manner. Use the one you feel comfortable with:

HTTP Header

Embed your API Key in the WWW-Authenticate HTTP header of the incoming request as follows:
WWW-Authenticate: API_KEY.
Replace API_KEY with your application’s real API Key you got from the Console.

Query Parameter

Or, simply include your API key within your POST or GET request like any other parameters an API Endpoint would takes as follows:
https://api.pixlab.io/facedetect?param=val&key=API_KEY

 Don't forget to keep your API keys handy, and make sure they are used by authorized scripts only.

Responses, Status Codes & Errors


The following HTTP status codes are always returned after each initiated request. All PixLab API Endpoints, always returns application/json for each request whether successful or not. BLOBs (images binary contents) are returned only after successful requests and at the user explicit demand, usually by setting the blob parameter an endpoint takes to true.

200 The target endpoint (i.e. FACEDETECT, DOCSCAN, etc.) executed successfully.
400 Bad Request - Often missing a required parameter.
401 Unauthorized - Missing, Blocked or Invalid API Key.
404 Not Found - The requested item (i.e. Image URL) does not exists.
405 The HTTP method is not handled by the API endpoint.
415 The given media file is not supported by the target API endpoint (i.e. Unsupported image format).
429 Too many requests (per minute) from this IP address.
500 Server Side Error or Maintenance Planned (We'll notify you anyway).

Further Reading

Now that you understand how PixLab handle your incoming HTTP requests, we can tackle each API endpoint in details in the next lecture.