Video slideshow generation (Beta)

Combine your new and existing assets to create auto-generated video slideshows. Build up your slideshows using videos and images and select how you want to transition between each.

Some examples of how you might use video slideshows include:

• Creating a personalized video of a user's recent items.
• Creating a personalized video of items a user left in their shopping cart.
• Creating a daily sale video of different products automatically.
• Creating a real-estate video out of apartment images.

Generating a slideshow

You can generate a slideshow in two different ways depending on your use case:

• Using a delivery URL - Combine the relevant components in a delivery URL. This method uses a CLT template file that is uploaded to your account. All slideshows will be generated as a derived version of this template file and you can edit and tweak the various settings by applying URL transformations and seeing the resulting derived version.
• Using the Upload API - Use the create_slideshow method of the Upload API. This method creates a new original video in your Cloudinary account based on the parameters provided. Once the video slideshow is created you can generate subsequent derived versions with standard Cloudinary transformations. To edit the slideshow itself you must generate a new video or overwrite the existing one using the API.

Using a delivery URL

Components

Each slideshow is comprised of a number of components:

• Template: Defined by Cloudinary specifically for video slideshows. Download the template and upload it to your Cloudinary account as a video file. In the future, template creation will be available to support additional use cases.
• Manifest transformation: The components of the slideshow itself including all the relevant slides, transitions and transformations:
  • Global settings: Settings to apply to the whole video, such as resolution, duration and frames per second.
  • Slide settings: Settings to apply to all slides, such as:
    • Slide duration
    • Transition effect - see supported transitions
    • Transition duration
    • Transformation
  • Individual slides: The media to include in the individual slides and any settings specific to that slide.
• Global transformations: Transformations to apply post-production to the generated slideshow, see the Transformation URL API Reference for all available transformations.

Syntax

Use the following URL syntax to create a video slideshow using a delivery URL:

https://res.cloudinary.com/<cloudname>/video/upload/fn_render:<global-settings>;vars_(<slide-settings>(<individual-slide>))/<global-transformations>/<template>.<ext>

The URL syntax is designed to allow the slideshow settings to be constructed as a URL instead of a data structure. The characters used are defined as:

• ( - Start of list or object (key/value list)
• ) - End of list or object
• ; - Separator between values in list or object
• _ - Key/value separator in a object

Additional syntax is used to signify the beginning of the relevant components:

• fn_render - Signals the beginning of the transformation as a whole.
• vars - Signals the beginning of the slide settings data structure.

See the reference for full details on the relevant options.

Examples

Example with images only:

• Images: 4
• Width: 500px
• Height: 500px
• Duration: 20 seconds
• Slide Duration: 3000 milliseconds
• Transition Duration: 1500 milliseconds
• Transition: circlecrop

Example with videos and images:

• Images: 3
• Videos: 1
• Width: 640px
• Height: 480px
• Duration: 20 seconds
• Slide Duration: 3000 milliseconds
• Transition Duration: 1500 milliseconds
• Transition: hexagonalize

Example with custom slide durations:

• Images: 4
• Width: 500px
• Height: 500px
• Duration: 18 seconds
• Slide Durations: 2000, 4000, 3000, 3000 milliseconds
• Transition Duration: 1500 milliseconds
• Transition: hexagonalize

Example with slide transformation:

• Images: 4
• Width: 500px
• Height: 500px
• Duration: 18 seconds
• Slide Durations: 2000, 4000, 3000, 3000 milliseconds
• Transition Duration: 1500 milliseconds
• Transition: hexagonalize
• Slide Transformation: Fes filter

Using the Upload API

To create a new slideshow using the Upload API, send a POST request to the create_slideshow method. Your slideshow will be generated asynchronously as a video and will be added as an original to your media library.

Syntax

You need to provide the manifest_json parameter as part of your request. This parameter includes all of the relevant configuration for the slideshow itself including all the relevant slides, transitions and transformations:

• Global settings: Settings to apply to the whole video, such as resolution, duration and frames per second.
• Slide settings: Settings to apply to all slides, such as:
  • Slide duration
  • Transition effect - see supported transitions
  • Transition duration
  • Transformation
• Individual slides: The media to include in the individual slides and any settings specific to that slide.

manifest_json

The manifest_json parameter is a stringified json parameter, allowing you to define your slideshow settings in a structured data format, which then needs to be converted to a string.

See the reference for full details on the relevant options.

Here's an example manifest_json:

"manifest_json": {
    "w": 500,
    "h": 500,
    "du": 6,
    "fps": 30,
    "vars": {
        "sdur": 500,
        "tdur": 500,
        "slides": [
            {
                "media": "i:sample"
            },
            {
                "media": "i:sample2"
            },                
            {
                "media": "i:sample3"
            },
            {
                "media": "i:sample4"
            }
        ]
    }
}

Examples

Example signed upload with images only

Cloudinary::Uploader.create_slideshow(
    :manifest_json => {"w":500,"h":500,"du":8,"vars":{"sdur":3000,"tdur":1500,"slides":[{"media":"i:sample"},{"media":"i:sample"}]}},
    :public_id => "test_slideshow"
)

$cloudinary->uploadApi->createSlideshow([
    'manifest_json' => [
            "w"    => 500,
            "h"    => 500,
            "du"   => 8,
            "vars" => [
                "sdur"   => 3000,
                "tdur"   => 1500,
                "slides" => [
                    ["media" => "i:sample"],
                    ["media" => "i:sample"],
                ],
            ],
        ],
    'public_id' => 'test_slideshow'
    ]
]);

uploader.create_slideshow(
    manifest_json={
        "w":500,
        "h":500,
        "du":8,
        "vars":{
            "sdur":3000,
            "tdur":1500,
            "slides":[
                {"media":"i:sample"},
                {"media":"i:sample"}
            ]
        }
    },
    public_id="test_slideshow"
)

