Flag of Ukraine
Our /file/preview Robot
Beta

Generate a preview thumbnail

πŸ€–/file/preview generates a thumbnail for any uploaded file to preview its content, similar to the thumbnails in desktop file managers.

This feature is still in an experimental stage. Its exact behavior, its parameters, and its pricing might change while we continue to work on it. If you encounter any bugs or odd behavior, please contact us.

This Robot's purpose is to generate a meaningful preview image for any file, in such a way that the resulting thumbnail highlights the file's content. The goal is not to losslessly present the original media in a smaller way. Instead, it is to maximize the chance of a person recognizing the media at a glance, while being visually pleasing and consistent with other previews. The generation process depends on the file type. For example, the Robot can extract artwork from media files, frames from videos, generate a waveform for audio files, and preview the content of documents and images. The details of all available strategies are provided in the next section.

If no file-specific thumbnail can be generated because the file type is not supported, a generic icon containing the file extension will be generated.

The default parameters ensure that the Robot always generates a preview image with the predefined dimensions and formats, to allow an easy integration into your application's UI. In addition, the generated preview images are optimized by default to reduce their file size while keeping their quality.

Strategies

The Robot groups each file into one category based on its type: audio, video, image, document (PDFs, Word documents, PowerPoint presentations etc.), archive (ZIP, RAR etc.), webpage (HTML), or unknown (for all unsupported files types).

For each category, multiple thumbnail generation strategies are available. Using the strategy parameter, you can define a list of strategies per file category. The Robot will go through the list, attempting each strategy until one succeeds. This approach allows you to customize the preview generation process to your application's needs.

The available strategies are:

For all categories (including unknown and archive), the icon strategy is available as well. It generates a generic thumbnail featuring a category-specific icon and optionally the file's extension, using the πŸ€–/image/resize Robot. This way, the file type is visualized, but its exact content is not. The icon strategy is especially useful as a fallback method when other strategies are not available.

Pricing

The /file/preview Robot internally uses other Robots for generating the desired thumbnail, as listed in the description of the available strategies in the section above. To account for the varying computational effort between different strategies, the /file/preview Robot does not have a fixed pricing, but is billed according to the Robot that is used under the hood. For example, if an Assembly generated a thumbnail using /file/preview's frame strategy for videos, it will be billed as a πŸ€–/video/thumbs Step. It will then also show up as πŸ€–/video/thumbs usage on your invoice.

For the artwork, waveform, page, and render strategies, an additional charge is billed for the image resizing, because the underlying Robots are not capable of performing a resize operation. Thus, an additional πŸ€–/image/resize Step is necessary, which will show up as πŸ€–/image/resize usage on your invoice.

As an example, if a 1 MB audio file generates a 0.5 MB waveform with the waveform strategy and this waveform is then resized into a 0.1 MB thumbnail, 1.5 MB (= 1 MB + 0.5 MB) will be billed according to πŸ€–/audio/waveform's rules and 0.6 MB (= 0.6 MB + 0.1 MB) will be billed according to πŸ€–/image/resize's rules.

If the optimize parameter is enabled, images will be optimized to reduce their file size and a corresponding charge for the use of πŸ€–/image/optimize will be billed.

Usage example

Generate a preview thumbnail for any uploaded file:

{
  "steps": {
    "previewed": {
      "robot": "/file/preview",
      "use": ":original",
      "height": 400,
      "width": 300,
      "format": "png"
    }
  }
}

