Image Nodes

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

Required Plugins

Plugin Required

Image processing nodes require a plugin to execute. You must install and provide one of the image plugins listed below.

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

Sharp (Recommended)

npm

npm install @uploadista/flow-images-nodes @uploadista/flow-images-sharp

pnpm

pnpm add @uploadista/flow-images-nodes @uploadista/flow-images-sharp

yarn

yarn add @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+

Photon (Edge)

npm

npm install @uploadista/flow-images-nodes @uploadista/flow-images-photon

pnpm

pnpm add @uploadista/flow-images-nodes @uploadista/flow-images-photon

yarn

yarn add @uploadista/flow-images-nodes @uploadista/flow-images-photon

import { createUploadistaServer } from "@uploadista/server";
// For Node.js
import { imagePluginNode } from "@uploadista/flow-images-photon/node";
// For Serverless (Cloudflare Workers)
import { imagePluginServerless } from "@uploadista/flow-images-photon/serverless";

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

Features: Resize, optimize, blur, flip, grayscale, sepia, brightness, contrast, sharpen

Limitations: No rotate, watermark, logo, or text overlay support

Replicate (AI)

npm

npm install @uploadista/flow-images-nodes @uploadista/flow-images-replicate

pnpm

pnpm add @uploadista/flow-images-nodes @uploadista/flow-images-replicate

yarn

yarn add @uploadista/flow-images-nodes @uploadista/flow-images-replicate

import { createUploadistaServer } from "@uploadista/server";
import { imageAiPlugin } from "@uploadista/flow-images-replicate";

const uploadista = await createUploadistaServer({
  // ...
  plugins: [
    imageAiPlugin(process.env.REPLICATE_API_TOKEN),
  ],
});

Features: AI background removal, upscaling, style transfer

Requirements: Replicate API token

Cost: ~$0.001-0.05 per operation

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

Scale images to specific dimensions.

Requires Plugin

ImagePlugin - Use @uploadista/flow-images-sharp or @uploadista/flow-images-photon

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

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

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

Compress and convert image formats.

Requires Plugin

ImagePlugin - Use @uploadista/flow-images-sharp or @uploadista/flow-images-photon

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

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

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

Apply multiple transformations in sequence.

Requires Plugin

ImagePlugin - Use @uploadista/flow-images-sharp (full support) or @uploadista/flow-images-photon (limited support)

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

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

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

---

Remove Background Node

AI-powered background removal.

Requires Plugin

ImageAiPlugin - Use @uploadista/flow-images-replicate (requires API token)

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

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

Extract image metadata using AI.

Requires Plugin

ImageAiPlugin - Use @uploadista/flow-images-replicate (requires API token)

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

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

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

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

---

Related

• Plugins Concept - How plugins work
• Flow Nodes Overview - All available nodes