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.

Inside your project, type:

yarn add transloadit@^4.0.0

npm install --save transloadit@^4.0.0

CLI

This package ships with a full-featured CLI:

export TRANSLOADIT_KEY="YOUR_TRANSLOADIT_KEY"
export TRANSLOADIT_SECRET="YOUR_TRANSLOADIT_SECRET"
npx transloadit --help

CommonJS projects

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

async function getClient() {
  const { Transloadit } = await import('transloadit')
  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'

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.