Node.js 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.
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-urlsnpx @transloadit/node image generate --prompt "A red bicycle in a studio" --output bicycle.pngnpx @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.pngnpx @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.