MERGE API Endpoint Documentation | PixLab Developers Handbook

API Endpoint Access URL

https://api.pixlab.io/merge

Description

Merge multiple images with specified offsets, ideal for integrating with media analysis endpoints like FaceDetect and FaceLandmarks to create Snapchat-like filters. Check the sample page for usage examples. Composite as much images as desired on top of another at a specified offset. This API endpoint is of particular interest if mixed with some media analysis endpoints such as facedetect or docscan in order to mimic the Snapachat filters effects for example. Refer to the sample page for a concrete usage.

HTTP Methods

POST

HTTP Parameters

Required

Fields	Type	Description
`src`	URL	Target image URL. This is the composited image. If you want to upload your image directly from your app, call store and use the output link before invoking `merge`.
`cord`	Array	JSON array holding the coordinates of the images to be merged with the target (Array fields are described 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 returns a JSON Object holding the link to the image output. If set to true, the image binary contents are returned instead.

POST Request Body

Allowed Content-Types:

application/json

Only JSON data is accepted. The cord parameter must be a JSON array containing object coordinates for each image to be composited on the target. Obtain these offsets from analysis API endpoints like docscan.

Fields	Type	Description
`img`	URL	Image URL to composite on the source. For direct uploads, call store first and use its output link.
`x`	Integer	X (column) coordinate offset for the composited image.
`y`	Integer	Y (row) coordinate offset for the composited image.
`center`	Boolean	When True, centers the image horizontally (X = Width/2) at the specified X offset.
`center_y`	Boolean	When True, centers the image vertically (Y = Height/2) at the specified Y offset.

A typical cord array:

cord = [
    {
     img: 'http://www.wowpng.com/wp-content/uploads/2016/10/lol-troll-face-png-image-october-2016-370x297.png',
      x: 200,
      y: 290
    },
    {
     img: 'http://orig08.deviantart.net/67d1/f/2010/216/6/7/lol_face_by_bloodyhalfdemon.png',
      x: 165,
      y: 95
    }
]

Tip: Use meme to add text overlays to your composited image.

HTTP Response

Fields	Type	Description
`status`	Integer	Status code 200 indicates success, any other code indicates failure.
`link`	URL	Link to the media output stored on pixlab.xyz storage unless custom S3 keys are configured (see console for setup).
`id`	String	Unique media identifier.
`error`	String	Error description when status ≠ 200.

Returns application/json when the optional blob parameter is omitted. Binary image data is returned directly when blob is enabled. The JSON response structure is documented above.

Code Samples


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

def composite_images(
    base_image_url: str,
    overlay_images: List[Dict[str, Any]],
    api_key: str
) -> str:
    """Composite multiple images onto a base image using PixLab API.
    
    Args:
        base_image_url: URL of the base image.
        overlay_images: List of dictionaries containing overlay image details.
        api_key: PixLab API key.
    
    Returns:
        URL of the composited image if successful, otherwise raises an exception.
    """
    endpoint = 'https://api.pixlab.io/merge'
    headers = {'Content-Type': 'application/json'}
    
    payload = {
        'src': base_image_url,
        'key': api_key,
        'cord': overlay_images
    }
    
    try:
        response = requests.post(
            endpoint,
            headers=headers,
            data=json.dumps(payload),
            timeout=10
        )
        response.raise_for_status()
        data = response.json()
        
        if data['status'] != 200:
            raise ValueError(f"API Error: {data.get('error', 'Unknown error')}")
        
        return data['link']
    
    except requests.exceptions.RequestException as e:
        raise ConnectionError(f"Request failed: {str(e)}") from e
    except json.JSONDecodeError as e:
        raise ValueError("Invalid JSON response from API") from e

# Example usage
if __name__ == "__main__":
    try:
        result_url = composite_images(
            base_image_url='https://pbs.twimg.com/media/CcEfpp0W4AEQVPf.jpg',
            overlay_images=[
                {
                    'img': 'http://www.wowpng.com/wp-content/uploads/2016/10/lol-troll-face-png-image-october-2016-370x297.png',
                    'x': 30,
                    'y': 320
                },
                {
                    'img': 'http://orig08.deviantart.net/67d1/f/2010/216/6/7/lol_face_by_bloodyhalfdemon.png',
                    'x': 630,
                    'y': 95
                }
            ],
            api_key='My_PIXLAB_API_KEY'
        )
        print(f"Composite image: {result_url}")
    except Exception as e:
        print(f"Error: {str(e)}")


fetch('https://api.pixlab.io/merge', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        src: 'https://pbs.twimg.com/media/CcEfpp0W4AEQVPf.jpg',
        key: 'My_PIXLAB_API_KEY',
        cord: [
            {
                img: 'http://www.wowpng.com/wp-content/uploads/2016/10/lol-troll-face-png-image-october-2016-370x297.png',
                x: 30,
                y: 320
            },
            {
                img: 'http://orig08.deviantart.net/67d1/f/2010/216/6/7/lol_face_by_bloodyhalfdemon.png',
                x: 630,
                y: 95
            }
        ]
    })
})
.then(response => response.json())
.then(reply => {
    if (reply.status !== 200) {
        console.log(reply.error);
    } else {
        console.log("Composite image: " + reply.link);
    }
})
.catch(error => console.error('Error:', error));

<?php
$data = [
    'src' => 'https://pbs.twimg.com/media/CcEfpp0W4AEQVPf.jpg',
    'key' => 'My_PIXLAB_API_KEY',
    'cord' => [
        [
            'img' => 'http://www.wowpng.com/wp-content/uploads/2016/10/lol-troll-face-png-image-october-2016-370x297.png',
            'x' => 30,
            'y' => 320
        ],
        [
            'img' => 'http://orig08.deviantart.net/67d1/f/2010/216/6/7/lol_face_by_bloodyhalfdemon.png',
            'x' => 630,
            'y' => 95
        ]
    ]
];

$ch = curl_init('https://api.pixlab.io/merge');
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 "Composite image: " . $reply['link'];
}


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

uri = URI.parse('https://api.pixlab.io/merge')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.request_uri)
request['Content-Type'] = 'application/json'
request.body = {
  'src' => 'https://pbs.twimg.com/media/CcEfpp0W4AEQVPf.jpg',
  'key' => 'My_PIXLAB_API_KEY',
  'cord' => [
    {
      'img' => 'http://www.wowpng.com/wp-content/uploads/2016/10/lol-troll-face-png-image-october-2016-370x297.png',
      'x' => 30,
      'y' => 320
    },
    {
      'img' => 'http://orig08.deviantart.net/67d1/f/2010/216/6/7/lol_face_by_bloodyhalfdemon.png',
      'x' => 630,
      'y' => 95
    }
  ]
}.to_json

response = http.request(request)
reply = JSON.parse(response.body)

if reply['status'] != 200
  puts reply['error']
else
  puts "Composite image: #{reply['link']}"
end

Similar API Endpoints

docscan, meme, mogrify, avatar, facedetect, crop, resize, grayscale, rotate, newimage