1. Basics

1.1 How to Read the Docs

Welcome to our documentation section! There are 3 pages in our docs. These are:

  1. The Integration page, the one you are on right now. It explains the basics of our API service including terminology, the flow of things and how to build encoding instructions. It shows you all the possibilities there are concerning how to integrate with the service.
  2. The API page explains the different available endpoints, their request and response structures as well as how to authenticate yourself with the API.
  3. Robots gives an overview of all the available conversion types (image resizing, video encoding, etc.) and their available parameters.

The remaining two tabs in our header are Formats and FAQ. They can be used for reference.

We recommend that you first read through the Basics section. Then you will want to check out all the different conversion robots that we have on offer in Robots, so that you can already see if your desired features are available. The rest of the documentation is for reference and can be read as you see fit.

1.2 Introduction

What We Offer

We offer all of the required components to manage file uploads and conversions for your web or mobile application:

  • A RESTful JSON API for managing the encoding/resizing/conversion of images, videos, documents, etc.

  • A jQuery plugin to facilitate enabling Transloadit functionality in your HTML forms.

  • Development kits for all popular languages which allow you to send API calls from your back-end.

The Basic Flow

  1. You send files via a POST request to our API, either manually with Curl or with one of our SDKs.
  2. Transloadit processes the files, encodes videos, resizes images, etc.
  3. We notify your app with a POST request at a callback URL and include JSON containing the meta and URLs of the encoding results.
  4. In your back-end you store the URLs to the result files in your database and display beautiful videos and images to your users.

The Basic Flow With jQuery

Our jQuery plugin really helps when you want to use Transloadit with HTML forms.

  1. You include it on your HTML page to enable upload forms to use Transloadit. When your user submits the form, the selected files are uploaded to Transloadit.
  2. Transloadit processes the uploaded files, such as by encoding videos, resizing images, and storing the results on Amazon S3 for example.
  3. Once processing is completed, the jQuery plugin attaches the result JSON in a hidden field called transloadit to your form. Then, the form is submitted as it would have been normally.
  4. In your back-end, you analyze the result JSON from the transloadit form field and store the URLs to the result files in your database. Then you display beautiful videos and images to your users.

Terminology

  • Assembly

    An Assembly is the execution of file conversion instructions (called Assembly Instructions) against uploaded and/or imported files. Each Assembly has a unique assembly_id identifier that can be used to refer to the Assembly in subsequent API requests.

  • Assembly Instructions

    The set of Assembly Steps that the Transloadit back-end executes on the uploaded/imported files.

  • Assembly Notification

    The sending of the results of an Assembly in a POST request to a URL of your choice. It is optional to use Assembly Notifications.

  • Assembly Step

    One processing Step that files undergo in an Assembly. Each Step does some type of encoding, resizing or conversion. You can name Steps however you want in the JSON.

  • Robot

    Each Assembly Step uses exactly one robot. We have a robot for video encoding, one for image manipulation, etc. You can set parameters in your Assembly Step that define how exactly the specified robot should convert your files.

  • Template

    A Template allows you to save Assembly Instructions securely in your account on transloadit.com, so that you can hide them from your users. You would reference them via a template_id parameter in your API request.

1.3 the Minimal Integration

The following step-by-step guide explains how to implement a minimal image resize upload using Transloadit.

Step 1: Create Your Account

Create a new account using our signup page. Your API credentials will be generated automatically. Then, log in to your account.

Step 2: Create the Upload Form

In your web page, edit the source of the page and add the HTML for a form:

<form id="upload-form" action="/uploads" enctype="multipart/form-data" method="POST">
  <input type="file" name="my_file" />
  <input type="submit" value="Upload">
</form>

Make sure that enctype is set to multipart/form-data. If it is not, browsers will not understand that this form is used to upload files.

Also your file input field(s) must contain a name attribute.

Step 3: Add the jQuery Plugin

The Transloadit jQuery plugin provides some additional functionality, allowing you to:

  • show file upload progress,
  • get upload results directly without further API queries, and
  • wait for all file conversions to complete before final form submission.

You can use the following HTML/JavaScript to add our jQuery plugin:

