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, such as terminology, the flow of things and how to build encoding instructions. It shows you all the possibilities concerning integration 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. The Robots page 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. These pages can be used for further reference.

We recommend that you first read through the Basics section. After that, you will want to check out all the different conversion robots that are listed in Robots. That way, you can quickly make sure whether your desired features are available. The rest of our 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 SDK 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 SDK is really helpful when you want to use Transloadit with HTML forms.

  1. If you include the SDK on your HTML page, you can add Transloadit capabilities to any form. When your user submits the form, the selected files are uploaded to Transloadit.
  2. Transloadit processes the uploaded files, for example by encoding videos, resizing images, and storing the results on Amazon S3.
  3. Once processing is completed, the jQuery SDK attaches the result JSON in a hidden field called transloadit to your form. Then, the form is submitted as usual.
  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) on 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. Using Assembly Notifications is optional.

  • 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.

  • Assembly Variables

    Assembly Variables are special placeholders such as ${file.original_basename} that can be used in any Robot to influence it's encoding behavior based on the media, or form that is processed.

  • 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. That way, you can hide them from your users. You would then 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. When you have signed up, you can log into 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 this is not done correctly, browsers will not understand that this form is used to upload files.

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

Step 3: Add the jQuery SDK

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

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

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

<!-- 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 collection 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 SDK 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). Both can be found as 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 it should nevertheless give you a good idea of how things work.

Specifying Assembly Instructions in the Form

Alternatively, you could also have 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 is easier to specify them directly in the form, than to add them in the call to the jQuery SDK

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 directly in the form or in your JavaScript makes them publicly visible. That is why you will learn about Templates later on, in order to hide instructions within your Transloadit account.

In addition to this, you might have noticed that your Auth Key is also publicly visible using this integration method, potentially allowing anyone to upload files on your behalf and 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 SDK 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

Processing files lies at the heart of Transloadit. For that reason, we have crafted a simple JSON format that enables Transloadit to do just about anything with your files. 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 any way 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. These keys 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 instruct the Assembly engine itself. They control 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, without additional warning. 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 for this Step.
This parameter is mandatory
Please use the value ":original" to reference uploaded files.

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

By default, the Assembly engine passes every file individually through all Steps. 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 use a combination of several Steps 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 in this example:

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 whether 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 your convenience, 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 parameter 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 aims to process as much as possible in parallel. Steps will be executed as soon as their input Steps are available. For example, let's say you want to encode an uploaded video 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 various examples of both simple and complex Assembly Instructions.

1.5 Templates

Securing Your Assembly Instructions

Specifying Assembly Instructions directly in the params field of a form is very convenient. However, since anyone visiting your site can easily read your HTML source and find out your Assembly settings, this also has two major downsides,:

  • Embedded secrets, such as S3 and SFTP access credentials, can be seen by anyone in your HTML source!
  • Assembly replays will not work, because we obfuscate embedded secrets when the assembly is finished.

To counter these issues, we offer Templates.

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

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

Assembly replays will also work properly, because they can read the storage credentials straight from your Templates. When you only use the params, the credentials are obfuscated for security reasons and replays will not be able to decrypt them.

Templates are the absolutely recommended way of integrating Transloadit. If you are not using Templates at all, you are either prone to security issues or unable to replay failed Assemblies - or both. You should only consider not using Templates for very simple one-time file conversion jobs. For integrating Transloadit into your apps Templates should always be used!

The jQuery SDK'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 selected. There really is no good 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". You can then 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 SDK'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 received the results from Transloadit, you can save the URLs of the result files in your database.

You can find an uploads key and a results key in the response JSON, 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 longer than 24 hours, 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 will explain how you can speed things up, giving your end-users a smoother experience.

Uploading Times

We have many machines that are dedicated to receiving uploads. For redundancy purposes, we have clusters in both Europe and the United states. This also results in lower 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 maintain an overcapacity of 300% to handle traffic spikes. This ensures that we rarely have a queue. We can't rule this out completely, however, as customers could still 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 minutes for a machine to come online and we can launch up to 1500 of these in parallel.

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

Even though queues are a rare thing, especially since 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 will contact your app programmatically when the processing is done, after which you can notify your user via web / ajax / email and display the files.

If you want to use our jQuery SDK, 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 is not only the best experience for your users, but it also offers the most reliability, because it allows you to replay Assemblies (a button is available on the website's Assembly detail page) in case there was a problem.

Queues

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

2. Advanced

2.1 Dynamic Assembly Instructions

In addition to template_id, other parameters can be specified as 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.

If you want to disallow any overriding of steps, so that a browser could not modify the behavior, of a Template in any way, you can set allow_steps_override to false inside the saved Template.

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 the prefix. 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 similar to ${unique_prefix}, with the exception that two different 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-character 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 a certain 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 a certain 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 a certain file derives from. All of 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, as well a 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 in order for you to safely use it in the path parameter of your export step, like this: "path": "${file.original_path}${file.name}". This is handy if you want to import files from, for example, S3, convert them somehow and store them again on 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. Any characters other than A-Z a-z 0-9 -_. are replaced with underscores, and spaces are 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), Any characters other than A-Z a-z 0-9 -_. are replaced with underscores, and spaces are 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 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 together 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 will 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, for example, change the parameter's value to "${previous_step.name}/${unique_prefix}/${file.id}.${file.ext}", 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 SDK'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 text area named message (using the name attribute), its value could be accessed using ${fields.message} in your path parameter of the store Step, such as in the following example:

{
  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 to the instructions that are independent of a form:

{
  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"
  }
}

In the example above, variables derived from form fields take precedence over those in the fields key.

2.4 Assembly Notifications

The results of an Assembly can be sent in a POST request to a URL of your choice. This is called an Assembly Notification. It is entirely optional to use these.

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 would like to test Assembly Notifications locally, we recommend a service like localtunnel.

The Browser Notifies Your App

When choosing this approach, your visitors will have to wait for both the file uploading and the file conversions to finish.

If you use our jQuery SDK 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 assist you with integration.

Letting Transloadit Notify Your App

When choosing this approach, your visitors only wait for the file uploading to finish. They do not have 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.

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 specifically generated 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 SDK, 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 having to wait unnecessarily when files are uploaded.

The JSON that is sent to your app server will also contain a property called signature. This is the signature that is generated for the Assembly Notification. If you calculate the signature for the whole request yourself with your auth secret, you can verify whether 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 SDK or some other JavaScript integration.)

So far we have assumed that you are using the jQuery SDK (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 will then redirect the browser to the redirect_url.

We will also append two GET parameters to that URL: 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 obtained. 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 will still send the conversion result JSON to this notify_url through 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 that specifies additional conditions, which determine the files that are to be used as 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 set to 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 must be enabled if you want to make use of it.

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 that you will send to Transloadit using your Auth Secret and save the result in a field named signature. You then send that as well.

We will then happily accept your Assembly Steps as long as you POST this before the expiration date.

You can read the following sections for more detailed information about authentication.

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: { ... }
}

The auth.key in this example 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 are 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. Make sure that all quotation marks are in place and that there is no whitespace between JSON keys and values.

{"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:

5d349fc1436e2819a912554b1700a16f15b1b91e

Your final request would then 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=5d349fc1436e2819a912554b1700a16f15b1b91e

Calculating Signatures When Using Templates

You only have to encrypt the request parameters that 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 to say, 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 its signature.

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 sure that uploads only come 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, since 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 could be useful to others in the community? Please get in touch and we will 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 using 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 then have to option to 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.