MOGRIFY API Endpoint

Version 2.197 (Release Notes ↗)

Description

MOGRIFY is an API endpoint that applies a blur filter to one or more regions of an input image, commonly used for blurring faces or body parts in face detection and adult content detection. Unlike the general blur endpoint, MOGRIFY processes specific regions for precise content moderation. Apply a blur filter to one or more regions of a given input image. Mogrify is very popular within face and adult content detection endpoints such as facedetect, nsfw, etc. that can be used to blur faces or body parts unlike blur which process the whole image instead of a region of it. (See below for a working example).

HTTP Methods

POST

HTTP Parameters

Required

Fields Type Description
img URL Input media URL. If you want to upload your image directly from your app, call store before invoking this one.
cord Array JSON array holding the coordinates of the regions that takes the blur filter (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.
radius Float Blur radius (Default value is set to 30.00).
sigma Float Standard deviation (Max value is set to 30.00).

POST Request Body

Allowed Content-Types:

application/json

Only JSON data is allowed. The field of interest here is the cord parameter which must be a JSON array holding the object coordinates of each region that takes the blur filter on the input image. You can obtain these coordinates from an analysis API endpoint like facedetect for example. The following are the required parameters for each object in the cord array:

Fields Type Description
x Integer X coordinate of the top left corner. You can also substitute x with left as a field name.
y Integer Y coordinate of the top left corner. You can also substitute y with top as a field name.
width Integer Width of the desired rectangle.
height Integer Height of the desired rectangle.

So, a typical cord array should look like the following: (refer to the example section for a working snippet)

cord = [
    {
      x: 200,
      y: 290,
      width: 90,
      height: 60
    },
    {
      x: 165,
      y: 95,
      width: 145,
      height: 145,
      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 media ID.
error String Error message if status != 200.

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

This API endpoint returns a JSON Object after each call only if the optional blob parameter is omitted. Otherwise, the raw image binary is returned. The JSON response structure is documented above.

Code Samples


import requests
import json
import sys

def blur_faces(image_url: str, api_key: str) -> None:
    """Detect and blur faces in the given image using PixLab API."""
    
    # Detect faces
    try:
        detect_response = requests.get(
            'https://api.pixlab.io/facedetect',
            params={'img': image_url, 'key': api_key},
            timeout=10
        )
        detect_response.raise_for_status()
        detect_data = detect_response.json()
        
        if detect_data['status'] != 200:
            print(f"Error: {detect_data.get('error', 'Unknown error')}")
            sys.exit(1)
            
        faces = detect_data.get('faces', [])
        total_faces = len(faces)
        print(f"{total_faces} face(s) were detected")
        
        if total_faces < 1:
            sys.exit(0)
            
        # Blur detected faces
        blur_response = requests.post(
            'https://api.pixlab.io/mogrify',
            headers={'Content-Type': 'application/json'},
            json={
                'img': image_url,
                'key': api_key,
                'cord': faces
            },
            timeout=10
        )
        blur_response.raise_for_status()
        blur_data = blur_response.json()
        
        if blur_data['status'] != 200:
            print(f"Error: {blur_data.get('error', 'Unknown error')}")
        else:
            print(f"Face blurred picture location: {blur_data['ssl_link']}")
            
    except requests.exceptions.RequestException as e:
        print(f"API request failed: {str(e)}")
        sys.exit(1)
    except json.JSONDecodeError:
        print("Error: Invalid API response")
        sys.exit(1)

if __name__ == "__main__":
    IMAGE_URL = 'http://anewscafe.com/wp-content/uploads/2012/05/Brave-Faces-Group-shot.jpg'
    API_KEY = 'PIXLAB_API_KEY'  # Replace with your actual API key
    blur_faces(IMAGE_URL, API_KEY)
← Return to API Endpoint Listing