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

Note: This documentation covers Node SDK v4 (ESM, Node.js 20+). For legacy docs, see v3 or v2. For upgrade details, read the v3 → v4 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, type:

yarn add @transloadit/node

npm install --save @transloadit/node

CLI

This package ships with a full-featured CLI:

export TRANSLOADIT_KEY="YOUR_TRANSLOADIT_KEY"
export TRANSLOADIT_SECRET="YOUR_TRANSLOADIT_SECRET"
npx -y @transloadit/node --help

Note

The CLI binary is still called transloadit, so command examples may use npx transloadit ....

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.

For example:

export TRANSLOADIT_KEY="YOUR_TRANSLOADIT_KEY"
export TRANSLOADIT_SECRET="YOUR_TRANSLOADIT_SECRET"
npx -y transloadit markdown pdf --input ./README.md --print-urls

Other examples include:

npx -y transloadit image remove-background --input ./photo.jpg --print-urls
npx -y transloadit image generate --prompt "A red bicycle in a studio" --output bicycle.png
npx -y transloadit 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 -y transloadit 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.

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,
  })
}

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: 'YOUR_TRANSLOADIT_SECRET',
})

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")
  }
} catch (err) {
  console.error('❌ Unable to process Assembly.', err)
  if (err instanceof ApiError && err.assemblyId) {
    console.error(`💡 More info: https://transloadit.com/assemblies/${err.assemblyId}`)
  }
}

You can find details about your executed Assemblies here.

Examples

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

Documentation

See GitHub for the full documentation and the migration guide for v3 → v4 upgrade details.