mergehttps://api.pixlab.io/merge
Description
Composite as much images as desired on top of another at a specified offset. This command is of particular interest if mixed with some media analysis endpoints such as facedetect or facelandmarks in order to mimic the Snapachat filters effects for example. Refer to the sample page for a concrete usage.
HTTP Methods
POST
Request 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 command 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. |
POST Request Body
Allowed Content-Type:
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 image and its offset to be composited on top of the target image. You can obtain these offsets from an analysis command like facelandmarks for example. The following are the required parameters for each object in the cord array:
| Fields | Type | Description |
|---|---|---|
| img | URL | Image URL to be composited on top of the source. If you want to upload an image directly from your app, call the store command and use the output link before invoking merge. |
| x | Integer | X (column offset) coordinate of the of the composited image. |
| y | Integer | Y (row offset) coordinate of the of the composited image. |
| center | Boolean | If True then superpose the middle X point of this image (Width / 2) on top of the X (column offset) point. This is very useful if you want the engine to calculate the best position for you. |
| center_y | Boolean | If True then superpose the middle Y point of this image (Height / 2) on top of the Y (row offset) point. This is very useful if you want the engine to calculate the best position for you |
A typical cord array should look like this (See the example section for a working snippet).
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 draw some text on top of your composited image!
Response
application/json if the optional blob parameter is not set.
This command return a JSON object after each call only if the optional blob parameter is not set. Otherwise the image binary contents is returned instead. The following are the JSON fields returned in response body:
| Fields | Type | Description |
|---|---|---|
| status | Integer | Status code 200 indicates success, any other code indicates failure. |
| link | URL | Link to the media 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. |
Python Example
import requests
import json
# Composite two smiley on top of the famous Michael jordan crying face. A more sophisticated approach would be to extract the face landmarks using facelandmarks and composite something on the different regions.
req = requests.post('https://api.pixlab.io/merge',
headers={'Content-Type':'application/json'},
data=json.dumps({
'src':'https://pbs.twimg.com/media/CcEfpp0W4AEQVPf.jpg',
'key':'My_Pix_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
}]
})
)
reply = req.json()
if reply['status'] != 200:
print (reply['error'])
else:
print ("Composite image: "+ reply['link'])