Getting Started with the PixLab REST APIs

This tutorial walks through the request pattern behind the PixLab REST API using practical examples you can reuse in your own applications. Once you understand the core flow, the API Portal, REST API Reference, ID Scan & Extract API, Vision Platform, and API Endpoints Directory become much easier to navigate.

• Features of the PixLab REST API →
• API Access URL →
• Authentication & API Keys →
• Response Success & Error Codes →
• API Endpoints Categories →
• Your First API Call ↓
• Detect & Extract or Mark Faces ↓
• Detect & Blur Human Faces ↓
• Programmatically Generate MEMEs ↓
• Challenge Bots by Dynamic Image Generation ↓
• Scan Passports, ID Cards & KYC Verification Check ↓
• Moderate Image Uploads According to their NSFW Score ↓

Your First API Call

To get familiar with the PixLab API, start with one of the simplest endpoints: GRAYSCALE. Given an input image, it returns a grayscale version of that image:

Input Picture

GRAYSCALE (api.pixlab.io/grayscale) Picture Output

The output, grayscaled image above was obtained using the following code snippets:

• Regardless of language, the request pattern stays the same. Here we make a simple HTTP GET request with the input image URL as the main parameter. Most API endpoints support both GET and POST, so you can either reference remote files or upload images and videos directly from your own application. See the Code Samples page for more patterns.
• After the request completes, PixLab returns a JSON object with a link field pointing to the output asset plus a status code. Status code 200 means success. Any other code indicates failure with an appropriate error message. Refer to the API response section for the full list of status codes.
• Sometimes you may want the raw image content (BLOB) returned directly instead of a JSON object containing an output link. To do that, set blob=true on the request, for example https://api.pixlab.io/endpoint?blob=true&param=val. When blob is enabled, the raw asset is returned to the caller instead of being stored on the pixlab.xyz storage cluster.
• By default, processed assets are stored on the globally distributed pixlab.xyz storage cluster so you can access them through the returned link. If privacy or storage control matters, you can connect your own AWS S3 bucket as the storage gateway. That way, processed images and video outputs are written to your own bucket instead of the public PixLab one. Configure this from the PixLab Console.

Detect & Extract or Mark Faces

Next, move to a workflow that combines analysis and processing in the same request chain. First, detect all human faces in an image or video frame with FACEDETECT, then extract each detected face into a separate image with CROP. This pattern is useful for identity checks, KYC forms, and moderation pipelines.

Input Picture

Draw Rectangle instead of CROP

Extract (crop) face via CROP

This is easily done via the following code snippets:

To perform such operation, two endpoints are actually needed: One for the analysis phase, the other for processing:

• FACEDETECT is the analysis endpoint that must be called first. It outputs the rectangle coordinates for each detected face in a given image or video frame. This endpoint, its expected parameter, and JSON output result is documented here.
• CROP is called later after we obtain the rectangle coordinates for all the detected faces. In which case, we simply pass these coordinates to crop untouched and the target region of the image where each face is located is extracted and saved in a new image. Find out more information on the CROP endpoint here.
• Alternatively, if you prefer marking the face(s) instead of extracting it, you can rely on the DRAWRECTANGLE endpoint to perform such operation.

Detect & Blur Human Faces

The same two-step pattern can be used to blur detected faces in an image or video frame. This is a practical privacy workflow for user uploads, public content, journalism, moderation, and GDPR-sensitive applications.

Input Picture

Output Blurred Faces

Again, this is easily achieved using the following snippets:

• Just like the previous example, we relied on the FACEDETECT endpoint to output the rectangle coordinates for each present human face then, we immediately called the MOGRIFY endpoint, and we simply passed the facial coordinates untouched to mogrify to blur the target regions of the input image hence, the facial coordinates. The mogrify endpoint, its expected parameters, and output results is documented here.

Programmatically Generate MEMEs

Let's generate a funny MEME by drawing some text on top of the famous Cool Cat, public domain image using the DRAWTEXT API endpoint. Given an input image, draw some text on TOP & BOTTOM of the image to obtain something like this:

Input Picture

Output Picture, dynamically generated DRAWTEXT

The output picture with text drawn on TOP & BOTTOM was obtained via the following code snippets:

• DRAWTEXT is the sole endpoint needed to generate such image. It expect the text to be displayed on TOP, CENTER or BOTTOM of the target image. This endpoint is so flexible that you can supply Font Name, Size & Color, Stroke width, etc. Refer to DRAWTEXT documentation for additional information. Notice that there is a more flexible endpoint named DRAWTEXTAT which let you draw text on any region of the target image by specifying the X & Y coordinates instead.

Challenge Bots by Dynamic Image Generation

In this sample, we create a 300x300 PNG image on the fly with a yellow background and draw text on top. This is useful when you need a lightweight CAPTCHA-style challenge or any simple dynamically generated image asset.

Dynamically created using NEWIMAGE, text drawn via DRAWTEXT

• A blank image is requested first via a call NEWIMAGE which export to PNG by default but you can change the output format at request. We set the image height, width and the background color respectively to 300x300 with a yellow background color.
• Note, if one of the height or width parameter is missing (but not both), then the available length is applied to the missing side and if you want a transparent image set the color parameter to none.
• We finally DRAW our text at the center of the newly created image using the WOLF Font, black color and 35 px font size. One could also draw lines, a rectangle, and other shapes for example to surround faces, merge with other images and so on...

After generating such image, the automated script, hence the bot scrapping your platform, has to resolve your challenge by typing the text drawn on top of this image. The whole image creation process is done via the following code snippets:

Scan Passports, ID Cards & KYC Verification Check

In this sample, you will use the DOCSCAN endpoint to build a minimal KYC flow for a website or onboarding system and verify information submitted through an uploaded ID card or passport image.

Start by scanning a government-issued travel or identity document such as a passport, visa, or ID card using the DOCSCAN endpoint. In addition to extracting text fields, DOCSCAN can also crop the detected face from the document. A typical passport scan flow looks like this:

Input Passport Specimen

Extracted MRZ Fields

The extracted face, plus the scanned Passport MRZ fields were obtained via the following code snippets:

• DOCSCAN is the main endpoint needed for this workflow. It supports passports, visas, and a wide range of ID cards, and it can extract the face automatically.
• PixLab recommends connecting your own AWS S3 bucket via the dashboard ↗ so extracted faces and MRZ crops are stored in your own environment rather than the public PixLab one. Refer to the DOCSCAN documentation for supported fields, storage behavior, and PDF document handling.

Moderate Image Uploads According to their NSFW Score

In this last sample, we shall censor image uploads according to their NSFW score by applying a blur filter on each image if, and only if, its NSFW score is high enough. A typical blurred picture should look like the following after processing:

To filter, and obtain such blurred image, we used the following code snippets:

To perform such operation, two endpoints are actually needed. One for the analysis phase, the other for processing:

• NSFW is the analysis endpoint that must be called first. It does perform nudity & adult content detection and returns a score value between 0..1. The more this value approaches 1, the more your picture/frame is highly nsfw. Find out more information about NSFW here.
• BLUR is called later only if the nsfw score value returned earlier is greater than certain threshold. In our case, it is set to 0.5. The blur endpoint is documented here.

Further Reading

If you followed the tutorial from the start, you should now have a working understanding of how PixLab handles incoming HTTP requests and how to combine endpoints into practical workflows. Continue with the reference pages below, and use the GitHub sample repository when you want more end-to-end examples.