Video slideshow generation (Beta)

Important
Video slideshow generation is currently in Beta. There may be minor changes to parameter names or other implementation details before the general access release. We invite you to try it out. We would appreciate any feedback via our support team.

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:
    • 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.

Notes

  • You must have the template file (.clt) in your account for slideshow generation to work. Download the template and upload it to your account as a video file. The public ID, including the folder structure, is used as part of the slideshow URL.
  • If the configured duration is less than the combined total duration of the individual videos and transitions, the video will be cut short.

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.

Note
Slideshow generation occurs asynchronously after the initial request. As a result, an HTTP 423 error will be returned whilst the final slideshow is generated. Refresh your browser after several seconds or minutes to see the result.

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.

Important
Slideshow generation is not currently supported by our SDKs. To use the create_slideshow method, you need to make a direct request to the API. For a signed upload you need to include a signature with your request, see the signature generation guide for more information. For unsigned uploads, you need to include an upload preset.

Syntax

You need to provide the manifest_transformation or 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:
  • Individual slides: The media to include in the individual slides and any settings specific to that slide.

manifest_transformation

The manifest_transformation parameter is included as a string that follows the same syntax as when creating a slideshow using a delivery URL:

The syntax is designed to allow the slideshow settings to be constructed as a URL string 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.

Here's an example manifest_transformation:

Copy to clipboard
fn_render:w_500;h_500;du_25;vars_(sdur_3000;tdur_1500;transition_s:circlecrop;slides_((media_i:sample);(media_i:sample2);(media_i:sample3);(media_i:sample4)))

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:

Copy to clipboard
"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

Using manifest_transformation:

Copy to clipboard
curl https://api.cloudinary.com/v1_1/demo/video/create_slideshow -X POST --data 'public_id=test_slideshow&resource_type=video&manifest_transformation=fn_render:w_500;h_500;du_25;vars_(sdur_3000;tdur_1500;transition_s:circlecrop;slides_((media_i:sample);(media_i:sample2);(media_i:sample3);(media_i:sample4)))&timestamp=173719931&api_key=436464676&signature=a781d61f86a6f818af'

Using manifest_json:

Copy to clipboard
curl 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

Using manifest_transformation:

Copy to clipboard
curl https://api.cloudinary.com/v1_1/demo/video/create_slideshow -X POST --data 'public_id=test_slideshow&resource_type=video&upload_preset=Default&manifest_transformation=fn_render:w_500;h_500;du_25;vars_(sdur_3000;tdur_1500;transition_s:circlecrop;slides_((media_i:sample);(media_i:sample2);(media_i:sample3);(media_i:sample4)))'

Using manifest_json:

Copy to clipboard
curl 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:sample"}]}}'

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.

Copy to clipboard
{
    "status": "processing",
    "public_id": "test_slideshow",
    "batch_id": "00b45635e533ab11e63585dd145ab7816ca19bff2bf3f298a0e66d87405ab7793"
}
Copy to clipboard
{
  "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

Parameter Description
w Required. The width of the slideshow in pixels.
h Required. The height of the slideshow in pixels.
du The duration of the slideshow in seconds. Default: 10.
fps The frames per second of the slideshow. Default: 20.

Slide settings

Parameter Description
vars_ Signals the start of the slide settings.
transition_s: The transition to use for all slides. Default: CrossZoom.
transformation_s: A single transformation to apply to all slides. Default: null.
sdur The duration for all slides in milliseconds. Default: 3000.
tdur The duration for all transitions in milliseconds. Default: 1000.
slides_ The slides to appear in the video. See Individual slide settings.

Individual slide settings

Parameter Description
media_: The type of media. Specify images as media_i:<public_id>. Specify videos as media_v:<public_id>.
type_s The slide type. Set to video when using a video for a slide. For example: media_v:my-public-id;type_s:video. Default: image.
transition_s The transition to use from the individual slide to the next. Default: CrossZoom.
sdur The slide duration in milliseconds. Default: 3000.
tdur The transition duration in milliseconds. Default: 1000.

✔️ Feedback sent!

Rate this page: