Skip to content
Uploadista Docs

Image Nodes

Optimize and transform images with resize, optimize, transform, and AI-powered operations.

Required Plugins

Section titled “Required Plugins”

Available Plugins

Section titled “Available Plugins”
Plugin Package Best For Speed
imagePlugin @uploadista/flow-images-sharp Node.js servers, full features 50-100ms
imagePluginNode @uploadista/flow-images-photon Edge/serverless (Cloudflare Workers) 5-10ms
imageAiPlugin @uploadista/flow-images-replicate AI operations (background removal) 5-20s

Installation

Section titled “Installation”
npm install @uploadista/flow-images-nodes @uploadista/flow-images-sharp
import { createUploadistaServer } from "@uploadista/server";
import { imagePlugin } from "@uploadista/flow-images-sharp";


const uploadista = await createUploadistaServer({
  // ...
  plugins: [
    imagePlugin(),
  ],
});

Features: Resize, optimize, transform, blur, rotate, watermark, logo, text overlay

Requirements: Node.js 18+

Plugin Comparison

Section titled “Plugin Comparison”
Feature Sharp Photon Replicate
Resize Yes Yes No
Optimize Yes Yes No
Blur Yes Yes No
Rotate Yes No No
Flip Yes Yes No
Grayscale Yes Yes No
Brightness/Contrast Yes Yes No
Watermark Yes No No
Logo overlay Yes No No
Text overlay Yes No No
Background removal No No Yes
AI upscale No No Yes
Environment Node.js Edge/Workers Any
Cost Free Free Per-request

Resize Node

Section titled “Resize Node”

Scale images to specific dimensions.

Package: @uploadista/flow-images-nodes

import { createResizeNode } from "@uploadista/flow-images-nodes";


// Resize to specific dimensions
const resizeNode = yield* createResizeNode("resize-1", {
  width: 800,
  height: 600,
  fit: "cover",
});


// Resize width only, maintain aspect ratio
const widthOnlyNode = yield* createResizeNode("resize-2", {
  width: 1200,
  fit: "contain",
});


// With streaming mode for large files
const streamingNode = yield* createResizeNode("resize-3", {
  width: 800,
  height: 600,
  fit: "cover",
}, {
  mode: "streaming",
  naming: { mode: "auto" },
});

Parameters

Section titled “Parameters”
Parameter Type Required Description
width number No* Target width in pixels
height number No* Target height in pixels
fit "contain" | "cover" | "fill" Yes How the image fits within dimensions

*At least one of width or height must be specified.

Options

Section titled “Options”
Option Type Default Description
mode "auto" | "buffered" | "streaming" "auto" Processing mode
keepOutput boolean false Keep output in flow results
naming FileNamingConfig - File naming configuration
streamingConfig.fileSizeThreshold number 1048576 Threshold for auto streaming (1MB)

Optimize Node

Section titled “Optimize Node”

Compress and convert image formats.

Package: @uploadista/flow-images-nodes

import { createOptimizeNode } from "@uploadista/flow-images-nodes";


// Convert to WebP with quality 80
const optimizeNode = yield* createOptimizeNode("optimize-1", {
  quality: 80,
  format: "webp",
});


// Maximum compression with AVIF
const avifNode = yield* createOptimizeNode("optimize-2", {
  quality: 75,
  format: "avif",
});


// High quality JPEG for compatibility
const jpegNode = yield* createOptimizeNode("optimize-3", {
  quality: 90,
  format: "jpeg",
}, {
  naming: { mode: "auto" },
});

Parameters

Section titled “Parameters”
Parameter Type Required Description
quality number (0-100) Yes Image quality percentage
format "jpeg" | "webp" | "png" | "avif" Yes Output image format

Options

Section titled “Options”
Option Type Default Description
mode "auto" | "buffered" | "streaming" "buffered" Processing mode
keepOutput boolean false Keep output in flow results
naming FileNamingConfig - File naming configuration

Recommended Settings:

  • quality: 85, format: "webp" - Good balance of size and quality
  • quality: 90, format: "jpeg" - Maximum compatibility
  • quality: 75, format: "avif" - Maximum compression