Parameters

  • use

    String / Array of Strings / Object required

    Specifies which Step(s) to use as input.

    • You can pick any names for Steps except ":original" (reserved for user uploads handled by Transloadit)

    • You can provide several Steps as input with arrays:

      "use": [
        ":original",
        "encoded",
        "resized"
      ]
      

    πŸ’‘ That’s likely all you need to know about use, but you can view Advanced use cases.

  • format

    String β‹… default: "png"

    The output format for the generated thumbnail image. Possible formats are "jpg", "png", and "gif".

  • width

    Integer(1-5000) β‹… default: 300

    Width of the thumbnail, in pixels.

  • height

    Integer(1-5000) β‹… default: 200

    Height of the thumbnail, in pixels.

  • resize_strategy

    String β‹… default: "pad"

    To achieve the desired dimensions of the preview thumbnail, the Robot might have to resize the generated image. This happens, for example, when the dimensions of a frame extracted from a video do not match the chosen width and height parameters.

    See the list of available resize strategies for more details.

  • background

    String β‹… default: "#ffffffff"

    The hexadecimal code of the color used to fill the background (only used for the pad resize strategy). The format is #rrggbb[aa] (red, green, blue, alpha). Use #00000000 for a transparent padding.

  • strategy

    Object β‹… default: auto [?]

    Definition of the thumbnail generation process per file category. The parameter must be an object whose keys can be one of the file categories: audio, video, image, document, archive, webpage, and unknown. The corresponding value is an array of strategies for the specific file category. See the above section for a list of all available strategies.

    For each file, the Robot will attempt to use the first strategy to generate the thumbnail. If this process fails (e.g., because no artwork is available in a video file), the next strategy is attempted. This is repeated until either a thumbnail is generated or the list is exhausted. Selecting the icon strategy as the last entry provides a fallback mechanism to ensure that an appropriate strategy is always available.

    The parameter defaults to the following definition:

    {
      "audio": ["artwork", "waveform", "icon"],
      "video": ["artwork", "frame", "icon"],
      "document": ["page", "icon"],
      "image": ["image", "icon"],
      "webpage": ["render", "icon"],
      "archive": ["icon"],
      "unknown": ["icon"]
    }
    

Waveform parameters

  • waveform_center_color

    String β‹… default: "#000000ff"

    The color used in the center of the waveform's gradient. The format is #rrggbb[aa] (red, green, blue, alpha). Only used if the waveform strategy for audio files is applied.

  • waveform_outer_color

    String β‹… default: "#000000ff"

    The color used in the outer parts of the waveform's gradient. The format is #rrggbb[aa] (red, green, blue, alpha). Only used if the waveform strategy for audio files is applied.

  • waveform_height

    Integer(1-5000) β‹… default: 100

    Height of the waveform, in pixels. Only used if the waveform strategy for audio files is applied. It can be utilized to ensure that the waveform only takes up a section of the preview thumbnail.

  • waveform_width

    Integer(1-5000) β‹… default: 300

    Width of the waveform, in pixels. Only used if the waveform strategy for audio files is applied. It can be utilized to ensure that the waveform only takes up a section of the preview thumbnail.

Icon parameters

  • icon_style

    String β‹… default: "with-text"

    The style of the icon generated if the icon strategy is applied. The default style, with-text, includes an icon showing the file type and a text box below it, whose content can be controlled by the icon_text_content parameter and defaults to the file extension (e.g. MP4, JPEG). The square style only includes a square variant of the icon showing the file type. Below are exemplary previews generated for a text file utilizing the different styles:



    with-text style:
    Image with text style

    square style:
    Image with square style

  • icon_text_color

    String β‹… default: "#a2a2a2"

    The color of the text used in the icon. The format is #rrggbb[aa]. Only used if the icon strategy is applied.

  • icon_text_font

    String β‹… default: "Roboto"

    The font family of the text used in the icon. Only used if the icon strategy is applied. Here is a list of all supported fonts.

  • icon_text_content

    String β‹… default: "extension"

    The content of the text box in generated icons. Only used if the icon_style parameter is set to with-text. The default value, extension, adds the file extension (e.g. MP4, JPEG) to the icon. The value none can be used to render an empty text box, which is useful if no text should not be included in the raster image, but some place should be reserved in the image for later overlaying custom text over the image using HTML etc.

Image optimization parameters

  • optimize

    Boolean β‹… default: true

    Specifies whether the generated preview image should be optimized to reduce the image's file size while keeping their quaility. If enabled, the images will be optimized using πŸ€–/image/optimize.

  • optimize_priority

    String β‹… default: "conversion-speed"

    Specifies whether conversion speed or compression ratio is prioritized when optimizing images. Only used if optimize is enabled. Please see the πŸ€–/image/optimize documentation for more details.

  • optimize_progressive

    Boolean β‹… default: false

    Specifies whether images should be interlaced, which makes the result image load progressively in browsers. Only used if optimize is enabled. Please see the πŸ€–/image/optimize documentation for more details.