<!-- You can choose jQuery version 1.9.0 or any newer version here -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
<script src="//assets.transloadit.com/js/jquery.transloadit2-v2-latest.js"></script>
<script type="text/javascript">
$(function() {
  $('#upload-form').transloadit({
    wait: true,
    params: {
      auth: { key: "YOUR_TRANSLOADIT_AUTH_KEY" },
      steps: {
        resize_to_75: {
          robot: "/image/resize",
          use: ":original",
          width: 75,
          height: 75
        }
      }
    }
  });
});
</script>

Please make sure you replace YOUR_TRANSLOADIT_AUTH_KEY with the key found on the API credentials page.

The wait parameter specifies whether Transloadit should wait for all files to be processed before submitting the final form. In this case, it means Transloadit will first wait for all uploaded files to be resized to 75x75 pixels before submitting the final form. If you set it to false you will require Transloadit to notify you when the file processing is done. But more on that later.

The steps object allows you to set the Assembly Instructions (the set of Assembly Steps) you want to use. You can use as many Steps as you want and you can also name them however you like! We only specify one Step here, which uses the /image/resize robot, and specifies use: ":original", which means the robot should use the originally uploaded files as input. You can also specify names of other Steps for the use parameter, but we'll learn more about that later.

Hint Using the jQuery plugin or one of our other development kits is the advised way of integration. However, by changing a few things, you can also get it to work without JavaScript enabled. Read more about that here.

Step 4: Testing

Now that the form is done, we are ready to upload a file. By default, this will display an overlay with a progress bar when a file is uploaded.

On your back-end page, return the incoming POST data to display the results that Transloadit appended to the form. For example, use something like the following for PHP:

The result of the print_r should be something like this:

Transloadit provides information about all uploaded files (the uploads key) as well as about all produced result files (the results key). They are both arrays in the result JSON. This is to support all use cases, including having multiple uploaded files and multiple encoding results.

Hint To see a working example of what we just built, see this demo page. The Assembly Instructions differ slightly, but should give you a good idea of how things work.

Specifying Assembly Instructions in the Form

Alternatively, you could have also added the Assembly Instructions in a hidden form field named params. Sometimes, especially when your instructions need to be calculated by a back-end language, it's just easier to specify them in the form directly than to add them in the call to the jQuery plugin

The contents of the hidden params field need to be encoded as JSON, with HTML entities escaped. Have your preferred scripting language encode the JSON for you to maintain readability. Here is an example in PHP:

$params = array(
  "auth" => array("key" => "YOUR_TRANSLOADIT_AUTH_KEY"),
  "steps" => array(
    "resize_to_75" => array(
      "robot" => "/image/resize",
      "use" => ":original",
      "width" => 75,
      "height" => 75
    )
  )
);

printf(
  '<input type="hidden" name="params" value="%s" />',
  htmlentities(json_encode($params))
);

Your form should then look like this (just with YOUR_TRANSLOADIT_AUTH_KEY replaced with your real Auth Key):

<form id="upload-form" action="http://api2.transloadit.com/assemblies" enctype="multipart/form-data" method="POST">
  <input type="hidden" name="params" value="{&quot;auth&quot;:{&quot;key&quot;:&quot;YOUR_TRANSLOADIT_AUTH_KEY&quot;},&quot;steps&quot;:{&quot;resize_to_75&quot;:{&quot;robot&quot;:&quot;\/image\/resize&quot;,&quot;use&quot;:&quot;:original&quot;,&quot;width&quot;:75,&quot;height&quot;:75}}}" />
  <input type="file" name="my_file" />
  <input type="submit" value="Upload">
</form>

Both ways of adding the Assembly Instructions to your form are valid. When you upload a file you should see the same result.

Closing Remarks

That's it already for the minimal integration - it was pretty simple wasn't it? If you want to there is a lot more that you can do, though.

For example, specifying your Assembly Instructions in the form directly or in your JavaScript makes them publicly visible. That's why you'll later learn about Templates in order to hide instructions within your Transloadit account.

Also you might have noticed that your Auth Key is also publicly visible using this integration method, allowing potentially anyone to upload files on your behalf driving your Transloadit bill up. To prevent this we offer signature authentication in order to make sure that only you and your users can create Assemblies in your account. After all we want to make sure things are secure. Please learn about signature authentication here.

The jQuery plugin is not the only way you can integrate with Transloadit. We offer software development kits for all major platforms and there are also a lot of community projects that you can use and learn from. And if none of the SDKs and community projects suit your requirements, then you could also write your own code to integrate with our JSON API.

