Best Practices

Use Templates

Templates allow you to store Assembly Instructions on our servers so that they are encrypted at rest. You then only reference the Template by its ID in your API request to create an Assembly.

By using Templates, you do not need to worry about other people seeing your Assembly Instructions, which may include credentials for import or storage services such as Amazon S3. You should make a habit of using Templates, in order to avoid the risk of leaking sensitive information such as these credentials.

In addition, this also allows Assembly Replays. This is because if credentials end up directly in your requests instead of Templates, we'll have to obfuscate them in the Assembly Status JSON so that, should you share Assembly URLs with your customers, they cannot see the credentials.

It's possible to overrule any parameter in a Template if you want to tweak things like an image width based on a user interaction.

» Learn about Templates

Go Async if Possible

We try our best to avoid having any encoding queues. Nevertheless, they sometimes (if rarely) happen and when that does, your users will have a negative experience if, in your integration, they have to wait on processing.

Users can also be sent on their way as soon as the upload completes. When using the jQuery SDK, that means setting wait to false, and making use of Assembly Notifications. With those, your visitors will only need to wait for the file uploading to finish. They do not have wait for the subsequent file conversions to finish as well. This way, your visitors will bypass any queues, allowing them to move on as soon as the upload has finished.

When the processing is done, we ping your notify_url, and you ping your user.

Notifications are a good way to obtain file results, because they allow you to specify a URL that Transloadit will use to contact you whenever an Assembly has finished all of its encoding. You then save the results in your database, and inform the user that the results are available. We retry these notifications if your backend is unavailable, and support Signature Authentication for Notifications to secure them.

By employing Assembly Notifications, your users will never waste time staring at progress bars.

» Learn about Assembly Notifications

Check your Robot's documentation

It's easy to take inspiration from library of demos, and copy paste them to get going quickly. Sometimes however Robots come with edge cases or limitations, all known ones are documented carefully. Reading this can save you headaches or surprises later on.

Use the latest encoding stack

Our customers would get upset if we upgraded our encoding software without telling them. Often there are backwards incompatible changes and so we keep old stacks around for a long time, giving our customers the change to upgrade when they are ready for it.

This does however put a burden on the customer to every now & again try out a newer stack. We recommend checking available encoding stacks at least once a year.

We currently recommend:

  • "ffmpeg_stack": "v2.2.3"
  • "imagemagick_stack": "v1.0.0"

» Learn about Encoding Engines and our upgrade policies

Secure your Requests

When, for example, your are integrating with us in your browser using our jQuery SDK, your auth key is publicly visible. Other people can read your Auth Key just by looking at the HTML source of your website. They could then upload files to your account from their own websites and you would be billed for it.

To prevent this, please consider enabling Signature Authentication if you integrate with us through browsers or other public channels.

In addition to this, use our HTTPS endpoints ( so instructions are encrypted in transit.

» Learn more about Security and encryption in transit

Don't give us the keys to your everything

Taking a few Security paradigms to heart, we'd like as little privileges as possible to do our work. In of us exporting to your Amazon S3 bucket for instance, it's perfectly possible to create an IAM user that only has write access. We're working very hard to make this very hard, but should Transloadit ever get compromised, we would like the worst case scenario to be that a few extra files being stored in your bucket.

» Learn more about Security

Encode more files in less Assemblies

Assemblies are expensive on our platform, and to ensure performance for all, we have a Rate Limiter in place.

If possible, we recommend our customers to utilize that Assemblies can process many files. If you have a big library to import, we typically recommend processing 10,000 files per Assembly. Chunking things like this also allows you to retry a smaller chunk if you're unhappy with the results somehow.

Processing more files in less Assemblies allows you to maximize processing speeds as our Rate Limiter will happily accept your fewer Assemblies, not looking at the files inside them.

Please consider also that one ZIP file, could result in tens of thousands of files when we extracting it.

Design for failure

We strive to provide a top-notch service with no downtime and zero crashed Assemblies. While we have many years of experience in this field, running a distributed service such as Transloadit remains difficult work, problems cannot be ruled out completely. A server might crash or perform badly, resulting in some of your Assemblies to crash.

If you keep the following things in mind, crashed Assemblies can be replayed automatically by our service and neither you nor your customers would have to even notice that something went wrong. To design for failure, you should do the following:

  • *Enable automatic Assembly Replays in your account. You can do so here.
  • Always use Templates, otherwise automatic Assembly Replays will not always work properly (because we obfuscate S3 credentials, etc. that come from request parameters, which even our own system can't decipher anymore when it wants to replay an Assembly at a later stage).
  • Design with the Rate Limiter in mind. If you send us too many requests, we will rate limit them or even block your traffic entirely. You can learn about our Rate Limiters here.
  • Implement retries on your end.

Use an SDK

We recommend using official Software Development Kits. SDKs come with many of these Best Practices out of the box. They often support Signature Authentication, handling rate limits, and retries. This often means higher quality integration, and less time to market.