Transloadit
Pricing
  • File Uploads
  • File Importing
  • Batch Processing
  • Video Encoding
  • Audio Encoding
  • Image Processing
  • Document Processing
  • Artificial Intelligence
  • File Filtering & Security
  • Media Cataloging
  • File Compression
  • Code Evaluation
  • File Exporting
  • Smart CDN
  • View all services
  • Explore integrations
  • Explore live demos
  • Uppy
  • TransloaditKit
  • Android SDK
  • Node.js SDK
  • Viewer for Next.js
  • Python SDK
  • Ruby SDK
  • Go SDK
  • Java SDK
  • PHP SDK
  • Zapier
  • MCP Server
  • Transloadit CLI
  • Terraform
  • Essentials
  • Best Practices
  • FAQ
  • Robots
  • API
  • Formats
  • Build your first app
  • About
  • Comparisons
  • Open Source
  • Testimonials
  • Jobs
  • Security
  • Posts
  • DevTimes
  • DevTips
  • Press
  • Research
  • Case Studies
  • Solutions
  • Guides
  • Glossary
  • Legal
  • Tools
  • Helping Coursera bring education to millions around the world
  • Transloadit Support
  • Open Source Support
  • Service level agreement
  • Book a demo with our engineers
EssentialsRobotsFAQAPIFormatsBest Practices
Getting started
  • Overview
  • My first App
  • Saving result files
Topics
  • Assembly Instructions
  • Assembly Variables
  • Dynamic Evaluation
  • Templates
  • Webhooks
  • Third-party Credentials
  • Builtin Templates
  • Resize Strategies
  • Assembly Execution Progress
  • Workspaces
  • AI Agents
  • Advanced use Parameter
  • The ignore_errors Parameter
Software Development Kits
  • Overview
  • Android SDK
  • Browsers
  • Convex
  • cURL
  • Go SDK
  • Java SDK
  • MCP Server
  • Multipart Form
  • Node.js SDK
  • Viewer for Next.js
  • PHP SDK
  • Python SDK
  • Ruby SDK
  • Terraform
  • TransloaditKit
  • Zapier Integration
Migration
  • Migration guides
  • Migrate from Cloudinary to Transloadit
  • Migrate from Uploadcare to Transloadit
  • Migrate from Mux to Transloadit
  • Migrate from Filestack to Transloadit

Node.js SDK

transloadit/node-sdk⁠

We have a fully featured software development kit for Node.js, to make it easy to talk to the Transloadit REST API from your Node apps.

Install

The current SDK is ESM-only and supports Node.js 20.10.0 or newer. The Storage examples below use SDK/CLI 6.9.0 or newer. For legacy docs, see v3⁠ or v2⁠. For upgrade details, read the migration guide⁠.

Use @transloadit/node as the package name. The legacy transloadit npm package name is kept as an alias for backward compatibility.

Inside your project, install the SDK with npm:

npm install @transloadit/node

If your project already uses Yarn or pnpm, keep its package manager and lockfile instead:

yarn add @transloadit/node

For pnpm, use pnpm add @transloadit/node.

CLI

This package ships with a full-featured CLI:

npx @transloadit/node --help
npx @transloadit/node auth login

Login opens the browser so you can choose a Workspace and approve the CLI without copying an API secret into your shell. For automation and application servers, use separately configured Auth Keys; the credential reference⁠ describes the supported options. Do not deploy the disposable CLI login key as an application key.

Note

npx @transloadit/node uses the CLI from your installed SDK, or offers to fetch it if the package is absent. The examples name the package explicitly; no global install is required. For a standalone Storage demo, use the maintained upload-once initializer.

Intent commands

For quick one-off jobs, the CLI also ships with high-level Intent commands. These wrap common Transloadit workflows behind guessable subcommands, so you do not have to start with JSON Assembly Instructions for every task.

If you export an Auth Key instead of using browser login, match its Signature algorithm. The manual-key CLI example and JavaScript examples below use SHA-256, which Auth Keys with Smart CDN signing enabled accept. If your key uses another algorithm, such as SHA-384 on keys without Smart CDN signing, set the matching value in TRANSLOADIT_SIGNATURE_ALGORITHM and signatureAlgorithm.

For example:

export TRANSLOADIT_KEY="YOUR_TRANSLOADIT_KEY"
export TRANSLOADIT_SECRET="YOUR_TRANSLOADIT_SECRET"
export TRANSLOADIT_SIGNATURE_ALGORITHM="sha256"
npx @transloadit/node markdown pdf --input ./README.md --print-urls