cloudinary.v2.uploader
.create_slideshow({
    manifest_json: {
        w: 500,
        h: 500,
        du: 8,
        vars: {
            sdur: 3000,
            tdur: 1500,
            slides: [
                { media: "i:sample" },
                { media: "i:sample" },
            ],
        },
    },
    public_id: 'test_slideshow'
})
.then(result=>console.log(result));

var slideshowParams = new CreateSlideshowParams()
{  
      ManifestJson = new SlideshowManifest
      {
          Width = 500,
          Height = 500,
          Duration = 8,
          Variables = new Slideshow
          {
              SlideDuration = 1500,
              TransitionDuration = 3000,
              Slides = new List<Slide>
              {
                  new Slide { Media = "i:sample" },
                  new Slide { Media = "i:sample" },
              },

          }
      },
      PublicId = "test_slideshow"
}
var slideshowResult = cloudinary.CreateSlideshow(slideshowParams);

https://api.cloudinary.com/v1_1/demo/video/create_slideshow -X POST --data 'public_id=test_slideshow&resource_type=video&manifest_json={"w":500,"h":500,"du":8,"vars":{"sdur":3000,"tdur":1500,"slides":[{"media":"i:sample"},{"media":"i:sample"}]}}&timestamp=173719931&api_key=436464676&signature=a781d61f86a6f818af'

Example unsigned upload with images only

Cloudinary::Uploader.create_slideshow(
    :manifest_json => {"w":500,"h":500,"du":8,"vars":{"sdur":3000,"tdur":1500,"slides":[{"media":"i:sample"},{"media":"i:sample"}]}},
    :public_id => "test_slideshow",
    :upload_preset => "Default"
)

$cloudinary->uploadApi->createSlideshow([
    'manifest_json' => [
            "w"    => 500,
            "h"    => 500,
            "du"   => 8,
            "vars" => [
                "sdur"   => 3000,
                "tdur"   => 1500,
                "slides" => [
                    ["media" => "i:sample"],
                    ["media" => "i:sample"],
                ],
            ],
        ],
    'public_id' => 'test_slideshow',
    'upload_preset' => 'Default'
    ]
]);

uploader.create_slideshow(
    manifest_json={
        "w":500,
        "h":500,
        "du":8,
        "vars":{
            "sdur":3000,
            "tdur":1500,
            "slides":[
                {"media":"i:sample"},
                {"media":"i:sample"}
            ]
        }
    },
    public_id="test_slideshow",
    upload_preset="Default"
)

cloudinary.v2.uploader
.create_slideshow({
    manifest_json: {
        w: 500,
        h: 500,
        du: 8,
        vars: {
            sdur: 3000,
            tdur: 1500,
            slides: [
                { media: "i:sample" },
                { media: "i:sample" },
            ],
        },
    },
    public_id: 'test_slideshow',
    upload_preset: 'Default'
})
.then(result=>console.log(result));

var slideshowParams = new CreateSlideshowParams()
{  
      ManifestJson = new SlideshowManifest
      {
          Width = 500,
          Height = 500,
          Duration = 8,
          Variables = new Slideshow
          {
              SlideDuration = 1500,
              TransitionDuration = 3000,
              Slides = new List<Slide>
              {
                  new Slide { Media = "i:sample" },
                  new Slide { Media = "i:sample" },
              },

          }
      },
      PublicId = "test_slideshow",
      UploadPreset = "Default"
}
var slideshowResult = cloudinary.CreateSlideshow(slideshowParams);

https://api.cloudinary.com/v1_1/demo/video/create_slideshow -X POST --data 'public_id=test_slideshow&resource_type=video&upload_preset=Default&manifest_json={"w":500,"h":500,"du":8,"vars":{"sdur":3000,"tdur":1500,"slides":[{"media":"i:sample"},{"media":"i:sample2"}]}}'

Sample Response

The following is a sample response based on the examples above. As slideshow generation occurs asynchronously, a notification is sent once the slideshow has been successfully generated. You can see an example of the notification response below.

{
    "status": "processing",
    "public_id": "test_slideshow",
    "batch_id": "00b45635e533ab11e63585dd145ab7816ca19bff2bf3f298a0e66d87405ab7793"
}

{
  "notification_type": "upload",
  "timestamp": "2021-08-11T07:44:41+00:00",
  "request_id": "799b0f8305df4206b6d8f5dbdde0cdfc",
  "asset_id": "640cb419bed70ef5b86e2bbe7cbb388a",
  "public_id": "test_slideshow",
  "version": 1628667799,
  "version_id": "afcd9bdec6552adc43d7f316da077200",
  "width": 500,
  "height": 500,
  "format": "mp4",
  "resource_type": "video",
  "created_at": "2021-08-11T07:43:19Z",
  "tags": [],
  "pages": 0,
  "bytes": 521868,
  "type": "upload",
  "etag": "d7b3ecf1f5508af9fb8518158e78642f",
  "placeholder": false,
  "url": "http://res.cloudinary.com/demo/video/upload/v1628667799/test_slideshow.mp4",
  "secure_url": "https://res.cloudinary.com/demo/video/upload/v1628667799/test_slideshow.mp4",
  "access_mode": "public",
  "audio": {},
  "video": {
    "pix_format": "yuv420p",
    "codec": "h264",
    "level": 30,
    "profile": "High",
    "bit_rate": "163900",
    "time_base": "1/15360"
  },
  "frame_rate": 30,
  "bit_rate": 166997,
  "duration": 25,
  "rotation": 0,
  "nb_frames": 750
}

Reference

Global settings

Slide settings

Individual slide settings