Image Collage

🚧

Note: This API is not generally available. Please contact us to get access to this API.

Create a Collage out of image assets, add text labels. Using this API, collages that can be created with various backgrounds, graphics and border images by cropping, positioning, rotating and stacking them in a certain order using API parameters.

HTTP HEADER for POST REQUESTS

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

HTTP POST REQUEST

HTTP POST https://app-dei-dev.filespin.io/api/v1/assets/addons/collage

REQUEST JSON

The API call should be made with a JSON request as below.

{
  "canvas": {
    "size": {
      "width": 1000,
      "height": 1000
    },
    "color": "#FFFFFF"
  },
  "assets": [
    {
      "id": "ASSET_ID_1",
      "size": {
        "width": 500,
        "height": 500
      },
      "crop": {
        "left": 0,
        "top": 0,
        "right": 200,
        "bottom": 300
      },
      "position": {
        "x": 0,
        "y": 0
      },
      "rotation": 0,
      "z_index": 1
    }
  ],
  "labels":[
    {
      "text": "Name",
      "size":{
        "width": 100,
        "height": 50
      }
      "font": {
        "style": "regular",
        "name": "timesnewroman",
        "size": 30,
        "bg_color": "#FFFFFF",
        "color": "#000000"
      },
      "position": {
        "x": 900,
        "y": 110
      },
      "z_index": 2,
      "rotation": 20
    }
  ],
  "disposition": {
    "metadata": {
      "inherit": true,
      "src_asset_id": "ASSET_ID_2",
      "inherit_fields": [
        "field1",
        "field2"
      ],
      "data": {
        "key1": "value1",
        "key2": "value2"
      }
    },
    "mode": "APPEND",
    "data_schema_id": 1
  }
}

Components

Each asset in the asset list can have its own options for size, position and crop. The options for each asset are as below.

📘

Note that the sequence of operations for an given asset id is: crop -> rotation -> size -> position

Note:

1. if crop options is provided, crop dimensions must be in pixel ( left, top, right, bottom ) must and should be with respect to the original image size associated with asset id. For example, if original asset has a size of 2000x2000, crop of left:0, top:0, right:100, bottom:200 will crop to this region in the original image. Note that invalid crop parameters will result in incorrect outputs.
2. if rotation options is provided, rotation is applied for an asset within the bounding box given by size parameters for the asset, (i.e) it will try to rotate the image within the size provided. The gaps introduced as an outcome of rotation will be filled with black color.

Adding a background to the collage

To add an image asset as background to the Collage, provide the asset ID as below. Note the size should be set to the size of the canvas and position should be 0,0 and z-index should be lowest to stack the image as the background.

"assets":[
  {
    "id":"ASSET_ID",
    "size":{
      "width": "SAME_AS_CANVAS_WIDTH",
      "height": "SAME_AS_CANVAS_HEIGHT"
    },
    "position":{
      "x": 0,
      "y": 0
    }
    "z_index": 0
  }
]

Adding an image as border to a collage

To add a border to the Collage, please provide the border image asset ID as specified below.

"assets":[
  {
    "id":"ASSET_ID",
    "size":{
      "width": "SAME_AS_CANVAS_WIDTH",
      "height": "SAME_AS_CANVAS_HEIGHT"
    },
    "position":{
      "x": 0,
      "y": 0
    }
    "z_index": 1000
  }
]

Adding an image as graphics to a collage

To add Graphics image to the Collage, please provide the graphics image asset ID as specified below where size, position, rotation, crop and z_index control how it is added to the collage.

"assets":[
  {
    "id":"ASSET_ID",
    "size":{
      "width": "100",
      "height": "100"
    },
    "position":{
      "x": 100,
      "y": 100
    },
      "crop": {
        "left": 0,
        "top": 0,
        "right": 200,
        "bottom": 300
      },    
    "rotation": 20,
    "z_index": 1,
  }
]

RESPONSE JSON

The API call will return with a JSON response as below.

{
    "job_id" : 1234
}

Retrieve image after processing completes

Use the Job API to retrieve the URL of the processed output image after Collage operation.

HTTP REQUEST

HTTP GET https://app-dei-dev.filespin.io/api/v1/assets/addons/collage/jobs/{job_id}

HTTP HEADER

X-FileSpin-Api-Key:API_KEY

Where API_KEY should be replaced with your API Key

RESPONSE JSON

The Job API call will return with a JSON response as below.

{
    "status": "SUCCESS",
    "data":{
      "asset_id": "NEW ASSET ID" ,
      "metadata": {}
    }
}