Programmable Media
Menu

Video slideshow generation (deprecated)

Last updated: Jul-10-2024

Important
Video slideshow generation has been deprecated. If you are still using this feature, you may want to try video generation instead, which supports the same features, plus more.

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.

See also: Cross fade transitions for a simple way to concatenate media on the fly.

On this page:

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 Cloudinary. 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 Cloudinary 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 Cloudinary 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) stored in Cloudinary for slideshow generation to work. Download the template and upload it to Cloudinary as a video file. The public ID 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 Cloudinary storage.

Important
If you're making a direct request to the API (not using an SDK) 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_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_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:

Examples

Example signed upload with images only

Example unsigned upload with images only

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.

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.

create_slideshow

Run in Postman Learn more about running Postman collections

Syntax

POST /video/create_slideshow

Required parameters

Parameter Type Description
manifest_json String The slideshow specific manifest transformation as stringified JSON that specifies the assets to use as well as durations, transitions and any slide specific transformations. See the slideshow generation reference for full details on syntax.
signature String (Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters. For more details, see manually generating signatures.
upload_preset String (Required for unsigned uploading / optional for signed uploading) Name of an upload preset that you defined for your Cloudinary product environment. An upload preset consists of upload parameters centrally managed using the Admin API or from the Upload page of your Console Settings. An upload preset may be marked as unsigned, which allows unsigned uploading directly from the browser and restricts the optional parameters to: public_id, folder, tags, context, face_coordinates, regions and custom_coordinates.

Optional parameters

Parameter Type Description
public_id String The identifier that is used for accessing or delivering the slideshow video.

If not specified, then the public ID of the slideshow video will be comprised of random characters.

Note: The public ID value for slideshow videos should not include a file extension.
transformation String A transformation to apply to the slideshow after it has been generated. This parameter is given as a comma-separated list of transformations, and separated with a slash for chained transformations.
overwrite Boolean Whether to overwrite existing assets with the same public ID. When set to false, a response is returned immediately if an asset with the same public ID was found.

When overwriting assets, if you include versions in your delivery URLs, you will need to update the URLs with the new version number to deliver the new asset. If you don't include versions, you will need to invalidate the old assets on the CDN server cache.

Default: true (when using unsigned upload, the default is false and cannot be changed to true).

Important: Depending on your product environment setup, overwriting an asset may clear the tags, contextual, and structured metadata values for that asset. If you have a Master admin role, you can change this behavior for your product environment in the Media Library Preferences pane, so that these field values are retained when new version assets overwrite older ones (unless you specify different values for the tags, context, or metadata parameters as part of your upload).
tags String A comma-separated list of tag names to assign to the slideshow video for later group reference. For example: animal,dog.
notification_url String An HTTP or HTTPS URL to notify your application (a webhook) when the process has completed. If not specified, the response is sent to the global Notification URL (if defined) in the Upload page of your Console Settings.

Example

Generating a slideshow using manifest_json, comprised of two images, setting the public ID to test_slideshow:

Sample response

The following is a sample response based on the example 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.

✔️ Feedback sent!

Rate this page: