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.

Usage example

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

Parameters

• interpolate

  boolean | Record<string, boolean>

  Controls whether Assembly Variables are interpolated for individual instruction fields.

  By default, most Robot instruction fields interpolate Assembly Variables. Set this to false to treat every instruction field as literal text, or set an individual field path to false to treat only that field as literal text. For Robot-specific fields that are literal by default, set this to true or set that field path to true to opt back into interpolation.

  Use field names such as path, or dotted paths such as ffmpeg.vf for nested objects.

• output_meta

  Record<string, boolean> | boolean | Array<string>

  Allows you to specify a set of metadata that is more expensive on CPU power to calculate, and thus is disabled by default to keep your Assemblies processing fast.

  For images, you can add "has_transparency": true in this object to extract if the image contains transparent parts and "dominant_colors": true to extract an array of hexadecimal color codes from the image.

  For images, you can also add "blurhash": true to extract a BlurHash⁠ string — a compact representation of a placeholder for the image, useful for showing a blurred preview while the full image loads.

  For images, "thumbhash": true instead extracts a base64-encoded ThumbHash⁠ into meta.thumbhash, together with meta.has_alpha (whether an alpha channel exists, even when fully opaque). It describes EXIF-oriented pixels and uses the first frame of animated images. Extraction is best-effort: images above 40 megapixels, unsupported formats, or a failed/bounded decode produce no placeholder. Successful extraction adds a metadata charge equivalent to 20% of that file's bytes. No ThumbHash surcharge applies when disabled or when no hash is produced.

  Set this option on the Step producing the image, such as /upload/handle for uploaded originals or /image/resize for processed outputs. Setting it only on /transloadit/store does not request extraction: storage preserves the producer's metadata. Transloadit Storage persists a generated hash with its immutable version and returns it in stored results and native asset reads. Direct S3 uploads do not generate placeholders. A placeholder contains image information, so protect it with the same access controls as the full image.

  For videos, you can add the "colorspace": true parameter to extract the colorspace of the output video.

  For videos, you can also add "interlaced": true to detect whether the video is interlaced. This combines the cheap ffprobe field_order flag with a bounded idet sampling pass over the first frames of the source, exposing interlaced, field_order, and a diagnostic interlace_detection object under file.meta. This is computationally expensive and billed accordingly.

  For audio, you can add "mean_volume": true to get a single value representing the mean average volume of the audio file.

  You can also set this to false to skip metadata extraction and speed up transcoding.

• user_meta

  Record<string, any>(default: {})

  Adds custom JSON metadata to each emitted file without changing its contents. Nested objects and arrays are supported.

  Inheritance depends on the Robot. Values merge with existing user_meta on the output file; the current Step replaces matching top-level keys. Assign required keys explicitly when a Robot creates fresh outputs.

  In processing Steps, ${file.*} refers to the first input and ${result.*} to the emitted file. Values are evaluated per output after the Robot runs, before subsequent metadata extraction and temporary storage. On :original, values are evaluated per upload before metadata extraction.

  Downstream Steps read ${file.user_meta.key}. See Custom metadata for a complete example and inheritance rules.

• result

  boolean(default: false)

  Whether the results of this Step should be present in the Assembly Status JSON

• queue

  batch

  Setting the queue to 'batch', manually downgrades the priority of jobs for this step to avoid consuming Priority job slots for jobs that don't need zero queue waiting times

• force_accept

  boolean(default: false)

  Force a Robot to accept a file type it would have ignored.

  By default, Robots ignore files they are not familiar with. 🤖/video/encode, for example, will happily ignore input images.

  With the force_accept parameter set to true, you can force Robots to accept all files thrown at them. This will typically lead to errors and should only be used for debugging or combatting edge cases.

• ignore_errors

  boolean | Array<meta | execute>(default: [])

  Ignore errors during specific phases of processing.

  Setting this to ["meta"] will cause the Robot to ignore errors during metadata extraction.

  Setting this to ["execute"] will cause the Robot to ignore errors during the main execution phase.

  Setting this to true is equivalent to ["meta", "execute"] and will ignore errors in both phases.

• use

  string | Array<string> | Array<object> | object

  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"
      ]
    }
    

  • You can also tag input Steps with as to pass semantic intent to robots:

    {
      "use": [
        {
          "name": ":original",
          "as": "image"
        },
        {
          "name": ":original",
          "as": "mask"
        }
      ]
    }
    

  Tip

  That's likely all you need to know about use, but you can view Advanced use cases.

• format

  avif | gif | jpeg | jpg | png | webp(default: "png")

  The output format for the generated thumbnail image. If a short video clip is generated using the clip strategy, its format is defined by clip_format.

• quality

  string | number

  Compression quality for still previews, from 1 to 100. When specified, the final image resize encodes directly into the requested format at this quality and strips embedded metadata. Omit it to retain the default encoding behavior. Animated clips use their own encoding settings. If optimize is enabled, optimization runs after this encoding.

• width

  number(default: 300)

  Width of the thumbnail, in pixels.

• height

  number(default: 200)

  Height of the thumbnail, in pixels.

• resize_strategy

  crop | fit | fillcrop | min_fit | pad | stretch(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.

• zoom

  boolean(default: true)

  If set to false, smaller images will not be stretched to the desired width and height. This is useful if you want to retain the original image dimensions and only limit the output to a maximum size. For details about the impact of zooming for your preferred resize strategy, see the list of available resize strategies.

  Note that this parameter only affects strategies that produce a still image. Animated clips generated by the clip strategy are not affected.

• strategy

  object

  Definition of the thumbnail generation process per file category. Each key selects a file category and its value is an ordered array of strategies:

  File category	Available strategies
  audio	artwork, waveform, icon
  video	artwork, frame, clip, icon
  image	image, embedded-preview, icon
  document	page, icon
  archive	icon
  webpage	render, icon
  unknown	icon

  artwork extracts embedded artwork, waveform draws an audio waveform, frame extracts a video frame, and clip creates an animated video preview. For images, image resizes the original and embedded-preview extracts an embedded preview when available. page renders the first document page, render captures a webpage, and icon generates a file-type icon.

  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:

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

• artwork_outer_color

  string

  The color used in the outer parts of the artwork's gradient.

• artwork_center_color

  string

  The color used in the center of the artwork's gradient.

• 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

  string | number(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

  string | number(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_style

  square | with-text(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:
  
  
  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

  extension | none(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 leaves the text box empty while reserving space for a custom text overlay, for example using HTML in your application.

• optimize

  boolean(default: true)

  Specifies whether the generated preview image should be optimized to reduce its file size while maintaining visual quality. If enabled, the image will be optimized using 🤖/image/optimize.

• optimize_priority

  compression-ratio | conversion-speed(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.

• clip_format

  apng | avif | gif | webp(default: "webp")

  The animated image format for the generated video clip. Only used if the clip strategy for video files is applied.

  Please consult the MDN Web Docs⁠ for detailed information about the image formats and their characteristics. GIF enjoys broad support in software, but only supports a limited color palette. APNG supports a variety of color depths, but its lossless compression produces large images for videos. AVIF offers efficient compression, but animation support varies between browsers. WebP offers a balance between small file sizes and visual quality and is the default clip format.

• clip_offset

  string | number(default: 1)

  The start position in seconds of where the clip is cut. Only used if the clip strategy for video files is applied. For large videos, only portions of the file may be imported to improve speed. An offset outside the available media data can prevent clip generation.

• clip_duration

  string | number(default: 5)

  The duration in seconds of the generated video clip. Only used if the clip strategy for video files is applied. Be aware that a longer clip duration also results in a larger file size, which might be undesirable for previews.

• clip_framerate

  string | number(default: 5)

  The framerate of the generated video clip. Only used if the clip strategy for video files is applied. Be aware that a higher framerate appears smoother but also results in a larger file size, which might be undesirable for previews.

• clip_loop

  boolean(default: true)

  Specifies whether the generated animated image should loop forever (true) or stop after playing the animation once (false). Only used if the clip strategy for video files is applied.

Related blog posts