1.4 Assembly Instructions

Basics

Since processing files is the heart of Transloadit, we have crafted a simple JSON format that enables Transloadit to do just about anything with them. Here is a simple example:

{
  auth: { key: "YOUR_TRANSLOADIT_AUTH_KEY" },
  steps: {
    encode: {
      robot: "/video/encode",
      use: ":original",
      preset: "iphone"
    },
    export: {
      robot: "/s3/store",
      use: "encode",
      bucket: "YOUR_AMAZON_S3_BUCKET"
      key: "YOUR_AMAZON_S3_KEY",
      secret: "YOUR_AMAZON_S3_SECRET",
    }
  }
}

These instructions consist of two Assembly Steps, encode and export, but you can name your Steps however you want. Giving them names (instead of numbers) makes it easier to reference them.

Each Step is defined as a JSON object with a robot and use key. They specify which robot should be used for the Assembly Step and which other Step the robot should use as its conversion input. By using :original you state that the originally uploaded files should be used as input.

All other parameters will be used for the file conversion itself.

Special Parameters

Special parameters are those interpreted by the Assembly engine itself, controlling the order and behavior of your Steps.

Parameter Description

robot

Specifies which processing robot to use for the Step.
Robots only accept certain file types. File types they cannot process will be ignored, no errors are thrown. The /video/encode robot, for example, will ignore images and the /image/resize robot will ignore videos.

use

Specifies which Assembly Step to use as the input to this Step.
This parameter is mandatory
Please use the value ":original" to reference uploaded files.

You can also specify an array here to use several Steps as the input to your step: use: [ ":original", "my_video_encode" ]

The Assembly engine passes every file individually through all Steps by default. If you would like to change that, then you need to use Step bundling.

Step bundling
Some robots like /media/playlist and /file/compress allow you to bundle several Steps to be used as the input. In the case of the /file/compress robot for example, you may not want to create one zip file for each of your uploaded files. Instead you may want to create one zip file that holds all the uploaded files. In this case you would set bundle_steps to true like this:

use: { steps: "segment_step_name", bundle_steps: true }

Please keep in mind, that all input Steps must actually be present in your Template when using Step bundling. If one of them is missing, the Assembly will just complete without the robot having done its job.

Demo
See a demo for the use parameter here.

result

Controls if the results of this Step should be returned.
If set to true this Step will occur in the Assembly's result JSON with a temporary URL referencing the result file.
For convenience reasons this is automatically set to true for any Steps that have no subsequent Step and false for all "in-between" steps.

If you set this to false this Step will not occur in the Assembly's result JSON, which can be useful if you want to keep the JSON small.

Executing Assembly Instructions

Transloadit processes as much as possible in parallel. Steps will be executed as soon as their input Steps are available. For example, let's say we want to encode a video that was uploaded and would also like to extract thumbnails from it:

Both the encode and the thumbs step will be executed in parallel as soon as the file upload is finished.

The export step is set up to use the results of encode and thumbs and will spawn an internal job for each file as soon as the results of these Steps become available.

As you can see, this format makes it easy to execute instructions as fast as possible.

Examples

Please check out our demo section for a lot of examples of simple and complex Assembly Instructions.

1.5 Templates

The Way to Secure Your Assembly Instructions

While specifying Assembly Instructions directly in the params field of a form is convenient, there are two major problems:

  • Anyone visiting your site can read your HTML source, and see your Assembly settings.
  • Embedded secrets such as S3 and SFTP access credentials are completely visible!

Due to these issues, we offer Templates.

They allow you to store Assembly Instructions securely on our servers, by using 256 bit AES encryption and then just include the Template's ID in a template_id key in the hidden params input field (or the call to the jQuery plugin).

This is useful for Assembly Instructions that use storage robots that require service access credentials (such as the S3 robot). Templates can be used to hide your secret credentials, to keep them from showing up in your HTML source.

The jQuery plugin's params object will be merged into the Template that you use, giving you a good means to overwrite your Templates on the fly. Think of an image cropping tool that allows your users to select a cropping area. You will want to overwrite the coordinates in your Template with the coordinates that your user chose. With this, there really is no reason to not use Templates.