Transform Image Node

Section titled “Transform Image Node”

Apply multiple transformations in sequence.

Package: @uploadista/flow-images-nodes

import { createTransformImageNode } from "@uploadista/flow-images-nodes";


// Chain multiple transformations
const transformNode = yield* createTransformImageNode("transform-1", {
  transformations: [
    { type: "resize", width: 800, height: 600, fit: "cover" },
    { type: "brightness", value: 10 },
    { type: "sharpen" },
  ],
});


// Add watermark (Sharp only)
const watermarkNode = yield* createTransformImageNode("transform-2", {
  transformations: [
    { type: "resize", width: 1200, fit: "contain" },
    {
      type: "watermark",
      imagePath: "https://example.com/watermark.png",
      position: "bottom-right",
      opacity: 0.5,
    },
  ],
});


// Apply filters
const filterNode = yield* createTransformImageNode("transform-3", {
  transformations: [
    { type: "grayscale" },
    { type: "contrast", value: 20 },
  ],
});

Transformation Types

Section titled “Transformation Types”
Type Parameters Sharp Photon Description
resize width?, height?, fit Yes Yes Resize image
blur sigma (0.3-1000) Yes Yes Apply Gaussian blur
rotate angle, background? Yes No Rotate by degrees
flip direction (“horizontal” | “vertical”) Yes Yes Flip image
grayscale - Yes Yes Convert to grayscale
sepia - Yes Yes Apply sepia tone
brightness value (-100 to 100) Yes Yes Adjust brightness
contrast value (-100 to 100) Yes Yes Adjust contrast
sharpen sigma? Yes Yes Apply sharpening
watermark imagePath, position, opacity, offsetX?, offsetY? Yes No Add watermark
logo imagePath, position, scale, offsetX?, offsetY? Yes No Add logo overlay
text text, position, fontSize, color, fontFamily?, offsetX?, offsetY? Yes No Add text overlay

Position Values

Section titled “Position Values”

For watermark, logo, and text: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "center"

Remove Background Node

Section titled “Remove Background Node”

AI-powered background removal.

Package: @uploadista/flow-images-nodes

import { createRemoveBackgroundNode } from "@uploadista/flow-images-nodes";


// Remove background with default settings
const removeBgNode = yield* createRemoveBackgroundNode("remove-bg-1");


// With custom credential and naming
const customNode = yield* createRemoveBackgroundNode("remove-bg-2", {
  credentialId: "my-replicate-credential",
  naming: { mode: "auto" },
});

Parameters

Section titled “Parameters”
Parameter Type Required Default Description
credentialId string No - AI service credential ID
keepOutput boolean No false Keep output in flow results
naming FileNamingConfig No - File naming (auto suffix: nobg)

Performance: ~5-15s | Cost: ~$0.001-0.002 per image

Describe Image Node

Section titled “Describe Image Node”

Extract image metadata using AI.

Package: @uploadista/flow-images-nodes

import { createDescribeImageNode } from "@uploadista/flow-images-nodes";


// Describe image content
const describeNode = yield* createDescribeImageNode("describe-1");


// With custom credential
const customDescribeNode = yield* createDescribeImageNode("describe-2", {
  credentialId: "my-ai-credential",
  keepOutput: true,
});

Parameters

Section titled “Parameters”
Parameter Type Required Default Description
credentialId string No - AI service credential ID
keepOutput boolean No false Keep output in flow results

Output: Returns { description: string } with AI-generated image description.

Streaming Modes

Section titled “Streaming Modes”

All transform nodes support three processing modes:

Mode Description When to Use
auto Automatically selects streaming for files > 1MB Default, recommended
buffered Loads entire file into memory Small files, predictable memory
streaming Processes file as chunks Large files, memory-constrained

Performance

Section titled “Performance”
Operation Sharp Photon
Resize (1MB image) 50-100ms 5-10ms
Optimize (WebP) 100-200ms 10-15ms
Transform (multiple ops) 100-300ms 20-50ms
AI Operation Time Cost
Remove background 5-15s $0.001-0.002
Describe image 2-5s $0.001
Section titled “Related”