Image collage generation

Overview

Image collages are composed of several different images, combined together in a specific layout.

You can programmatically create image collages by combining assets that you've already uploaded to your Media Library. By defining a template, and specifying spacing and colors, you can choose the composition of the overall collage.

This collage is composed of four images in one row, with black spacing between each:

Fashion collage

To create a collage you need to supply a manifest_json to the create_collage endpoint of the Upload API.

Note

There is no SDK support yet for create_collage. You need to call the REST API directly. To help you, you can use our Postman collection.

Collage composition

There are two ways to specify the layout of the collage:

Predefined templates

One predefined template is currently supported: grid.

With this template you specify the number of columns and rows, then provide the public ID for each of the assets in the grid. Each image within the grid layout is of equal dimensions.

In the following example we specify a 3x3 grid with a total height and width of 500 px. The assets are spaced 1 pixel apart, with a blue background. The public IDs of nine assets are specified and each asset is cropped to fill the available space with auto gravity.

The manifest_json looks like this:

Copy to clipboard
manifest_json={
  "template": "grid",
  "width": 500,
  "height": 500,
  "columns": 3,
  "rows": 3, 
  "spacing": 1,
  "color": "blue",
  "assetDefaults": { "kind": "upload", "crop": "fill", "gravity": "auto"},
  "assets":  [{ "media": "docs/sample" }, 
              { "media": "docs/sample1" },
              { "media": "docs/sample2" }, 
              { "media": "docs/sample3" },
              { "media": "docs/sample4" },
              { "media": "docs/sample5" }, 
              { "media": "docs/sample6" }, 
              { "media": "docs/sample7" },
              { "media": "docs/sample8" }]
}

And the whole create_collage request looks like this:

Copy to clipboard
curl https://api.cloudinary.com/v1_1/demo/image/create_collage -X POST --data 'public_id=test_collage&resource_type=image&manifest_json={"template": "grid","width": 500,"height": 500,"columns": 3,"rows": 3, "spacing": 1,"color": "blue","assetDefaults": { "kind": "upload", "crop": "fill", "gravity": "auto"},"assets": [{ "media": "docs/sample" }, { "media": "docs/sample1" },{ "media": "docs/sample2" }, { "media": "docs/sample3" },{ "media": "docs/sample4" },{ "media": "docs/sample5" }, { "media": "docs/sample6" }, { "media": "docs/sample7" },{ "media": "docs/sample8" }]}&timestamp=173719931&api_key=436464676&signature=a781d61f86a6f818af'

The resulting collage is delivered with the URL that is returned in the response:

