2.0.10 • Published 5 days ago

transloadit v2.0.10

Weekly downloads
Last release
5 days ago

Transloadit Node.js SDK npm.io npm.io

A Node.js integration for Transloadit's file uploading and encoding service.


Transloadit is a service that helps you handle file uploads, resize, crop and watermark your images, make GIFs, transcode your videos, extract thumbnails, generate audio waveforms, and so much more. In short, Transloadit is the Swiss Army Knife for your files.

This is a Node.js SDK to make it easy to talk to the Transloadit REST API.



Inside your project, type

yarn add transloadit


npm install transloadit --save


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

const TransloaditClient = require('transloadit')

const transloadit       = new TransloaditClient({

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].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.assemblyId) {
    console.error(`💡 More info: https://transloadit.com/assemblies/${err.assemblyId}`)

You can find details about your executed assemblies here.


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

For more example use cases and information about the available robots and their parameters, check out the Transloadit website.


This documentation is for the current version v3. Looking for v2 docs?.

These are the public methods on the TransloaditClient object and their descriptions. The methods are based on the Transloadit API.

View TypeScript definitions.

Table of contents:



Returns a new instance of the client.

The options object can contain the following keys:

  • authKey (required) - see requirements
  • authSecret (required) - see requirements
  • service (default 'api2.transloadit.com')
  • region (default 'us-east-1')
  • useSsl (default true) - use SSL to access service with a https:// prefix. Set to false to use http://
  • maxRetries (default 5) - see Rate limiting & auto retry
  • timeout (default 60000: 1 minute) - the timeout (in milliseconds) for all requests (except createAssembly)


TransloaditClient.createAssembly(options) -> Promise

Creates a new Assembly on Transloadit and optionally upload the specified files and uploads.

You can provide the following keys inside the options object:

  • params (required) - An object containing keys defining the assembly's behavior with the following keys: (See also API doc and examples)
    • steps - Assembly instructions - See Transloadit docs and demos for inspiration.
    • template_id - The ID of the Template that contains your Assembly Instructions. One of either steps or template_id is required. If you specify both, then any steps will overrule the template.
    • fields - An object of form fields to add to the request, to make use of in the assembly instructions via assembly variables.
    • notify_url - Transloadit can send a Pingback to your server when the Assembly is completed. We'll send the Assembly Status in JSON encoded string inside a transloadit field in a multipart POST request to the URL supplied here.
  • files - An object (key-value pairs) containing one or more file paths to upload and use in your assembly. The key is the field name and the value is the path to the file to be uploaded. The field name and the file's name may be used in the (assembly instructions) (params.steps) to refer to the particular file. See example below.
    • 'fieldName': '/path/to/file'
    • more files...
  • uploads - An object (key-value pairs) containing one or more files to upload and use in your assembly. The key is the file name and the value is the content of the file to be uploaded. Value can be one of many types:
    • 'fieldName': (Readable | Buffer | TypedArray | ArrayBuffer | string | Iterable<Buffer | string> | AsyncIterable<Buffer | string> | Promise)
    • more uploads...
  • waitForCompletion - A boolean (default is false) to indicate whether you want to wait for the Assembly to finish with all encoding results present before the promise is fulfilled. If waitForCompletion is true, this SDK will poll for status updates and fulfill the promise when all encoding work is done.
  • timeout - Number of milliseconds to wait before aborting (default 86400000: 24 hours).
  • onUploadProgress - An optional function that will be periodically called with the file upload progress, which is an with an object containing:
    • uploadedBytes - Number of bytes uploaded so far.
    • totalBytes - Total number of bytes to upload or undefined if unknown.
  • onAssemblyProgress - Once the assembly has started processing this will be called with the Assembly Execution Status (result of getAssembly) only if waitForCompletion is true.

Example code showing all options:

await transloadit.createAssembly({
  files: {
    file1: '/path/to/file.jpg'
    // ...
  uploads: {
    'file2.bin': Buffer.from([0, 0, 7]), // A buffer
    'file3.txt': 'file contents', // A string
    'file4.jpg': process.stdin // A stream
    // ...
  params: {
    steps: { ... },
    template_id: 'MY_TEMPLATE_ID',
    fields: {
      field1: 'Field value',
      // ...
    notify_url: 'https://example.com/notify-url',
  waitForCompletion: true,
  timeout: 60000,

Example onUploadProgress and onAssemblyProgress handlers:

function onUploadProgress({ uploadedBytes, totalBytes }) {
  console.log(`♻️ Upload progress polled: ${uploadedBytes} of ${totalBytes} bytes uploaded.`)
function onAssemblyProgress(assembly) {
  console.log(`♻️ Assembly progress polled: ${assembly.error ? assembly.error : assembly.ok} ${assembly.assembly_id} ... `)

See also:

TransloaditClient.listAssemblies(params) -> Promise

Retrieves an array of assemblies according to the given params.

Valid params can be page, pagesize, type, fromdate, todate and keywords. Please consult the API documentation for details.


Creates an objectMode Readable stream that automates handling of listAssemblies pagination. It accepts the same params as listAssemblies.

This can be used to iterate through assemblies:

const assemblyStream = transloadit.streamAssemblies({ fromdate: '2016-08-19 01:15:00 UTC' });

assemblyStream.on('readable', function() {
  const assembly = assemblyStream.read();
  if (assembly == null) console.log('end of stream');


Results can also be piped. Here's an example using through2:

const assemblyStream = transloadit.streamAssemblies({ fromdate: '2016-08-19 01:15:00 UTC' });

  .pipe(through.obj(function(chunk, enc, callback) {
    this.push(chunk.id + '\n');

TransloaditClient.getAssembly(assemblyId) -> Promise

Retrieves the JSON status of the assembly identified by the given assemblyId. See API documentation.

TransloaditClient.cancelAssembly(assemblyId) -> Promise

Removes the assembly identified by the given assemblyId from the memory of the Transloadit machines, ultimately cancelling it. This does not delete the assembly from the database - you can still access it on https://transloadit.com/assemblies/{assembly_id} in your Transloadit account. This also does not delete any files associated with the assembly from the Transloadit servers. See API documentation.

TransloaditClient.replayAssembly(assemblyId, params) -> Promise

Replays the assembly identified by the given assemblyId (required argument). Optionally you can also provide a notify_url key inside params if you want to change the notification target. See API documentation for more info about params.

TransloaditClient.awaitAssemblyCompletion(assemblyId, opts) -> Promise

This function will continously poll the specified assembly assemblyId and resolve when it is done uploading and executing (until result.ok is no longer ASSEMBLY_UPLOADING, ASSEMBLY_EXECUTING or ASSEMBLY_REPLAYING). It resolves with the same value as getAssembly.

opts is an object with the keys:

  • onAssemblyProgress - A progress function called on each poll. See createAssembly
  • timeout - How many milliseconds until polling times out (default: no timeout)
  • interval - Poll interval in milliseconds (default 1000)


Returns the internal url that was used for the last call to createAssembly. This is meant to be used for debugging purposes.

Assembly notifications

TransloaditClient.replayAssemblyNotification(assemblyId, params) -> Promise

Replays the notification for the assembly identified by the given assemblyId (required argument). Optionally you can also provide a notify_url key inside params if you want to change the notification target. See API documentation for more info about params.

TransloaditClient.listAssemblyNotifications(params) -> Promise

Retrieves an array of assembly notifications. See example and API documentation for more info about params.


Creates an objectMode Readable stream that automates handling of listAssemblynotifications pagination. Similar to streamAssemblies.


Templates are steps that can be reused. See example template code.

TransloaditClient.createTemplate(params) -> Promise

Creates a template the provided params. The required params keys are:

  • name - The template name
  • template - The template JSON object containing its steps

See also API documentation.

const template = {
  steps: {
    encode: {
      use   : ':original',
      robot : '/video/encode',
      preset: 'ipad-high',
    thumbnail: {
      use  : 'encode',
      robot: '/video/thumbnails',

const result = await transloadit.createTemplate({ name: 'my-template-name', template })
console.log('✅ Template created with template_id', result.id)

TransloaditClient.editTemplate(templateId, params) -> Promise

Updates the template represented by the given templateId with the new value. The params works just like the one from the createTemplate call. See API documentation.

TransloaditClient.getTemplate(templateId) -> Promise

Retrieves the name and the template JSON for the template represented by the given templateId. See API documentation.

TransloaditClient.deleteTemplate(templateId) -> Promise

Deletes the template represented by the given templateId. See API documentation.

TransloaditClient.listTemplates(params) -> Promise

Retrieves a list of all your templates. See API documentation for more info about params.


Creates an objectMode Readable stream that automates handling of listTemplates pagination. Similar to streamAssemblies.



Same as constructor timeout option: Set the default timeout (in milliseconds) for all requests (except createAssembly)

TransloaditClient.getBill(date) -> Promise

Retrieves the billing data for a given date string with format YYYY-MM. See API documentation.


Calculates a signature for the given params JSON object. If the params object does not include an authKey or expires keys (and their values) in the auth sub-key, then they are set automatically.

This function returns an object with the key signature (containing the calculated signature string) and a key params, which contains the stringified version of the passed params object (including the set expires and authKey keys).


Errors from Node.js will be passed on and we use GOT for HTTP requests and errors from there will also be passed on. When the HTTP response code is not 200, the error will be a TransloaditClient.HTTPError, which is a got.HTTPError) with some additional properties:

  • HTTPError.response?.body the JSON object returned by the server along with the error response (note: HTTPError.response will be undefined for non-server errors)
  • HTTPError.transloaditErrorCode alias for HTTPError.response.body.error (View all error codes)
  • HTTPError.assemblyId (alias for HTTPError.response.body.assembly_id, if the request regards an Assembly)

To identify errors you can either check its props or use instanceof, e.g.:

catch (err) {
  if (err instanceof TransloaditClient.TimeoutError) {
    return console.error('The request timed out', err)
  if (err.code === 'ENOENT') {
    return console.error('Cannot open file', err)
  if (err.transloaditErrorCode === 'ASSEMBLY_INVALID_STEPS') {
    return console.error('Invalid assembly steps', err)

Note: Assemblies that have an error status (assembly.error) will only result in an error thrown from createAssembly and replayAssembly. For other assembly methods, no errors will be thrown, but any error can be found in the response's error property

Rate limiting & auto retry

All functions of the client automatically obey all rate limiting imposed by Transloadit (e.g. RATE_LIMIT_REACHED). It will automatically retry requests 5 times with auto back-off (maxRetries option). There is no need to write your own wrapper scripts to handle rate limits.

If you want to retry on other errors, please see the retry example code.


This project uses debug so you can run node with the DEBUG=transloadit evironment variable to enable verbose logging. Example:

DEBUG=transloadit* node examples/template_api.js


We'd be happy to accept pull requests. If you plan on working on something big, please first drop us a line!


Check your sources for linting errors via npm run lint, and unit tests, and run them via npm run test


Releasing a new version to npmjs.org can be done via npm run release:major (or minor / patch, depending on the semantic versioning impact of your changes). This will automatically:

  • Bump the version inside the package.json
  • Save a release commit with the updated version in Git
  • Push a tag to Github
  • Publish to npmjs.org


If you come from a unix background and fancy faster auto-complete, you'll be delighted to know that all npm scripts are also accessible under make, via fakefile.


Contributions from:

Thanks to:

  • Ian Hansen for donating the transloadit npm name. You can still access his code under v0.0.0.


MIT Licensed.


5 days ago


5 days ago


11 months ago


12 months ago


2 years ago


2 years ago


2 years ago


2 years ago


3 years ago


3 years ago


3 years ago


3 years ago


3 years ago


3 years ago


3 years ago


3 years ago


3 years ago


3 years ago


4 years ago


4 years ago


4 years ago


4 years ago


4 years ago


4 years ago


5 years ago


5 years ago


5 years ago


5 years ago


6 years ago


6 years ago


6 years ago


6 years ago


7 years ago


7 years ago


7 years ago


7 years ago


9 years ago