Other examples include:

  • npx @transloadit/node image remove-background --input ./photo.jpg --print-urls
  • npx @transloadit/node image generate --prompt "A red bicycle in a studio" --output bicycle.png
  • npx @transloadit/node image generate --input ./person1.jpg --input ./person2.jpg --input ./background.jpg --prompt "Place person1.jpg feeding person2.jpg in front of background.jpg" --output scene.png
  • npx @transloadit/node image describe --input ./hero.jpg --for wordpress --output fields.json

image generate now defaults to google/nano-banana-2, including input-guided runs.

If you omit --output, the CLI writes next to a single local file input when it can. Otherwise it falls back to the current working directory. Use --print-urls on its own when you want temporary result URLs without downloading locally.

We also updated the public Transloadit skills repo⁠ to use the same Intent-based image generation flow.

For the full command reference, see the Intent Commands reference⁠ and the package README⁠.

Storage and image delivery

Try Storage and the Smart CDN with the upload-once example, or follow the Viewer for Next.js guide to render responsive images in an existing app.

The CLI can store mixed-media originals, not just images:

npx @transloadit/node storage store ./photo.jpg ./clip.mp4 ./guide.pdf website/media/

This does not publish the directory. Use storeAsset() for application-server uploads and keep the returned asset/version receipt with its owner. See mixed-media originals⁠ for byte verification, explicit overwrite, catalog recovery and original downloads. Existing HTTP/S3 sources can also use Viewer without migrating to Storage.

CommonJS projects

The SDK is ESM-only. If you are on CommonJS, use a dynamic import:

async function getClient() {
  const { Transloadit } = await import('@transloadit/node')
  return new Transloadit({
    authKey: process.env.TRANSLOADIT_KEY,
    authSecret: process.env.TRANSLOADIT_SECRET,
    // Match another Signature algorithm if your Auth Key requires one.
    signatureAlgorithm: 'sha256',
  })
}

Usage

The following code will upload an image and resize it to a thumbnail:

import { ApiError, Transloadit } from '@transloadit/node'

const transloadit = new Transloadit({
  authKey: 'YOUR_TRANSLOADIT_KEY',
  authSecret: process.env.TRANSLOADIT_SECRET,
  // Match another Signature algorithm if your Auth Key requires one.
  signatureAlgorithm: 'sha256',
})

try {
  const options = {
    files: {
      file1: '/PATH/TO/FILE.jpg',
    },
    params: {
      steps: {
        // You can have many Steps. In this case we will just resize any inputs (:original)
        resize: {
          use: ':original',
          robot: '/image/resize',
          result: true,
          width: 75,
          height: 75,
        },
      },
      // OR if you already created a template, you can use it instead of "steps":
      // template_id: 'YOUR_TEMPLATE_ID',
    },
    waitForCompletion: true, // Wait for the Assembly (job) to finish executing before returning
  }

  const status = await transloadit.createAssembly(options)

  if (status.results.resize) {
    console.log('✅ Success - Your resized image:', status.results.resize[0].ssl_url)
  } else {
    console.log("❌ The Assembly didn't produce any output. Make sure you used a valid image file")
    process.exitCode = 1
  }
} catch (err) {
  console.error('❌ Unable to process Assembly:', err instanceof ApiError ? (err.code ?? 'API request failed.') : 'Check your connection and input files.')
  process.exitCode = 1
  if (err instanceof ApiError && err.assemblyId) {
    console.error(`💡 More info: https://api2.transloadit.com/assemblies/${err.assemblyId}`)
  }
}

You can find details about your executed Assemblies here.

Examples

  • Upload and resize image⁠
  • Upload image and convert to WebP⁠
  • Rasterize SVG to PNG⁠
  • Crop a face out of an image and download the result⁠
  • Retry example⁠
  • Calculate total costs (GB usage)⁠
  • Templates CRUD⁠
  • Template credentials CRUD⁠

For more fully working examples take a look at examples/⁠.

Documentation

See GitHub⁠ for the full documentation and the migration guide⁠ for upgrade details.

Previous page ← Multipart FormNext page Viewer for Next.js →
Contact support
TransloaditChecking status…

Product

  • Services
  • Pricing
  • Demos
  • Tools
  • Security
  • Support

Company

  • About/Press
  • Blog/Jobs
  • Comparisons/Compliance matrix
  • Research
  • Open source
  • Solutions
  • Pioneers of the web

Docs

  • Getting started
  • Transcoding
  • FAQ
  • API
  • Guides/DevTips
  • Supported formats

More

  • Platform status⁠
  • Community forum⁠
  • Uppy
  • tus⁠

© 2009–2026 Transloadit-II GmbH

Transloadit®, tus®, and Uppy® are registered trademarks of Transloadit-II GmbH in the United States.

PrivacyTermsImprintTrademarksDMCA Policy
EnglishDeutschEspañolFrançaisPortuguês (Brasil)日本語