Ruby (cloudinary 1.x):
Copy to clipboard
cl_image_tag("test_collage.png")
PHP (cloudinary_php 2.x):
Copy to clipboard
(new ImageTag('test_collage.png'));
PHP (cloudinary_php 1.x (legacy)):
Copy to clipboard
cl_image_tag("test_collage.png")
Python (cloudinary 1.x):
Copy to clipboard
CloudinaryImage("test_collage.png").image()
Node.js (cloudinary 1.x):
Copy to clipboard
cloudinary.image("test_collage.png")
Java (cloudinary 1.x):
Copy to clipboard
cloudinary.url().transformation(new Transformation().imageTag("test_collage.png");
JS (@cloudinary/url-gen 1.x):
Copy to clipboard
new CloudinaryImage("test_collage.png");
JS (cloudinary-core 2.x (legacy)):
Copy to clipboard
cloudinary.imageTag('test_collage.png').toHtml();
jQuery (cloudinary-jquery 2.x):
Copy to clipboard
$.cloudinary.image("test_collage.png")
React (@cloudinary/react 1.x):
Copy to clipboard
//React SDK transformations are created using @cloudinary/url-gen.
new CloudinaryImage("test_collage.png");
React (cloudinary-react 1.x):
Copy to clipboard
<Image publicId="test_collage.png" >

</Image>
Vue.js (cloudinary-vue 1.x):
Copy to clipboard
<cld-image public-id="test_collage.png" >

</cld-image>
Angular (@cloudinary/ng 1.x):
Copy to clipboard
//Angular SDK transformations are created using @cloudinary/url-gen.
new CloudinaryImage("test_collage.png");
Angular (@cloudinary/angular-5.x 1.x (legacy)):
Copy to clipboard
<cl-image public-id="test_collage.png" >

</cl-image>
.NET (CloudinaryDotNet 1.x):
Copy to clipboard
cloudinary.Api.UrlImgUp.BuildImageTag("test_collage.png")
iOS (cloudinary 3.x):
Copy to clipboard
imageView.cldSetImage(cloudinary.createUrl().generate("test_collage.png")!, cloudinary: cloudinary)
Android (cloudinary-android 1.x):
Copy to clipboard
MediaManager.get().url().transformation(new Transformation().generate("test_collage.png");
Kotlin (kotlin-url-gen 1.x):
Copy to clipboard
cloudinary.image {
  publicId("test_collage.png") 
}.generate()
Cat collage

Custom templates

Custom templates let you create collages in layouts that allow for different dimensions of images. For example:

Cat collage of different sizes

To achieve this layout, specify a two dimensional matrix for template, using numbers to represent the same asset and the area of the canvas that the image will cover.

So, for a canvas that looks like this:

Template layout

Use a matrix that looks like this:

Copy to clipboard
"template": 
[[1,1,2,3,4,4],
 [1,1,5,5,4,4],
 [6,6,5,5,4,4],
 [6,6,7,7,4,4]]

Each number refers to an asset in the assets array. So, for the assets defined below, 1 refers to the asset with public ID docs/sample, 2 refers to the asset with public ID docs/sample1, and so on.

Copy to clipboard
  "assets": [{ "media": "docs/sample" },
             { "media": "docs/sample1" },
             { "media": "docs/sample2"},
             { "media": "docs/sample3" },
             { "media": "docs/sample4"},
             { "media": "docs/sample5"},
             { "media": "docs/sample6"}]

Notes

  • You cannot use the same number in different areas of the canvas. To use the same asset in a different position, specify more than one entry in the assets array with the same public ID. For example, making the image at positions 1, 4 and 6 the same asset (docs/sample):
Copy to clipboard
    "assets": [{ "media": "docs/sample" },
              { "media": "docs/sample1" },
              { "media": "docs/sample2"},
              { "media": "docs/sample" },
              { "media": "docs/sample4"},
              { "media": "docs/sample"},
              { "media": "docs/sample6"}]
  • Each defined area must be a whole square or rectangle.

Here's the whole manifest_json for the cat collage above:

Copy to clipboard
manifest_json={
  "template": [[1,1,2,3,4,4],
               [1,1,5,5,4,4],
               [6,6,5,5,4,4],
               [6,6,7,7,4,4]],
  "width": 600,
  "height": 400,
  "columns": 6, 
  "rows": 4,
  "spacing": 7,
  "color": "brown",
  "assetDefaults": { "kind": "upload", "crop": "fill", "gravity": "auto"},
  "assets": [{ "media": "docs/sample" },
             { "media": "docs/sample1" },
             { "media": "docs/sample2"},
             { "media": "docs/sample3" },
             { "media": "docs/sample4" },
             { "media": "docs/sample5"},
             { "media": "docs/sample6"}]
}

This is the full create_collage request to create the collage:

Copy to clipboard
curl https://api.cloudinary.com/v1_1/demo/image/create_collage -X POST --data 'public_id=docs/collage_template&resource_type=image&manifest_json={"template": [[1,1,2,3,4,4],[1,1,5,5,4,4],[6,6,5,5,4,4],[6,6,7,7,4,4]],"width": 600,"height": 400,"columns": 6, "rows": 4,"spacing": 7,"color": "brown","assetDefaults": { "kind": "upload", "crop": "fill", "gravity": "auto"},"assets": [{ "media": "docs/sample" },{ "media": "docs/sample1" },{ "media": "docs/sample2"},{ "media": "docs/sample3" },{ "media": "docs/sample4" },{ "media": "docs/sample5"},{ "media": "docs/sample6"}]}&timestamp=173719931&api_key=436464676&signature=a781d61f86a6f818af'

Individual assets

The assetDefaults parameter specifies the default settings for each of the assets. These can be overridden on a per-asset basis by specifying the asset settings in each asset entry, for example:

Copy to clipboard
"assetDefaults": { "kind": "upload", "crop": "fill", "gravity": "center"},
"assets": [{ "media": "docs/sample1", "crop": "pad", "gravity": "center", "color": "auto" },
           { "media": "docs/sample2", "crop": "pad", "gravity": "north", "color": "red" },
           { "media": "docs/sample3", "crop": "pad", "gravity": "southwest", "color": "#FEB61F" },
           { "media": "docs/sample4", "gravity": "auto", "color": "#FEB61FC2" }]

In the following example, the corner and center images use the asset default settings ("crop": "fill", "gravity": "center"), but the other images are padded using different gravities and colors:

Copy to clipboard
manifest_json={
  "template": [[1,2,3,4],
               [5,6,6,7],
               [8,6,6,9], 
               [10,11,12,13]],
  "width": 800,
  "height": 800,
  "columns": 4, 
  "rows": 4,
  "spacing": 0,
  "color": "black",
  "assetDefaults": { "kind": "upload", "crop": "fill", "gravity": "center"},
  "assets": [{ "media": "docs/pic1"},
             { "media": "docs/pic2", "crop": "pad", "gravity": "north", "color": "red" },
             { "media": "docs/pic3", "crop": "pad", "gravity": "north", "color": "yellow" },
             { "media": "docs/pic4" },
             { "media": "docs/pic5", "crop":"pad", "gravity": "west", "color": "yellow" },
             { "media": "docs/pic6"},
             {"media": "docs/pic7", "crop": "pad", "gravity": "east", "color": "blue"},
             { "media": "docs/pic8", "crop":"pad", "gravity": "west", "color": "blue" },
             {"media": "docs/pic9", "crop": "pad", "gravity": "east", "color": "red"},
             { "media": "docs/pic10"},
             { "media": "docs/pic11", "crop": "pad", "gravity": "south", "color": "yellow" },
             { "media": "docs/pic12", "crop": "pad", "gravity": "south", "color": "blue" },
             { "media": "docs/pic13"}]
}

Collage of houses

Note
The creation of one image collage counts as one transformation, regardless of the number of images contained within it.

Asynchronous handling

Although collage creation usually only take a few seconds, it is still handled asynchronously. Therefore, the immediate response to the create_collage request indicates that the status is processing:

Copy to clipboard
{
    "status": "processing",
    "public_id": "docs/collage_template",
    "batch_id": "1d6a19863de6c2faa80572ef05cd0eda1c38f009e28055b404c09429696853f0"
}

To receive a notification when the collage is ready, add the notification_url parameter to your request. The JSON response includes the new url and secure_url:

Copy to clipboard
{
  "notification_type": "upload",
  "timestamp": "2022-05-27T11:12:46+00:00",
  "request_id": "65b6a1b71e48d64dffb5bf3d27617eb0",
  "asset_id": "e5dd5615d4a4c90bda4e3df1da9fe1a3",
  "public_id": "docs/collage_template",
  "version": 1653649960,
  "version_id": "5e3aff06cfb04e985edd4035ad2a64af",
  "width": 600,
  "height": 400,
  "format": "png",
  "resource_type": "image",
  "created_at": "2022-05-27T11:12:40Z",
  "tags": [],
  "pages": 1,
  "bytes": 365104,
  "type": "upload",
  "etag": "7f3a8006a3ef2da7537116309f4dea23",
  "placeholder": false,
  "url": "http://res.cloudinary.com/demo/image/upload/v1653649960/docs/collage_template.png",
  "secure_url": "https://res.cloudinary.com/demo/image/upload/v1653649960/docs/collage_template.png",
  "folder": "docs",
  "access_mode": "public"
}

Reference

These settings apply to the manifest_json parameter of the create_collage method.

See examples of a manifest_json for predefined templates, custom templates, and custom templates with individual asset specifications.

Global settings

Parameter Description
template Required. The name of the predefined template (currently only grid is supported) or a two dimensional custom matrix.
width Required. The total width of the output image collage.
height Required. The total height of the output image collage.
columns Required. The number of columns in the template.
rows Required. The number of rows in the template.
spacing Required. The space (in pixels) between individual images in the collage and from the outer boundaries. Specify 0 for no spacing.
color Required. The background (canvas) color. Specify any color name or a 3-, 4-, 6- or 8-digit RGB hex number with a hash (e.g. #FEB61F).
assetDefaults Required. Default asset parameters to apply to all assets unless overwritten in the asset entry.

Asset settings

Parameter Description
media Required. The public ID of an asset.
kind The delivery type of the asset. Specify upload, restricted or fetch.

Default: upload.

crop The type of crop. Specify fill or pad. For details of the cropping modes see fill and pad.

Default: pad.

gravity The gravity of the crop. Specify center, north_west, north_east, south_west, south_east, north, west, south, east, or auto.

Default: center.

color The background color of the asset if pad is used. Specify any color name, a 3-, 4-, 6- or 8-digit RGB hex number with a hash (e.g. #FEB61F) or auto for the predominant color.

Default: auto.

✔️ Feedback sent!

Rate this page: