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.
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.
JSONfor each request whether successful or not.
API Access Point URL
The PixLab API’s base endpoint is located at
The request URL scheme is
cmdis 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=valare the endpoint parameters (if any).
Each endpoint may handle both
POSTrequests 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.
|Access Point URL
|API Status Endpoint
|HTTP & TLS Protocols Version
|1.1/2 (Optional TLS 1.2/3)
|Cloudflare, AWS & OVH
|HTTP Response MIME Type
application/json or BLOBs
|HTTP Status & Error Codes
Authentication to the API occurs via two manner. Use the one you feel comfortable with:
Embed your API Key in the WWW-Authenticate HTTP header of the incoming request as follows:
Or, simply include your API key within your
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
|The target endpoint (i.e. FACEDETECT, DOCSCAN, etc.) executed successfully.
|Bad Request - Often missing a required parameter.
|Unauthorized - Missing, Blocked or Invalid API Key.
|Not Found - The requested item (i.e. Image URL) does not exists.
|The HTTP method is not handled by the API endpoint.
|The given media file is not supported by the target API endpoint (i.e. Unsupported image format).
|Too many requests (per minute) from this IP address.
|Server Side Error or Maintenance Planned (We'll notify you anyway).
Now that you understand how PixLab handle your incoming HTTP requests, we can tackle each API endpoint in details in the next lecture.