transloadit 4.7.4 → 4.8.0

package/README.md

@@ -33,15 +33,18 @@ This is a **Node.js** SDK to make it easy to talk to the
 Inside your project, type:
 
 ```bash
-yarn add transloadit
+yarn add @transloadit/node
 ```
 
 or
 
 ```bash
-npm install --save transloadit
+npm install --save @transloadit/node
 ```
 
+The legacy npm package name `transloadit` is kept as an alias for backward compatibility, but
+`@transloadit/node` is the canonical package name.
+
 ## Command Line Interface (CLI)
 
 This package includes a full-featured CLI for interacting with Transloadit from your terminal.
@@ -54,9 +57,12 @@ export TRANSLOADIT_KEY="YOUR_TRANSLOADIT_KEY"
 export TRANSLOADIT_SECRET="YOUR_TRANSLOADIT_SECRET"
 
 # See all available commands
-npx transloadit --help
+npx -y @transloadit/node --help
 ```
 
+The CLI binary is still called `transloadit`, so command examples below may use
+`npx transloadit ...`.
+
 ### Minting Bearer Tokens (Hosted MCP)
 
 If you want to connect an agent to the Transloadit-hosted MCP endpoint, mint a short-lived bearer
@@ -78,7 +84,905 @@ npx -y transloadit auth token --aud mcp --scope assemblies:write,templates:read
 
 ### Processing Media
 
-Create Assemblies to process files using Assembly Instructions (steps) or Templates:
+For common one-off tasks, prefer the intent-first commands:
+
+The full generated intent reference also lives in [`docs/intent-commands.md`](./docs/intent-commands.md).
+
+<!-- GENERATED_INTENT_DOCS:START -->
+
+#### At a glance
+
+Intent commands are the fastest path to common one-off tasks from the CLI.
+Use `--print-urls` when you want temporary result URLs without downloading locally.
+All intent commands also support the global CLI flags `--json`, `--log-level`, `--endpoint`, and `--help`.
+
+| Command | What it does | Input | Output |
+| --- | --- | --- | --- |
+| `image generate` | Generate images from text prompts | file, dir, URL, base64 | file |
+| `preview generate` | Generate a preview thumbnail | file, dir, URL, base64 | file |
+| `image remove-background` | Remove the background from images | file, dir, URL, base64 | file |
+| `image optimize` | Optimize images without quality loss | file, dir, URL, base64 | file |
+| `image resize` | Convert, resize, or watermark images | file, dir, URL, base64 | file |
+| `document convert` | Convert documents into different formats | file, dir, URL, base64 | file |
+| `document optimize` | Reduce PDF file size | file, dir, URL, base64 | file |
+| `document auto-rotate` | Auto-rotate documents to the correct orientation | file, dir, URL, base64 | file |
+| `document thumbs` | Extract thumbnail images from documents | file, dir, URL, base64 | directory |
+| `audio waveform` | Generate waveform images from audio | file, dir, URL, base64 | file |
+| `text speak` | Speak text | file, dir, URL, base64 | file |
+| `video thumbs` | Extract thumbnails from videos | file, dir, URL, base64 | directory |
+| `video encode-hls` | Run builtin/encode-hls-video@latest | file, dir, URL, base64 | directory |
+| `image describe` | Describe images as labels or publishable text fields | file, dir, URL, base64 | file |
+| `markdown pdf` | Render Markdown files as PDFs | file, dir, URL, base64 | file |
+| `markdown docx` | Render Markdown files as DOCX documents | file, dir, URL, base64 | file |
+| `file compress` | Compress files | file, dir, URL, base64 | file |
+| `file decompress` | Decompress archives | file, dir, URL, base64 | directory |
+
+> At least one of `--out` or `--print-urls` is required on every intent command.
+
+#### Shared flags
+
+These flags are available across many intent commands, so the per-command sections below focus on differences.
+
+**Shared file input & output flags**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--input, -i` | `path \| dir \| url \| -` | varies | `input.file` | Provide an input path, directory, URL, or - for stdin |
+| `--input-base64` | `base64 \| data URL` | no | `data:text/plain;base64,SGVsbG8=` | Provide base64-encoded input content directly |
+| `--out, -o` | `path` | yes* | `output.file` | Write the result to this path or directory |
+| `--print-urls` | `boolean` | no | `false` | Print temporary result URLs after completion |
+
+**Shared no-input output flags**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--out, -o` | `path` | yes* | `output.file` | Write the result to this path |
+| `--print-urls` | `boolean` | no | `false` | Print temporary result URLs after completion |
+
+**Shared processing flags**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--recursive, -r` | `boolean` | no | `false` | Enumerate input directories recursively |
+| `--delete-after-processing, -d` | `boolean` | no | `false` | Delete input files after they are processed |
+| `--reprocess-stale` | `boolean` | no | `false` | Process inputs even if output is newer |
+
+**Shared watch flags**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--watch, -w` | `boolean` | no | `false` | Watch inputs for changes |
+| `--concurrency, -c` | `number` | no | `5` | Maximum number of concurrent assemblies (default: 5) |
+
+**Shared bundling flags**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--single-assembly` | `boolean` | no | `false` | Pass all input files to a single assembly instead of one assembly per file |
+
+#### `image generate`
+
+Generate images from text prompts
+
+Runs `/image/generate`. Without inputs, this is text-to-image. With one or more `--input` files, the inputs are bundled into a single assembly so the prompt can refer to them by filename.
+
+**Usage**
+
+```bash
+npx transloadit image generate [--input <path|dir|url|->] [options]
+```
+
+**Quick facts**
+
+- Input: file, dir, URL, base64
+- Output: file
+- Execution: single assembly
+- Backend: semantic alias `image-generate`
+
+**Shared flags**
+
+- Uses the shared file input and output flags listed above.
+- Also supports the shared base processing flags listed above.
+
+**Command options**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--prompt` | `string` | yes | `"A red bicycle in a studio"` | The prompt describing the desired image content. |
+| `--model` | `string` | no | `google/nano-banana-2` | The AI model to use for image generation. Defaults to google/nano-banana-2. |
+| `--format` | `string` | no | `jpg` | Format of the generated image. |
+| `--seed` | `number` | no | — | Seed for the random number generator. |
+| `--aspect-ratio` | `string` | no | — | Aspect ratio of the generated image. |
+| `--height` | `number` | no | — | Height of the generated image. |
+| `--width` | `number` | no | — | Width of the generated image. |
+| `--style` | `string` | no | — | Style of the generated image. |
+| `--num-outputs` | `number` | no | — | Number of image variants to generate. |
+
+**Examples**
+
+```bash
+# Generate an image from text
+transloadit image generate --prompt "A red bicycle in a studio" --out output.png
+# Guide generation with one input image
+transloadit image generate --input subject.jpg --prompt "Place subject.jpg on a magazine cover" --out output.png
+# Guide generation with multiple input images
+transloadit image generate --input person1.jpg --input person2.jpg --input background.jpg --prompt "Place person1.jpg feeding person2.jpg in front of background.jpg" --out output.png
+```
+
+#### `preview generate`
+
+Generate a preview thumbnail
+
+Runs `/file/preview` on each input file and writes the result to `--out`.
+
+**Usage**
+
+```bash
+npx transloadit preview generate --input <path|dir|url|-> [options]
+```
+
+**Quick facts**
+
+- Input: file, dir, URL, base64
+- Output: file
+- Execution: per-file; supports `--single-assembly` and `--watch`
+- Backend: `/file/preview`
+
+**Shared flags**
+
+- Uses the shared file input and output flags listed above.
+- Also supports the shared base processing flags, watch flags, bundling flags listed above.
+
+**Command options**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--format` | `string` | no | `jpg` | 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. |
+| `--width` | `number` | no | `1` | Width of the thumbnail, in pixels. |
+| `--height` | `number` | no | `1` | Height of the thumbnail, in pixels. |
+| `--resize-strategy` | `string` | no | `crop` | To achieve the desired dimensions of the preview thumbnail, the Robot might have to resize the generated image. |
+| `--background` | `string` | no | `value` | The hexadecimal code of the color used to fill the background (only used for the pad resize strategy). |
+| `--zoom` | `boolean` | no | `true` | If set to false, smaller images will not be stretched to the desired width and height. |
+| `--strategy` | `json` | no | `value` | Definition of the thumbnail generation process per file category. |
+| `--artwork-outer-color` | `string` | no | `value` | The color used in the outer parts of the artwork's gradient. |
+| `--artwork-center-color` | `string` | no | `value` | The color used in the center of the artwork's gradient. |
+| `--waveform-center-color` | `string` | no | `value` | 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` | no | `value` | 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` | `number` | no | `1` | 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… |
+| `--waveform-width` | `number` | no | `1` | 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… |
+| `--icon-style` | `string` | no | `square` | The style of the icon generated if the icon strategy is applied. |
+| `--icon-text-color` | `string` | no | `value` | 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` | no | `value` | 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` | no | `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)… |
+| `--optimize` | `boolean` | no | `true` | Specifies whether the generated preview image should be optimized to reduce the image's file size while keeping their quaility. |
+| `--optimize-priority` | `string` | no | `compression-ratio` | Specifies whether conversion speed or compression ratio is prioritized when optimizing images. |
+| `--optimize-progressive` | `boolean` | no | `true` | Specifies whether images should be interlaced, which makes the result image load progressively in browsers. |
+| `--clip-format` | `string` | no | `apng` | 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… |
+| `--clip-offset` | `number` | no | `1` | The start position in seconds of where the clip is cut. Only used if the clip strategy for video files is applied. Be aware that for larger video only the first few MBs of the… |
+| `--clip-duration` | `number` | no | `1` | 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… |
+| `--clip-framerate` | `number` | no | `1` | 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… |
+| `--clip-loop` | `boolean` | no | `true` | Specifies whether the generated animated image should loop forever (true) or stop after playing the animation once (false). |
+
+**Examples**
+
+```bash
+transloadit preview generate --input input.file --out output.file
+```
+
+#### `image remove-background`
+
+Remove the background from images
+
+Runs `/image/bgremove` on each input file and writes the result to `--out`.
+
+**Usage**
+
+```bash
+npx transloadit image remove-background --input <path|dir|url|-> [options]
+```
+
+**Quick facts**
+
+- Input: file, dir, URL, base64
+- Output: file
+- Execution: per-file; supports `--single-assembly` and `--watch`
+- Backend: `/image/bgremove`
+
+**Shared flags**
+
+- Uses the shared file input and output flags listed above.
+- Also supports the shared base processing flags, watch flags, bundling flags listed above.
+
+**Command options**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--select` | `string` | no | `foreground` | Region to select and keep in the image. The other region is removed. |
+| `--format` | `string` | no | `png` | Format of the generated image. Defaults to PNG when not provided. |
+| `--provider` | `string` | no | `aws` | Provider to use for removing the background. |
+| `--model` | `string` | no | `value` | Provider-specific model to use for removing the background. Mostly intended for testing and evaluation. |
+
+**Examples**
+
+```bash
+transloadit image remove-background --input input.png --out output.png
+```
+
+#### `image optimize`
+
+Optimize images without quality loss
+
+Runs `/image/optimize` on each input file and writes the result to `--out`.
+
+**Usage**
+
+```bash
+npx transloadit image optimize --input <path|dir|url|-> [options]
+```
+
+**Quick facts**
+
+- Input: file, dir, URL, base64
+- Output: file
+- Execution: per-file; supports `--single-assembly` and `--watch`
+- Backend: `/image/optimize`
+
+**Shared flags**
+
+- Uses the shared file input and output flags listed above.
+- Also supports the shared base processing flags, watch flags, bundling flags listed above.
+
+**Command options**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--priority` | `string` | no | `compression-ratio` | Provides different algorithms for better or worse compression for your images, but that run slower or faster. |
+| `--progressive` | `boolean` | no | `true` | Interlaces the image if set to true, which makes the result image load progressively in browsers. |
+| `--preserve-meta-data` | `boolean` | no | `true` | Specifies if the image's metadata should be preserved during the optimization, or not. |
+| `--fix-breaking-images` | `boolean` | no | `true` | If set to true this parameter tries to fix images that would otherwise make the underlying tool error out and thereby break your Assemblies . |
+| `--lossy` | `boolean` | no | `true` | When set to false (the default), only lossless PNG optimizers are used, disabling pngquant to preserve color accuracy. |
+
+**Examples**
+
+```bash
+transloadit image optimize --input input.png --out output.png
+```
+
+#### `image resize`
+
+Convert, resize, or watermark images
+
+Runs `/image/resize` on each input file and writes the result to `--out`.
+
+**Usage**
+
+```bash
+npx transloadit image resize --input <path|dir|url|-> [options]
+```
+
+**Quick facts**
+
+- Input: file, dir, URL, base64
+- Output: file
+- Execution: per-file; supports `--single-assembly` and `--watch`
+- Backend: `/image/resize`
+
+**Shared flags**
+
+- Uses the shared file input and output flags listed above.
+- Also supports the shared base processing flags, watch flags, bundling flags listed above.
+
+**Command options**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--format` | `string` | no | `value` | The output format for the modified image. Some of the most important available formats are "jpg", "png", "gif", and "tiff". For a complete lists of all formats that we can write… |
+| `--width` | `number` | no | `1` | Width of the result in pixels. If not specified, will default to the width of the original. |
+| `--height` | `number` | no | `1` | Height of the new image, in pixels. If not specified, will default to the height of the input image. |
+| `--resize-strategy` | `string` | no | `crop` | See the list of available resize strategies. |
+| `--zoom` | `boolean` | no | `true` | If this is set to false, smaller images will not be stretched to the desired width and height. |
+| `--crop` | `auto` | no | `value` | Specify an object containing coordinates for the top left and bottom right corners of the rectangle to be cropped from the original image(s). |
+| `--gravity` | `string` | no | `bottom` | The direction from which the image is to be cropped, when "resize_strategy" is set to "crop", but no crop coordinates are defined. |
+| `--strip` | `boolean` | no | `true` | Strips all metadata from the image. This is useful to keep thumbnails as small as possible. |
+| `--alpha` | `string` | no | `Activate` | Gives control of the alpha/matte channel of an image. |
+| `--preclip-alpha` | `string` | no | `Activate` | Gives control of the alpha/matte channel of an image before applying the clipping path via clip: true. |
+| `--flatten` | `boolean` | no | `true` | Flattens all layers onto the specified background to achieve better results from transparent formats to non-transparent formats, as explained in the ImageMagick documentation. |
+| `--correct-gamma` | `boolean` | no | `true` | Prevents gamma errors common in many image scaling algorithms. |
+| `--quality` | `number` | no | `1` | Controls the image compression for JPG and PNG images. Please also take a look at 🤖/image/optimize. |
+| `--adaptive-filtering` | `boolean` | no | `true` | Controls the image compression for PNG images. Setting to true results in smaller file size, while increasing processing time. It is encouraged to keep this option disabled. |
+| `--background` | `string` | no | `transparent` | Either the hexadecimal code or name of the color used to fill the background (used for the pad resize strategy). |
+| `--frame` | `number` | no | `1` | Use this parameter when dealing with animated GIF files to specify which frame of the GIF is used for the operation. |
+| `--colorspace` | `string` | no | `CMY` | Sets the image colorspace. For details about the available values, see the ImageMagick documentation. Please note that if you were using "RGB", we recommend using "sRGB" instead… |
+| `--type` | `string` | no | `Bilevel` | Sets the image color type. For details about the available values, see the ImageMagick documentation. If you're using colorspace, ImageMagick might try to find the most efficient… |
+| `--sepia` | `number` | no | `1` | Applies a sepia tone effect in percent. |
+| `--rotation` | `auto` | no | `auto` | Determines whether the image should be rotated. Use any number to specify the rotation angle in degrees (e.g., 90, 180, 270, 360, or precise values like 2.9). Use the value true… |
+| `--compress` | `string` | no | `BZip` | Specifies pixel compression for when the image is written. Compression is disabled by default. Please also take a look at 🤖/image/optimize. |
+| `--blur` | `string` | no | `value` | Specifies gaussian blur, using a value with the form {radius}x{sigma}. |
+| `--blur-regions` | `json` | no | `value` | Specifies an array of ellipse objects that should be blurred on the image. |
+| `--brightness` | `number` | no | `1` | Increases or decreases the brightness of the image by using a multiplier. For example 1.5 would increase the brightness by 50%, and 0.75 would decrease the brightness by 25%. |
+| `--saturation` | `number` | no | `1` | Increases or decreases the saturation of the image by using a multiplier. For example 1.5 would increase the saturation by 50%, and 0.75 would decrease the saturation by 25%. |
+| `--hue` | `number` | no | `1` | Changes the hue by rotating the color of the image. The value 100 would produce no change whereas 0 and 200 will negate the colors in the image. |
+| `--contrast` | `number` | no | `1` | Adjusts the contrast of the image. A value of 1 produces no change. Values below 1 decrease contrast (with 0 being minimum contrast), and values above 1 increase contrast (with 2… |
+| `--watermark-url` | `string` | no | `value` | A URL indicating a PNG image to be overlaid above this image. |
+| `--watermark-position` | `string[]` | no | `bottom` | The position at which the watermark is placed. The available options are "center", "top", "bottom", "left", and "right". You can also combine options, such as "bottom-right". An… |
+| `--watermark-x-offset` | `number` | no | `1` | The x-offset in number of pixels at which the watermark will be placed in relation to the position it has due to watermark_position. |
+| `--watermark-y-offset` | `number` | no | `1` | The y-offset in number of pixels at which the watermark will be placed in relation to the position it has due to watermark_position. |
+| `--watermark-size` | `string` | no | `value` | The size of the watermark, as a percentage. For example, a value of "50%" means that size of the watermark will be 50% of the size of image on which it is placed. The exact… |
+| `--watermark-resize-strategy` | `string` | no | `area` | Available values are "fit", "min_fit", "stretch" and "area". |
+| `--watermark-opacity` | `number` | no | `1` | The opacity of the watermark, where 0.0 is fully transparent and 1.0 is fully opaque. |
+| `--watermark-repeat-x` | `boolean` | no | `true` | When set to true, the watermark will be repeated horizontally across the entire width of the image. |
+| `--watermark-repeat-y` | `boolean` | no | `true` | When set to true, the watermark will be repeated vertically across the entire height of the image. |
+| `--text` | `json` | no | `value` | Text overlays to be applied to the image. Can be either a single text object or an array of text objects. Each text object contains text rules. The following text parameters are… |
+| `--progressive` | `boolean` | no | `true` | Interlaces the image if set to true, which makes the image load progressively in browsers. |
+| `--transparent` | `string` | no | `transparent` | Make this color transparent within the image. Example: "255,255,255". |
+| `--trim-whitespace` | `boolean` | no | `true` | This determines if additional whitespace around the image should first be trimmed away. |
+| `--clip` | `auto` | no | `value` | Apply the clipping path to other operations in the resize job, if one is present. |
+| `--negate` | `boolean` | no | `true` | Replace each pixel with its complementary color, effectively negating the image. Especially useful when testing clipping. |
+| `--clut` | `boolean` | no | `true` | Applies a Color Look-Up Table (CLUT) image to remap the colors of the input image using ImageMagick's -clut operator. |
+| `--density` | `string` | no | `value` | While in-memory quality and file format depth specifies the color resolution, the density of an image is the spatial (space) resolution of the image. |
+| `--monochrome` | `boolean` | no | `true` | Transform the image to black and white. This is a shortcut for setting the colorspace to Gray and type to Bilevel. |
+| `--shave` | `auto` | no | `value` | Shave pixels from the image edges. The value should be in the format width or widthxheight to specify the number of pixels to remove from each side. |
+
+**Examples**
+
+```bash
+transloadit image resize --input input.png --out output.png
+```
+
+#### `document convert`
+
+Convert documents into different formats
+
+Runs `/document/convert` on each input file and writes the result to `--out`.
+
+**Usage**
+
+```bash
+npx transloadit document convert --input <path|dir|url|-> [options]
+```
+
+**Quick facts**
+
+- Input: file, dir, URL, base64
+- Output: file
+- Execution: per-file; supports `--single-assembly` and `--watch`
+- Backend: `/document/convert`
+
+**Shared flags**
+
+- Uses the shared file input and output flags listed above.
+- Also supports the shared base processing flags, watch flags, bundling flags listed above.
+
+**Command options**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--format` | `string` | yes | `pdf` | The desired format for document conversion. |
+| `--markdown-format` | `string` | no | `commonmark` | Markdown can be represented in several variants, so when using this Robot to transform Markdown into HTML please specify which revision is being used. |
+| `--markdown-theme` | `string` | no | `bare` | This parameter overhauls your Markdown files styling based on several canned presets. |
+| `--pdf-margin` | `string` | no | `value` | PDF Paper margins, separated by , and with units. We support the following unit values: px, in, cm, mm. Currently this parameter is only supported when converting from html. |
+| `--pdf-print-background` | `boolean` | no | `true` | Print PDF background graphics. Currently this parameter is only supported when converting from html. |
+| `--pdf-format` | `string` | no | `A0` | PDF paper format. Currently this parameter is only supported when converting from html. |
+| `--pdf-display-header-footer` | `boolean` | no | `true` | Display PDF header and footer. Currently this parameter is only supported when converting from html. |
+| `--pdf-header-template` | `string` | no | `value` | HTML template for the PDF print header. Should be valid HTML markup with following classes used to inject printing values into them: - date formatted print date - title document… |
+| `--pdf-footer-template` | `string` | no | `value` | HTML template for the PDF print footer. Should use the same format as the pdf_header_template. Currently this parameter is only supported when converting from html, and requires… |
+
+**Examples**
+
+```bash
+transloadit document convert --input input.pdf --format pdf --out output.pdf
+```
+
+#### `document optimize`
+
+Reduce PDF file size
+
+Runs `/document/optimize` on each input file and writes the result to `--out`.
+
+**Usage**
+
+```bash
+npx transloadit document optimize --input <path|dir|url|-> [options]
+```
+
+**Quick facts**
+
+- Input: file, dir, URL, base64
+- Output: file
+- Execution: per-file; supports `--single-assembly` and `--watch`
+- Backend: `/document/optimize`
+
+**Shared flags**
+
+- Uses the shared file input and output flags listed above.
+- Also supports the shared base processing flags, watch flags, bundling flags listed above.
+
+**Command options**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--preset` | `string` | no | `screen` | The quality preset to use for optimization. Each preset provides a different balance between file size and quality: - screen - Lowest quality, smallest file size. Best for screen… |
+| `--image-dpi` | `number` | no | `1` | Target DPI (dots per inch) for embedded images. When specified, this overrides the DPI setting from the preset. Higher DPI values result in better image quality but larger file… |
+| `--compress-fonts` | `boolean` | no | `true` | Whether to compress embedded fonts. When enabled, fonts are compressed to reduce file size. |
+| `--subset-fonts` | `boolean` | no | `true` | Whether to subset embedded fonts, keeping only the glyphs that are actually used in the document. |
+| `--remove-metadata` | `boolean` | no | `true` | Whether to strip document metadata (title, author, keywords, etc.) from the PDF. This can provide a small reduction in file size and may be useful for privacy. |
+| `--linearize` | `boolean` | no | `true` | Whether to linearize (optimize for Fast Web View) the output PDF. |
+| `--compatibility` | `string` | no | `1.4` | The PDF version compatibility level. Lower versions have broader compatibility but fewer features. Higher versions support more advanced features but may not open in older PDF… |
+
+**Examples**
+
+```bash
+transloadit document optimize --input input.pdf --out output.pdf
+```
+
+#### `document auto-rotate`
+
+Auto-rotate documents to the correct orientation
+
+Runs `/document/autorotate` on each input file and writes the result to `--out`.
+
+**Usage**
+
+```bash
+npx transloadit document auto-rotate --input <path|dir|url|-> [options]
+```
+
+**Quick facts**
+
+- Input: file, dir, URL, base64
+- Output: file
+- Execution: per-file; supports `--single-assembly` and `--watch`
+- Backend: `/document/autorotate`
+
+**Shared flags**
+
+- Uses the shared file input and output flags listed above.
+- Also supports the shared base processing flags, watch flags, bundling flags listed above.
+
+**Examples**
+
+```bash
+transloadit document auto-rotate --input input.pdf --out output.pdf
+```
+
+#### `document thumbs`
+
+Extract thumbnail images from documents
+
+Runs `/document/thumbs` on each input file and writes the results to `--out`.
+
+**Usage**
+
+```bash
+npx transloadit document thumbs --input <path|dir|url|-> [options]
+```
+
+**Quick facts**
+
+- Input: file, dir, URL, base64
+- Output: directory
+- Execution: per-file; supports `--single-assembly` and `--watch`
+- Backend: `/document/thumbs`
+
+**Shared flags**
+
+- Uses the shared file input and output flags listed above.
+- Also supports the shared base processing flags, watch flags, bundling flags listed above.
+
+**Command options**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--page` | `number` | no | `1` | The PDF page that you want to convert to an image. By default the value is null which means that all pages will be converted into images. |
+| `--page-range` | `string` | no | `value` | A page range to extract, in the format "start-end" (e.g., "1-20"). |
+| `--format` | `string` | no | `jpg` | The format of the extracted image(s). If you specify the value "gif", then an animated gif cycling through all pages is created. Please check out this demo to learn more about… |
+| `--delay` | `number` | no | `1` | If your output format is "gif" then this parameter sets the number of 100th seconds to pass before the next frame is shown in the animation. |
+| `--width` | `number` | no | `1` | Width of the new image, in pixels. If not specified, will default to the width of the input image |
+| `--height` | `number` | no | `1` | Height of the new image, in pixels. If not specified, will default to the height of the input image |
+| `--resize-strategy` | `string` | no | `crop` | One of the available resize strategies. |
+| `--background` | `string` | no | `value` | Either the hexadecimal code or name of the color used to fill the background (only used for the pad resize strategy). |
+| `--alpha` | `string` | no | `Remove` | Change how the alpha channel of the resulting image should work. |
+| `--density` | `string` | no | `value` | While in-memory quality and file format depth specifies the color resolution, the density of an image is the spatial (space) resolution of the image. |
+| `--antialiasing` | `boolean` | no | `true` | Controls whether or not antialiasing is used to remove jagged edges from text or images in a document. |
+| `--colorspace` | `string` | no | `CMY` | Sets the image colorspace. For details about the available values, see the ImageMagick documentation. Please note that if you were using "RGB", we recommend using "sRGB".… |
+| `--trim-whitespace` | `boolean` | no | `true` | This determines if additional whitespace around the PDF should first be trimmed away before it is converted to an image. |
+| `--pdf-use-cropbox` | `boolean` | no | `true` | Some PDF documents lie about their dimensions. For instance they'll say they are landscape, but when opened in decent Desktop readers, it's really in portrait mode. This can… |
+| `--turbo` | `boolean` | no | `true` | Enables high-performance mode for faster document processing. |
+
+**Examples**
+
+```bash
+transloadit document thumbs --input input.pdf --out output/
+```
+
+#### `audio waveform`
+
+Generate waveform images from audio
+
+Runs `/audio/waveform` on each input file and writes the result to `--out`.
+
+**Usage**
+
+```bash
+npx transloadit audio waveform --input <path|dir|url|-> [options]
+```
+
+**Quick facts**
+
+- Input: file, dir, URL, base64
+- Output: file
+- Execution: per-file; supports `--single-assembly` and `--watch`
+- Backend: `/audio/waveform`
+
+**Shared flags**
+
+- Uses the shared file input and output flags listed above.
+- Also supports the shared base processing flags, watch flags, bundling flags listed above.
+
+**Command options**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--ffmpeg` | `json` | no | `value` | A parameter object to be passed to FFmpeg. If a preset is used, the options specified are merged on top of the ones from the preset. For available options, see the FFmpeg… |
+| `--format` | `string` | no | `image` | The format of the result file. Can be "image" or "json". If "image" is supplied, a PNG image will be created, otherwise a JSON file. When style is "spectrogram", only "image" is… |
+| `--width` | `number` | no | `1` | The width of the resulting image if the format "image" was selected. |
+| `--height` | `number` | no | `1` | The height of the resulting image if the format "image" was selected. |
+| `--antialiasing` | `auto` | no | `0` | Either a value of 0 or 1, or true/false, corresponding to if you want to enable antialiasing to achieve smoother edges in the waveform graph or not. |
+| `--background-color` | `string` | no | `value` | The background color of the resulting image in the "rrggbbaa" format (red, green, blue, alpha), if the format "image" was selected. |
+| `--center-color` | `string` | no | `value` | The color used in the center of the gradient. The format is "rrggbbaa" (red, green, blue, alpha). |
+| `--outer-color` | `string` | no | `value` | The color used in the outer parts of the gradient. The format is "rrggbbaa" (red, green, blue, alpha). |
+| `--style` | `string` | no | `v0` | Waveform style version. - "v0": Legacy waveform generation (default). - "v1": Advanced waveform generation with additional parameters. - "spectrogram": Spectrogram visualization… |
+| `--split-channels` | `boolean` | no | `true` | Available when style is "v1". If set to true, outputs multi-channel waveform data or image files, one per channel. |
+| `--zoom` | `number` | no | `1` | Available when style is "v1". Zoom level in samples per pixel. This parameter cannot be used together with pixels_per_second. |
+| `--pixels-per-second` | `number` | no | `1` | Available when style is "v1". Zoom level in pixels per second. This parameter cannot be used together with zoom. |
+| `--bits` | `number` | no | `8` | Available when style is "v1". Bit depth for waveform data. Can be 8 or 16. |
+| `--start` | `number` | no | `1` | Available when style is "v1". Start time in seconds. |
+| `--end` | `number` | no | `1` | Available when style is "v1". End time in seconds (0 means end of audio). |
+| `--colors` | `string` | no | `audition` | Available when style is "v1". Color scheme to use. Can be "audition" or "audacity". |
+| `--border-color` | `string` | no | `value` | Available when style is "v1". Border color in "rrggbbaa" format. |
+| `--waveform-style` | `string` | no | `normal` | Available when style is "v1". Waveform style. Can be "normal" or "bars". |
+| `--bar-width` | `number` | no | `1` | Available when style is "v1". Width of bars in pixels when waveform_style is "bars". |
+| `--bar-gap` | `number` | no | `1` | Available when style is "v1". Gap between bars in pixels when waveform_style is "bars". |
+| `--bar-style` | `string` | no | `square` | Available when style is "v1". Bar style when waveform_style is "bars". |
+| `--axis-label-color` | `string` | no | `value` | Available when style is "v1". Color for axis labels in "rrggbbaa" format. |
+| `--no-axis-labels` | `boolean` | no | `true` | Available when style is "v1". If set to true, renders waveform image without axis labels. |
+| `--with-axis-labels` | `boolean` | no | `true` | Available when style is "v1". If set to true, renders waveform image with axis labels. |
+| `--amplitude-scale` | `number` | no | `1` | Available when style is "v1". Amplitude scale factor. |
+| `--compression` | `number` | no | `1` | Available when style is "v1". PNG compression level: 0 (none) to 9 (best), or -1 (default). Only applicable when format is "image". |
+| `--color-map` | `string` | no | `viridis` | Available when style is "spectrogram". Color scheme for the spectrogram visualization. Defaults to "viridis". |
+| `--frequency-scale` | `string` | no | `linear` | Available when style is "spectrogram". Frequency scale for the spectrogram. "linear" shows frequencies evenly spaced, "logarithmic" emphasizes lower frequencies. Defaults to… |
+| `--frequency-min` | `number` | no | `1` | Available when style is "spectrogram". Minimum frequency in Hz to display. Defaults to 0. |
+| `--frequency-max` | `number` | no | `1` | Available when style is "spectrogram". Maximum frequency in Hz to display. Defaults to half the sample rate (Nyquist frequency). |
+| `--legend` | `boolean` | no | `true` | Available when style is "spectrogram". Whether to include a legend showing the frequency and time scales. Defaults to false. |
+| `--gain` | `number` | no | `1` | Available when style is "spectrogram". Linear gain factor for spectrogram intensity. Defaults to 1. |
+| `--orientation` | `string` | no | `vertical` | Available when style is "spectrogram". Orientation of the spectrogram. "horizontal" shows time on the x-axis (default), "vertical" shows time on the y-axis. |
+
+**Examples**
+
+```bash
+transloadit audio waveform --input input.mp3 --out output.png
+```
+
+#### `text speak`
+
+Speak text
+
+Runs `/text/speak` on each input file and writes the result to `--out`.
+
+**Usage**
+
+```bash
+npx transloadit text speak [--input <path|dir|url|->] [options]
+```
+
+**Quick facts**
+
+- Input: file, dir, URL, base64
+- Output: file
+- Execution: per-file; supports `--single-assembly` and `--watch`
+- Backend: `/text/speak`
+
+**Shared flags**
+
+- Uses the shared file input and output flags listed above.
+- Also supports the shared base processing flags, watch flags, bundling flags listed above.
+
+**Command options**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--prompt` | `string` | no | `"A red bicycle in a studio"` | Which text to speak. You can also set this to null and supply an input text file. |
+| `--provider` | `string` | yes | `aws` | Which AI provider to leverage. Transloadit outsources this task and abstracts the interface so you can expect the same data structures, but different latencies and information… |
+| `--target-language` | `string` | no | `en-US` | The written language of the document. This will also be the language of the spoken text. The language should be specified in the BCP-47 format, such as "en-GB", "de-DE" or… |
+| `--voice` | `string` | no | `female-1` | The gender to be used for voice synthesis. Please consult the list of supported languages and voices. |
+| `--ssml` | `boolean` | no | `true` | Supply Speech Synthesis Markup Language instead of raw text, in order to gain more control over how your text is voiced, including rests and pronounciations. |
+
+**Examples**
+
+```bash
+transloadit text speak --input input.pdf --provider aws --out output.mp3
+```
+
+#### `video thumbs`
+
+Extract thumbnails from videos
+
+Runs `/video/thumbs` on each input file and writes the results to `--out`.
+
+**Usage**
+
+```bash
+npx transloadit video thumbs --input <path|dir|url|-> [options]
+```
+
+**Quick facts**
+
+- Input: file, dir, URL, base64
+- Output: directory
+- Execution: per-file; supports `--single-assembly` and `--watch`
+- Backend: `/video/thumbs`
+
+**Shared flags**
+
+- Uses the shared file input and output flags listed above.
+- Also supports the shared base processing flags, watch flags, bundling flags listed above.
+
+**Command options**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--ffmpeg` | `json` | no | `value` | A parameter object to be passed to FFmpeg. If a preset is used, the options specified are merged on top of the ones from the preset. For available options, see the FFmpeg… |
+| `--count` | `number` | no | `1` | The number of thumbnails to be extracted. As some videos have incorrect durations, the actual number of thumbnails generated may be less in rare cases. The maximum number of… |
+| `--offsets` | `auto` | no | `value` | An array of offsets representing seconds of the file duration, such as [ 2, 45, 120 ]. |
+| `--format` | `string` | no | `jpg` | The format of the extracted thumbnail. Supported values are "jpg", "jpeg" and "png". Even if you specify the format to be "jpeg" the resulting thumbnails will have a "jpg" file… |
+| `--width` | `number` | no | `1` | The width of the thumbnail, in pixels. Defaults to the original width of the video. |
+| `--height` | `number` | no | `1` | The height of the thumbnail, in pixels. Defaults to the original height of the video. |
+| `--resize-strategy` | `string` | no | `crop` | One of the available resize strategies. |
+| `--background` | `string` | no | `value` | The background color of the resulting thumbnails in the "rrggbbaa" format (red, green, blue, alpha) when used with the "pad" resize strategy. The default color is black. |
+| `--rotate` | `number` | no | `0` | Forces the video to be rotated by the specified degree integer. |
+| `--input-codec` | `string` | no | `value` | Specifies the input codec to use when decoding the video. This is useful for videos with special codecs that require specific decoders. |
+
+**Examples**
+
+```bash
+transloadit video thumbs --input input.mp4 --out output/
+```
+
+#### `video encode-hls`
+
+Run builtin/encode-hls-video@latest
+
+Runs the `builtin/encode-hls-video@latest` template and writes the outputs to `--out`.
+
+**Usage**
+
+```bash
+npx transloadit video encode-hls --input <path|dir|url|-> [options]
+```
+
+**Quick facts**
+
+- Input: file, dir, URL, base64
+- Output: directory
+- Execution: per-file; supports `--single-assembly` and `--watch`
+- Backend: `builtin/encode-hls-video@latest`
+
+**Shared flags**
+
+- Uses the shared file input and output flags listed above.
+- Also supports the shared base processing flags, watch flags, bundling flags listed above.
+
+**Examples**
+
+```bash
+transloadit video encode-hls --input input.mp4 --out output/
+```
+
+#### `image describe`
+
+Describe images as labels or publishable text fields
+
+Generates image labels through `/image/describe`, or structured altText/title/caption/description through `/ai/chat`, then writes the JSON result to `--out`.
+
+**Usage**
+
+```bash
+npx transloadit image describe --input <path|dir|url|-> [options]
+```
+
+**Quick facts**
+
+- Input: file, dir, URL, base64
+- Output: file
+- Execution: per-file; supports `--watch`
+- Backend: semantic alias `image-describe`
+
+**Shared flags**
+
+- Uses the shared file input and output flags listed above.
+- Also supports the shared base processing flags, watch flags listed above.
+
+**Command options**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--fields` | `string[]` | no | — | Describe output fields to generate, for example labels or altText,title,caption,description |
+| `--for` | `string` | no | — | Use a named output profile, currently: wordpress |
+| `--model` | `string` | no | — | Model to use for generated text fields (default: anthropic/claude-4-sonnet-20250514) |
+
+**Examples**
+
+```bash
+# Describe an image as labels
+transloadit image describe --input hero.jpg --out labels.json
+# Generate WordPress-ready fields
+transloadit image describe --input hero.jpg --for wordpress --out fields.json
+# Request a custom field set
+transloadit image describe --input hero.jpg --fields altText,title,caption --out fields.json
+```
+
+#### `markdown pdf`
+
+Render Markdown files as PDFs
+
+Runs `/document/convert` with `format: pdf`, letting the backend render Markdown and preserve features such as internal heading links in the generated PDF.
+
+**Usage**
+
+```bash
+npx transloadit markdown pdf --input <path|dir|url|-> [options]
+```
+
+**Quick facts**
+
+- Input: file, dir, URL, base64
+- Output: file
+- Execution: per-file; supports `--watch`
+- Backend: semantic alias `markdown-pdf`
+
+**Shared flags**
+
+- Uses the shared file input and output flags listed above.
+- Also supports the shared base processing flags, watch flags listed above.
+
+**Command options**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--markdown-format` | `string` | no | — | Markdown variant to parse, either commonmark or gfm |
+| `--markdown-theme` | `string` | no | — | Markdown theme to render, either github or bare |
+
+**Examples**
+
+```bash
+# Render a Markdown file as a PDF file
+transloadit markdown pdf --input README.md --out README.pdf
+# Print a temporary result URL without downloading locally
+transloadit markdown pdf --input README.md --print-urls
+```
+
+#### `markdown docx`
+
+Render Markdown files as DOCX documents
+
+Runs `/document/convert` with `format: docx`, letting the backend render Markdown and convert it into a Word document.
+
+**Usage**
+
+```bash
+npx transloadit markdown docx --input <path|dir|url|-> [options]
+```
+
+**Quick facts**
+
+- Input: file, dir, URL, base64
+- Output: file
+- Execution: per-file; supports `--watch`
+- Backend: semantic alias `markdown-docx`
+
+**Shared flags**
+
+- Uses the shared file input and output flags listed above.
+- Also supports the shared base processing flags, watch flags listed above.
+
+**Command options**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--markdown-format` | `string` | no | — | Markdown variant to parse, either commonmark or gfm |
+| `--markdown-theme` | `string` | no | — | Markdown theme to render, either github or bare |
+
+**Examples**
+
+```bash
+# Render a Markdown file as a DOCX file
+transloadit markdown docx --input README.md --out README.docx
+# Print a temporary result URL without downloading locally
+transloadit markdown docx --input README.md --print-urls
+```
+
+#### `file compress`
+
+Compress files
+
+Runs `/file/compress` for the provided inputs and writes the result to `--out`.
+
+**Usage**
+
+```bash
+npx transloadit file compress --input <path|dir|url|-> [options]
+```
+
+**Quick facts**
+
+- Input: file, dir, URL, base64
+- Output: file
+- Execution: single assembly
+- Backend: `/file/compress`
+
+**Shared flags**
+
+- Uses the shared file input and output flags listed above.
+- Also supports the shared base processing flags listed above.
+
+**Command options**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--format` | `string` | no | `zip` | The format of the archive to be created. Supported values are "tar" and "zip". Note that "tar" without setting gzip to true results in an archive that's not compressed in any way. |
+| `--gzip` | `boolean` | no | `true` | Determines if the result archive should also be gzipped. Gzip compression is only applied if you use the "tar" format. |
+| `--password` | `string` | no | `value` | This allows you to encrypt all archive contents with a password and thereby protect it against unauthorized use. |
+| `--compression-level` | `number` | no | `1` | Determines how fiercely to try to compress the archive. -0 is compressionless, which is suitable for media that is already compressed. -1 is fastest with lowest compression. -9… |
+| `--file-layout` | `string` | no | `advanced` | Determines if the result archive should contain all files in one directory (value for this is "simple") or in subfolders according to the explanation below (value for this is… |
+| `--archive-name` | `string` | no | `value` | The name of the archive file to be created (without the file extension). |
+| `--path` | `string` | no | `value` | The path at which each file is to be placed inside the archive. |
+
+**Examples**
+
+```bash
+transloadit file compress --input input.file --out output.file
+```
+
+#### `file decompress`
+
+Decompress archives
+
+Runs `/file/decompress` on each input file and writes the results to `--out`.
+
+**Usage**
+
+```bash
+npx transloadit file decompress --input <path|dir|url|-> [options]
+```
+
+**Quick facts**
+
+- Input: file, dir, URL, base64
+- Output: directory
+- Execution: per-file; supports `--single-assembly` and `--watch`
+- Backend: `/file/decompress`
+
+**Shared flags**
+
+- Uses the shared file input and output flags listed above.
+- Also supports the shared base processing flags, watch flags, bundling flags listed above.
+
+**Command options**
+
+| Flag | Type | Required | Example | Description |
+| --- | --- | --- | --- | --- |
+| `--password` | `string` | no | `value` | The password to use for decrypting password-protected archives. |
+| `--turbo` | `boolean` | no | `true` | Enables Turbo Mode for /file/decompress. This setting defaults to true. Set it to false to disable Turbo Mode. When enabled, extracted files are emitted as soon as they are… |
+
+**Examples**
+
+```bash
+transloadit file decompress --input input.file --out output/
+```
+
+<!-- GENERATED_INTENT_DOCS:END -->
+
+For full control, create Assemblies directly using Assembly Instructions (steps) or Templates:
 
 ```bash
 # Process a file using a steps file
@@ -300,7 +1204,7 @@ npx transloadit assemblies list -l 7
 The following code will upload an image and resize it to a thumbnail:
 
 ```javascript
-import { Transloadit } from 'transloadit'
+import { Transloadit } from '@transloadit/node'
 
 const transloadit = new Transloadit({
   authKey: 'YOUR_TRANSLOADIT_KEY',
@@ -852,3 +1756,9 @@ Thanks to [Ian Hansen](https://github.com/supershabam) for donating the `translo
 ## Development
 
 See [CONTRIBUTING](./CONTRIBUTING.md).
+
+
+
+
+
+