How to Create a Template

  1. Log in to your Transloadit account on the website.
  2. Click on the "Templates" link under "My Account", and then click "Create template".
  3. Give your Template a name for future reference.
  4. Provide the JSON Assembly Instructions for your Template and hit save.

Once the Template is saved, a page is displayed showing the Template you created. At the top of the page the Template's template_id is shown, such as "4b62ee4dbb38455d96fe13d972ec3211". Then you can attach this ID to the template_id parameter in your Transloadit form parameters.

Hint The website also has a testing area where you can test your Templates with an upload form, without updating your own HTML forms.

How to Use a Template

Once you have a template_id, you can use the Template in a form by replacing the Assembly Steps in the jQuery plugin's params object with the Template id. For example, take the following:

With a Template, this would become something like this:

{
  $(function() {
    $('#upload-form').transloadit({
      wait: true,
      params: {
        auth: { key: "YOUR_TRANSLOADIT_AUTH_KEY" },
        template_id: "4b62ee4dbb38455d96fe13d972ec3211"
      }
    });
  });
}

1.6 Saving Conversion Results

Once your upload form is submitted (or the Assembly Notification was sent) and you have the results from Transloadit, you can save the URLs of the result files in your database.

In the response JSON you'll find an uploads key and a results key, which contain your original file uploads and the conversion results respectively. You can learn more about the response JSON and how it is formatted here.

Important Transloadit will save your files only temporarily. These temporary file URLs expire after 24 hours, making them inaccessible. To persist your files, you can use any of the following storage robots:

Transloadit is very good at extracting metadata from uploaded files. So, in addition to saving the URLs of the result files, you may want to consider saving the metadata as well. Users often appreciate seeing more information about the video or image they are looking at.

You are free to integrate any web services or tools for displaying your files on the web as you see fit. For displaying video, we recommend using flowplayer or mediaelementjs.

1.7 Speeding Things Up

In this section we'll explain how to speed things up and give your end-users a smoother experience.

Uploading Times

We have many machines that are dedicated to receiving uploads. We have clusters in Europe and the United states for redundancy and to reduce latency, since your users will be serviced by the machines closest to them.

Queue Times

Encoding is hard work for computers, so we use high end machines. We keep an overcapacity of 300% to handle traffic spikes. This ensures we rarely have a queue, but we can't rule it out completely, as customers could send us tough jobs faster than we can process them.

When our scaling software foresees a queue, new machines are launched to drain the queue. It takes five for a machine to come online, and we can launch up to 1500 of these in parallel.

You can check our current queue times for image conversion and video encoding on our Status Page. You can also programmatically check for them by accessing this JSON API page, which shows them in number of seconds.

Even though queues are a rare thing and we continually optimize for even faster encoding times, sometimes it just takes a few minutes. This is why we recommend to implement Transloadit in an asynchronous way: as soon as your users finish the upload they do not need to wait for file processing to complete. We then contact your app programmatically when the processing is done, and you can then notify your user via web / ajax / email and display the files.

If you want to use our jQuery plugin, we advise you to set its wait parameter to false and use Assembly Notifications instead. By doing this, your users will only have to wait for the uploading of the files to finish and then they can move on. Once Transloadit is done processing your files we will notify you at the notify_url with a POST request and you can start displaying files to your users.

This is the recommended way of integrating Transloadit and you should use it whenever you allow uploading files from a client. It's the best experience for your users and it's also the most reliable way of integrating, because it allows you to replay Assemblies (button is available on an Assembly detail page on the website) in case there was a problem.

Queues

We implement several queue types in order to keep our servers from falling apart. This is so important, that we have dedicated an entire section to it in our API basics. Please read this here.

2. Advanced

2.1 Dynamic Assembly Instructions

In addition to template_id, other parameters can be specified params object. These parameters act as variables to be recursively merged into the Template. For example, assume the following template:

{
  // the plugin initialization code above this
  steps: {
    encode: {
      use: ":original",
      robot: "/video/encode",
      preset: "iphone"
    },
    store: {
      use: "encode",
      robot: "/s3/store",
      key: "YOUR_AMAZON_S3_KEY",
      secret: "YOUR_AMAZON_S3_SECRET",
      bucket: "YOUR_AMAZON_S3_BUCKET"
    }
  }
}

Additional logic can be merged into the Template by adding a steps key as well:

{
  // the plugin initialization code above this
  auth: { key : "YOUR_TRANSLOADIT_AUTH_KEY"},
  template_id: "4b62ee4dbb38455d96fe13d972ec3211",
  steps: {
    store: {
      bucket: "other-bucket"
    }
  }
}

This is then merged to create the following Assembly Instructions:

{
  auth: { key: "YOUR_TRANSLOADIT_AUTH_KEY" },
  template_id: "4b62ee4dbb38455d96fe13d972ec3211",
  steps: {
    encode: {
      use: ":original",
      robot: "/video/encode",
      preset: "iphone"
    },
    store: {
      use: "encode",
      robot: "/s3/store",
      key: "YOUR_AMAZON_S3_KEY",
      secret: "YOUR_AMAZON_S3_SECRET",
      bucket: "other-bucket"
    }
  }
}

Important bucket has a value of "other-bucket" now. These additional params are to be passed to the form using the hidden params field.

2.2 Assembly Variables

The following is a list of placeholder variables available to Assembly Instructions. These can be used for any parameter value in any robot:

Variable Description
${assembly.id}

The ID of the Assembly representing the current upload.

${unique_prefix}

A unique 33-character prefix used to avoid file name collisions, such as "f2/d3eeeb67479f11f8b091b04f6181ad". Please notice the / in it. If you use ${unique_prefix} in the path parameter of the /s3/store Robot for example, then it will create sub-directories in your S3 bucket. This may or may not be desired. Please use ${assembly.id} or ${file.id} if you require a unique prefix without slashes.

${unique_original_prefix}

This is like ${unique_prefix} with the exception that two files that are encoding results of the same uploaded file (the original file) will have the same prefix value here.

${previous_step.name}

The name of the previous Step that produced the current file.

${file.id}

The ID of the file being processed, which is a 32 char long, unique UUID. It does not contain any periods, slashes or other non-alphanumeric characters.

${file.original_id}

The ID of the original file that this file derives from. For example if you use an import robot to import files and then encode them somehow, the encoding result files will have a ${file.original_id} that matches the ${file.id} of the imported file. For imported files ${file.original_id} equals ${file.id}.

${file.original_basename}

The basename of the original file that this file derives from. For example if you use an import robot to import files and then encode them somehow, the encoding result files will have a ${file.original_basename} that matches the ${file.basename} of the imported file. For imported files ${file.original_basename} equals ${file.basename}.

${file.original_path}

The import path of the original file that this file derives from. All our import robots set ${file.original_path} accordingly. For example if you use the /s3/import Robot to import files from Amazon S3, the imported files and all files that are derived from them will have a file.original_path that equals the path to the file on S3, but without the filename. So if the S3 path was "path/to/file.txt", then file.original_path will be "/path/to/". If the path was "/a.txt", ${file.original_path} will be "/". file.original_path will always have sufficient slashes so that you can use it safely like this in the path parameter of your export step: "path": "${file.original_path}${file.name}". This is handy if you want to import files from say S3, convert them somehow, and store them back to S3 in the same (or similar) file structure.

${file.name}

The name of the file being processed, including the file extension.

${file.url_name}

The name of the file, with any characters other than A-Za-z0-9-_. replaced with underscores, and with spaces replaced with dashes. This includes the file extension as well.

${file.basename}

The name of the file being processed, without the file extension.

${file.url_basename}

The basename of the file (the file name without the file extension), with any characters other than A-Za-z0-9-_. replaced with underscores, and with spaces replaced with dashes.

${file.ext}

The file extension.

${file.size}

The file size.

${file.mime}

The file's mime type.

${file.md5hash}

The file's MD5 hash. This is a hash over the file's contents, not just only over the file's name.

${file.*}

Any file property available in the final results array, such as ${file.meta.width}. Not all meta keys are available for all file types.

${fields.*}

The form fields submitted with the upload.
For example, ${fields.myvar} would contain a value of 1 for a form with a
<input type="hidden" name="myvar" value="1" /> field.

Example

To see a good example for the use of Assembly variables we can take a look at any of our file export robots. We'll use the /s3/store robot here, which allows you to store files on Amazon S3.

The robot has a parameter named path which controls where on S3 the files will be stored. The default value is "${unique_prefix}/${file.url_name}", which makes the files end up on S3 like "f2/my-file-name.png".

We could change the parameter's value to "${previous_step.name}/${unique_prefix}/${file.id}.${file.ext}" for example, which would make the files end up like video-step-name/a8/d3eeeb67479f11f8b091b04f6181ad.png.

Please note that Assembly variables have different levels of uniqueness. For example ${previous_step.name} is the same for all files that are results of the same Assembly Step. ${file.id} is unique for all files, including results of the same Assembly Step. ${file.ext} can be the same for all files, or can be totally unique, but ${assembly.id} for example is the same for all files.

2.3 Form Fields in Instructions

When you set the jQuery plugin's fields option to '*' (or to an object of key value pairs) and submit a form then the respective form input fields become available in the Assembly as variable names. For example, if a form has a textarea named message (using the name attribute), its value could be accessed using ${fields.message} in your path parameter of the store Step, such as the following:

{
  auth: { key: "YOUR_TRANSLOADIT_AUTH_KEY" },
  template_id: "4b62ee4dbb38455d96fe13d972ec3211",
  steps: {
    encode: {
      use: ":original",
      robot: "/video/encode",
      preset: "iphone"
    },
    store: {
      use: "encode",
      robot: "/s3/store",
      key: "YOUR_AMAZON_S3_KEY",
      secret: "YOUR_AMAZON_S3_SECRET",
      bucket: "other-bucket",
      path: "${assembly.id}/${fields.message}/356"
    }
  }
}

A fields key can also be added to the params object to inject variables independent of a form into the instructions:

{
  auth: { key: "YOUR_TRANSLOADIT_AUTH_KEY" },
  template_id: "4b62ee4dbb38455d96fe13d972ec3211",
  steps: {
    encode: {
      use: ":original",
      robot: "/video/encode",
      preset: "iphone"
    },
    store: {
      use: "encode",
      robot: "/s3/store",
      key: "YOUR_AMAZON_S3_KEY",
      secret: "YOUR_AMAZON_S3_SECRET",
      bucket: "other-bucket",
      path: "${assembly.id}/${fields.message}/356"
    }
  },
  fields: {
    message: "my value"
  }
}

Variables derived from form fields take precedence over those in the fields key above.

2.4 Assembly Notifications

An Assembly Notification is the sending of the results of an Assembly in a POST request to a URL of your choice. It is optional to use Assembly Notifications.

The script behind the URL of your choice (the notify_url) needs to respond with a 200 header, otherwise Transloadit assumes the Notification has failed. If that is the case, the Notification is retried up to 5 times over a period of 20 minutes.

Important If you'd like to test Assembly Notifications locally, we recommend a service like localtunnel.

The Browser Notifies Your App

With this approach visitors wait for both the file uploading and the file conversions to finish.

If you use our jQuery plugin and set its wait parameter to true, the plugin will append the file results to your form as soon as Transloadit has finished processing the upload. It then submits the form to the defined form action.

{
  auth: { key: "YOUR_TRANSLOADIT_AUTH_KEY" },
  steps: { ... }
}

Unfortunately, this approach has a clear disadvantage; once the file upload is finished, your users must wait for Transloadit to finish all processing, possibly including video encoding and image resizing, before the form is actually submitted to the final destination. This is not usually an issue for image processing, which is very fast in most cases, but definitely harms user experience for video encoding. In this case, consider using Notifications, as explained below.

Important For very specific use-cases it may help to take a look at the plugin's source code. You can also always ask us to clarify something or help you with integration.

Letting Transloadit Notify Your App

With this approach visitors only wait for the file uploading to finish. They do not wait for the file conversions to finish.

Notifications are a good way to obtain file results, since they allow you to specify a URL that Transloadit will use to contact you whenever an Assembly is completed, when all uploaded files have been encoded, resized, and otherwise processed.

All Notifications are sent as POST requests, with a field called transloadit. For details about this response format, see the API documentation for the Transloadit response format.

They also contain a signature field, with the signature calculated for the Notification. This allows you to verify that it was actually Transloadit sending this Notification. You can learn more about Notification signatures here

To use Notifications, simply add a notify_url parameter to your params field or your template:

{
  auth: { key: "YOUR_TRANSLOADIT_AUTH_KEY" },
  steps: { ... },
  notify_url: "http://example.org/files_ready"
}

One common use case is to include our jQuery plugin, set the wait parameter to false, and use notify_url. This will submit the form to its action attribute as soon as the upload has finished, without waiting for the Transloadit results. Transloadit reports the results to your server once the uploaded files are processed.

Note This provides the best experience, since it prevents users from waiting unnecessarily when files are uploaded.

The JSON sent to your app server will also contain a property called signature. This is the signature calculated for the Assembly Notification. If you calculate the signature for the whole request yourself with your auth secret, you can verify if the request is actually from Transloadit (the signatures match) and has not been tampered with (the signatures do not match). For more details regarding signature calculation please read signature authentication.

If you would like to test your Assembly Notifications locally we recommend using services such as ngrok. If this is not possible for you, then you could also take a look at this community project.

If You Cannot Rely on JavaScript Being Enabled

(You can safely ignore this section if you are going to use our jQuery plugin or some other JavaScript integration.)

So far we have assumed that you are using the jQuery plugin (or your own plugin). But sometimes (read: very rarely) you cannot rely on JavaScript being available in the browser.

In this case, you must set your form's action attribute to "http://api2.transloadit.com/assemblies" and you have to provide a redirect_url parameter in your Assembly Instructions. The form will then be submitted to Transloadit and we'll then redirect the browser to the redirect_url.

It will also append two GET parameters: assembly_id and assembly_url. The assembly_id parameter contains the unique ID of your Assembly, and the assembly_url is a Transloadit URL from which the results of the file upload can be fetched. The result is a JSON object that also contains the values of other form fields unrelated to the file upload.

When using Assembly Notifications, i.e you have provided a notify_url, we'll still send the conversion result JSON to this notify_url via a POST request.

Important We originally built this approach to avoid the need to have JavaScript enabled in the browser. Times have changed and one can now assume that JavaScript is turned on in the browser.

2.5 Advanced use conditions

The special use parameter can also be assigned an object specifying additional conditions determining which files are to be input for a given Step. The following parameters are currently supported:

Parameter Description

steps

Specifying this has the same effect as providing a string or array for the use parameter.

fields

This is an array of one or more field names (from the upload form). When this is specified, the corresponding Step will only be executed for files submitted through one of the given fields. The field names here correspond to the strings in the name attribute of the HTML file input field tag. This parameter is true by default, meaning that all fields are accepted.

Example:

{
  auth: { key: "YOUR_TRANSLOADIT_AUTH_KEY" },
  steps: {
    encode: {
      robot: "/video/encode",
      use: {
        steps: [ ":original" ],
        fields: [ "file_input_field2" ]
      },
      preset: "iphone"
    }
  }
}

2.6 Signature Authentication

Transloadit uses a very simple authentication system based on JSON and HMAC signatures. Authentication is turned off by default, and needs to be enabled to be used.

The Idea in 3 Simple Steps

You get your Auth Key and a private Auth Secret from your API Credentials and follow these Steps:

  1. You decide which Assembly Instructions you want to post to Transloadit.
  2. You add an expiration date and your Auth Key.
  3. You encrypt everything you'll send to Transloadit using your Auth Secret and save the result in a field named signature and send that as well.

And then we will happily accept your Assembly Steps as long as you POST this before the expiration date. Now into more detail.

Enabling Signature Authentication

To require that all requests against your account are signed:

  1. Go to the API Credentials page under "My Account".
  2. Enable the "Deny requests that do not include a signature or a wrong one" checkbox.
  3. Click the Update button.

Basic Usage

The typical params field for a Transloadit Template or Assembly request is usually as follows:

{
  auth: { key: '23c96d084c744219a2ce156772ec3211' },
  steps: { ... }
}

Where auth.key is the "Auth Key" from the API Credentials page.

To sign this request, the additional auth.expires field needs to be added. This field must contain a timestamp in the (near) future, after which the signature will no longer be accepted. Use "YYYY/MM/DD HH:mm:SS+00:00" as the date format, making sure that UTC is used for the timezone. For example:

{
    auth: {
      key: "2b0c45611f6440dfb64611e872ec3211",
      expires: "2009/11/27 16:53:14+00:00"
    },
    steps: { ... }
}

To calculate the signature for this request.

  1. Stringify the above JavaScript object into a JSON string.
  2. Calculate an RFC 2104-compliant HMAC hex signature on the string, with your Auth Secret as the key, and SHA1 as the hash algorithm. Implementation examples for this can be found further down in this section.
  3. Add a signature field to your post request (or as a hidden field in your form), with the signature created in step 2.

Example

Assuming that you're using the following parameters,

{
    auth: {
      expires: "2010/10/19 09:01:20+00:00",
      key: "2b0c45611f6440dfb64611e872ec3211"
    },
    steps: {
      encode: {
        use: ":original",
        robot: "/video/encode"
      }
    }
}

you should sign a JSON string such as the following.

{ auth: { expires: "2010/10/19 09:01:20+00:00", key: "2b0c45611f6440dfb64611e872ec3211"}, steps: { encode: { use: ":original", robot: "/video/encode" } } }

Given an Auth Secret of d805593620e689465d7da6b8caf2ac7384fdb7e9, the resulting signature would be:

6ec267fedfcc9e52d0467307947e31435444eb9a

And your final request would look like this:

params=%7B%22auth%22%3A%7B%22key%22%3A%222b0c45611f6440dfb64611e872ec3211%22%2C%22expires%22%3A%222010%2F10%2F19+09%3A01%3A20%2B00%3A00%22%7D%2C%22steps%22%3A%7B%22encode%22%3A%7B%22use%22%3A%22%3Aoriginal%22%2C%22robot%22%3A%22%2Fvideo%2Fencode%22%7D%7D%7D&signature=6ec267fedfcc9e52d0467307947e31435444eb9a

Calculating Signatures When Using Templates

You only have to encrypt the request parameters you send to Transloadit.

If your params include a template_id, then you do not have to calculate the signature as if all Assembly Instructions from the Template were part of the request parameters.

You only need to calculate the signature for this parameter string:

{ auth: { expires: "2010/10/19 09:01:20+00:00", key: "2b0c45611f6440dfb64611e872ec3211" }, template_id: "YOUR_TRANSLOADIT_TEMPLATE_ID" }

Signature Authentication for Notifications

If you use Notifications you may want to ensure that only Transloadit can send you data at your notify_url. When a Notification is sent to your notify_url, its POST data includes two fields: transloadit, which contains all the result data and signature which contains a signature string calculated for the contents of the transloadit field.

To verify that the POST request actually came from Transloadit you need to calculate the signature yourself for the entire body of the transloadit field of the Assembly Notification. When the signature in the signature field matches the one you calculate, the request is valid. If not, then the request was tinkered with and should be ignored!

Here is some example Node.js code to calculate the signature yourself to see that the sent signature matches:

Implementations

When you deal with JSON, please keep in mind that your language of choice might escape slashes. That is it might turn occurrences of / into \/. We calculate the signatures on our end with unescaped slashes! Please make sure to remove backslashes from your JSON before calculating the signature of it.

If you use PHP for example, please check the JSON_UNESCAPED_SLASHES option of the json_encode function.

Ruby

PHP

Node.js

Additional Authentication Options

The auth parameter can also contain the following optional keys, to restrict uploads:

Key Description

referer

A regular expression to match against the HTTP referer of this upload, such as "example\.org". Specify this key to make uploads come only from your domain.

Uploads without a referer will always pass (as they are turned off for some browsers). For details about regular expressions, see Mozilla's RegExp documentation.

max_size

The maximum size an upload can have in bytes, such as 1048576 (1 MB). Specify this to prevent users from uploading excessively large files. When using this key, make sure that it is specified as a hidden max_size form field, as setting max_size in a Template will have no effect.

The file size is checked as soon as the upload is started, and if it exceeds the maximum size, the entire upload process is canceled, even if it contains files that do not exceed the max_size limitation.

If you want to just ignore the files that exceed a certain size, but process all others, then please use our file filtering capabilities.

3. Libraries & Example Apps

3.1 Software Development Kits

3.2 Community Projects

The following is a list of projects created by community members, for community members.

Did you see something cool that others in the community can use? Please get in touch and we'll list your project here.

3.3 Example Applications

1. Image Cropping Tool

In this example application you upload an image and then select a cropping area via drag and drop. Submitting the form will crop the uploaded image via Transloadit and give the result image back to you.

You can find a live demo and the source code here.

2. Video Preview Image Chooser

In this example application you upload a video and can then select a cover image for the video from 10 thumbnails that are extracted from the video. Your choice will be resized into several formats. The uploaded video will also be encoded into several different web formats.

You can find a live demo and the source code here.