Transcoding Docs
Handling Uploads
Handle uploads

The /upload/handle Robot receives uploads that your users throw at you from browser or apps, or that you throw at us programmatically.
Transloadit will handle file uploads for you whether you specify this Robot or not, so using it is optional.
It can still be good to define this Robot to make your Assembly Instructions explicit though, and to configure how exactly uploads should be handled. For example, what metadata we should extract for uploaded files?
There are three constraints when using this Robot, you must:
-
not define a
use
parameter, contrary to all other Robots - only use it once in a single set of Assembly Instructions
- name the Step that it's used in:
:original
For example:
{
"steps": {
":original": {
"robot": "/upload/handle",
"output_meta": {
"has_transparency": true
}
},
"exported": {
"robot": "/s3/store",
"use": ":original",
"credentials": "YOUR_S3_CREDENTIALS"
}
}
}
Parameters
-
output_meta
object / boolean ⋅ default:{}
Allows you to specify a set of metadata that is more expensive on cpu power to calculate, and thus is disabled by default to keep your Assemblies processing fast. For images, you can add"has_transparency": true
in this object to extract if the image contains transparent parts and"dominant_colors": true
to extract an array of hexadecimal color codes from the image. You can also set this tofalse
to skip meta data extraction and speed up transcoding.
Demos featuring the /upload/handle Robot
Blog posts
We wrote the following posts about the /upload/handle Robot on our blog:
- Re-loadit: the /upload/handle Robot February 13, 2019
File Importing
Import files from Azure

The /azure/import Robot imports whole directories of files from your azure container.
Since you need to provide credentials to this Robot, please always use this together with Templates and/or Template Credentials, so that you can never leak any secrets while transmitting your Assembly Instructions.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your Azure container, account and key. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:"account"
,"key"
,"container"
. -
path
string / array of strings requiredThe path in your container to the specific file or directory. If the path points to a file, only this file will be imported. For example:js/my_javascript_file.js
If it points to a directory, then all files from this directory will be imported. For example:js/
For Transloadit to recognize you want to import all files from a directory, make sure your path ends with a/
slash. Directories are imported recursively. You can also use an array of path strings here to import multiple paths in the same Robot Step. -
next_page_token
string ⋅ default:""
A string token used for pagination. The returned files of one paginated call have the next page token inside of their meta data, which needs to be used for the subsequent paging call. -
files_per_page
integer ⋅ default:1000
The pagination page size. this only works when recursive istrue
for now in order to not break backwards compatibility in non-recursive imports. -
ignore_errors
array of strings / boolean ⋅ default:[]
Possible array members are"meta"
and"import"
. There might be an error coming up when trying to extract metadata from your imported files. This happens for files that are zero bytes big for example. Including"meta"
in the array will cause the Robot to not stop the import (and the entire Assembly) when that happens. Including"import"
in the array will ensure the Robot does not error out on any import errors either. To keep backwards compatibility, setting this parameter totrue
will set it to["meta", "import"]
internally.
Demos featuring the /azure/import Robot
Import files from Backblaze

The /backblaze/import Robot imports whole directories of files from your Backblaze bucket.
Since you need to provide credentials to this Robot, please always use this together with Templates and/or Template Credentials, so that you can never leak any secrets while transmitting your Assembly Instructions.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your Backblaze bucket, app key id app key. To create your credential information head over to Backblaze, sign in to your account, and select Create a Bucket. Save the name of your bucket, and click on the App Keys tab, scroll to the bottom of the page then select “Add a New Application Key”. Allow access to your recently created bucket, select “Read and Write” as your type of access, and tick the “Allow List All Bucket Names:” option. Now everything is in place, create your key, and take note of the information you are given so you can add input the information into your Template Credentials.Your app key will only be viewable once so make sure you note this down. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:
"bucket"
,"app_key_id"
,"app_key"
. -
path
string / array of strings requiredThe path in your bucket to the specific file or directory. If the path points to a file, only this file will be imported. For example:js/my_javascript_file.js
If it points to a directory, then all files from this directory will be imported. For example:js/
For Transloadit to recognize you want to import all files from a directory, make sure your path ends with a/
slash. Directories are not imported recursively. If you want to import files from subfolders and sub-subfolders, please do this with another Robot Step. If you want to import all files from the root directory, please use/
as the value here. In this case, make sure all your objects belong to a path. If you have objects in the root of your bucket that aren't prefixed with/
, you'll receive a 404 BACKBLAZE_IMPORT_NOT_FOUND error. You can also use an array of path strings here to import multiple paths in the same Robot Step. -
recursive
boolean ⋅ default:false
Setting this true will enable importing files from subfolders and sub-subfolders, etc. of the given path. Please use the pagination parametersstart_file_name
andfiles_per_page
wisely here. -
start_file_name
string ⋅ default:""
The name of the last file from the previous paging call to tell the Robot to ignore all files up untill this one (including this file). -
files_per_page
integer ⋅ default: 1000The pagination page size. this only works when recursive istrue
for now in order to not break backwards compatibility in non-recursive imports. -
ignore_errors
array of strings / boolean ⋅ default:[]
Possible array members are"meta"
and"import"
. There might be an error coming up when trying to extract metadata from your imported files. This happens for files that are zero bytes big for example. Including"meta"
in the array will cause the Robot to not stop the import (and the entire Assembly) when that happens. Including"import"
in the array will ensure the Robot does not error out on any import errors either. To keep backwards compatibility, setting this parameter totrue
will set it to["meta", "import"]
internally.
Demos featuring the /backblaze/import Robot
Import files from Rackspace Cloud Files

The /cloudfiles/import Robot imports whole directories of files from your Rackspace Cloud Files container.
Since you need to provide credentials to this Robot, please always use this together with Templates and/or Template Credentials, so that you can never leak any secrets while transmitting your Assembly Instructions.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your Cloud Files container, user, key, account type and data center. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:"account_type"
("us" or "uk"),"data_center"
("dfw" for Dallas or "ord" for Chicago for example),"user"
,"key"
,"container"
. -
path
string / array of strings requiredThe path in your bucket to the specific file or directory. If the path points to a file, only this file will be imported. For example:js/my_javascript_file.js
If it points to a directory, then all files from this directory will be imported. For example:js/
For Transloadit to recognize you want to import all files from a directory, make sure your path ends with a/
slash. Directories are not imported recursively. If you want to import files from subfolders and sub-subfolders, please do this with another Robot Step. You can also use an array of path strings here to import multiple paths in the same Robot Step. -
recursive
boolean ⋅ default:false
Setting this true will enable importing files from subfolders and sub-subfolders, etc. of the given path. Please use the pagination parameterspage_number
andfiles_per_page
wisely here. -
page_number
integer ⋅ default:1
The pagination page number. To not break backwards compatibility in non-recursive imports, this for now only works when recursive is totrue
. When doing big imports, make sure no files are added or removed from other scripts within your path, otherwise you might get weird results with the pagination. -
files_per_page
integer ⋅ default:1000
The pagination page size. this only works when recursive istrue
for now in order to not break backwards compatibility in non-recursive imports. -
ignore_errors
array of strings / boolean ⋅ default:[]
Possible array members are"meta"
and"import"
. There might be an error coming up when trying to extract metadata from your imported files. This happens for files that are zero bytes big for example. Including"meta"
in the array will cause the Robot to not stop the import (and the entire Assembly) when that happens. Including"import"
in the array will ensure the Robot does not error out on any import errors either. To keep backwards compatibility, setting this parameter totrue
will set it to["meta", "import"]
internally.
Demos featuring the /cloudfiles/import Robot
Import files from Digitalocean Storage

The /digitalocean/import Robot imports whole directories of files from Digitalocean Storage.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your DigitalOcean space, key, secret and region. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:"space"
,"region"
(for example:"fra1"
or"nyc3"
),"key"
,"secret"
. -
path
string / array of strings requiredThe path in your bucket to the specific file or directory. If the path points to a file, only this file will be imported. For example:js/my_javascript_file.js
If it points to a directory, then all files from this directory will be imported. For example:js/
For Transloadit to recognize you want to import all files from a directory, make sure your path ends with a/
slash. Directories are not imported recursively. If you want to import files from subfolders and sub-subfolders, please do this with another Robot Step. You can also use an array of path strings here to import multiple paths in the same Robot Step. -
recursive
boolean ⋅ default:false
Setting this true will enable importing files from subfolders and sub-subfolders, etc. of the given path. Please use the pagination parameterspage_number
andfiles_per_page
wisely here. -
page_number
integer ⋅ default:1
The pagination page number. To not break backwards compatibility in non-recursive imports, this for now only works when recursive is totrue
. When doing big imports, make sure no files are added or removed from other scripts within your path, otherwise you might get weird results with the pagination. -
files_per_page
integer ⋅ default:1000
The pagination page size. this only works when recursive istrue
for now in order to not break backwards compatibility in non-recursive imports. -
ignore_errors
array of strings / boolean ⋅ default:[]
Possible array members are"meta"
and"import"
. There might be an error coming up when trying to extract metadata from your imported files. This happens for files that are zero bytes big for example. Including"meta"
in the array will cause the Robot to not stop the import (and the entire Assembly) when that happens. Including"import"
in the array will ensure the Robot does not error out on any import errors either. To keep backwards compatibility, setting this parameter totrue
will set it to["meta", "import"]
internally.
Demos featuring the /digitalocean/import Robot
Import files from Dropbox

The /dropbox/import Robot imports whole directories of files from your Dropbox.
Since you need to provide credentials to this Robot, please always use this together with Templates and/or Template Credentials, so that you can never leak any secrets while transmitting your Assembly Instructions.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your access token. Please create your dropbox access token here. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameter instead:"access_token"
. -
path
string / array of strings requiredThe path in your dropbox to the specific file or directory. If the path points to a file, only this file will be imported. For example:js/my_javascript_file.js
If it points to a directory, then all files from this directory will be imported. For example:js/
For Transloadit to recognize you want to import all files from a directory, make sure your path ends with a/
slash. Directories are imported recursively. If you want to import all files from the root directory, please use/
as the value here. You can also use an array of path strings here to import multiple paths in the same Robot Step. -
ignore_errors
array of strings / boolean ⋅ default:[]
Possible array members are"meta"
and"import"
. There might be an error coming up when trying to extract metadata from your imported files. This happens for files that are zero bytes big for example. Including"meta"
in the array will cause the Robot to not stop the import (and the entire Assembly) when that happens. Including"import"
in the array will ensure the Robot does not error out on any import errors either. To keep backwards compatibility, setting this parameter totrue
will set it to["meta", "import"]
internally.
Demos featuring the /dropbox/import Robot
Blog posts
We wrote the following posts about the /dropbox/import Robot on our blog:
- Re-loadit: the /dropbox/import Robot January 28, 2019
Import files from FTP servers

The /ftp/import Robot imports whole libraries of files from your FTP servers into Transloadit. This Robot relies on password access. For more security, consider our /sftp/import Robot.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your FTP host, user and password. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:"host"
,"user"
,"password"
. -
path
string requiredThe path on your FTP server where to search for files. Files are imported recursively from all sub-directories and sub-sub-directories (and so on) from this path. -
port
integer ⋅ default: 21The port to use for the FTP connection. -
ignore_errors
array of strings / boolean ⋅ default:[]
Possible array members are"meta"
and"import"
. There might be an error coming up when trying to extract metadata from your imported files. This happens for files that are zero bytes big for example. Including"meta"
in the array will cause the Robot to not stop the import (and the entire Assembly) when that happens. Including"import"
in the array will ensure the Robot does not error out on any import errors either. To keep backwards compatibility, setting this parameter totrue
will set it to["meta", "import"]
internally. -
passive_mode
boolean ⋅ default:true
Determines if passive mode should be used for the FTP connection.
Things to Keep in Mind
- Your server might be unresponsive from time to time. Since (S)FTP servers are harder to scale, we see this happen a lot. As a result, if this Robot fails to store one of your files, it will retry to store the file 5 times over 15 minutes.
- This also means that when you provided the wrong credentials (when testing for example) Assemblies can take up to 15 minutes to complete.
- If an Assembly has an export Step and takes long to execute, it is almost always due to the export Step having wrong credentials or the server being unreachable.
We advise you to use our /sftp/store and /sftp/import Robots when possible, as it is much more secure. The FTP Robots should only serve as a fallback in case cloud storage or SFTP cannot be used.
Demos featuring the /ftp/import Robot
Blog posts
We wrote the following posts about the /ftp/import Robot on our blog:
- On Upgrades & Goodbyes August 8, 2014
- Introducing the new /ftp/import Robot March 6, 2014
Import files from Google Storage

The /google/import Robot imports whole directories of files from Google Storage.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredCreate a new Google service account. Set its role to "Storage Object Creator". Choose "JSON" for the key file format and download it to your computer. You will need to upload this file when creating your Template Credentials.
Go back to your Google credentials project and enable the "Google Cloud Storage JSON API" for it. Wait around ten minutes for the action to propagate through the Google network. Grab the project id from the drop down menu in the header bar on the Google site. You will also need it later on.
Now you can set up the storage.objects.create and storage.objects.delete permissions. The latter is optional and only required if you intend to overwrite existing paths.
To do this from the Google Cloud console, locate to IAM & Admin and select Roles. From here select +CREATE ROLE, enter a name, set the role launch stage as general availability and set the permissions stated above. Next relocate to your storage browser and select the ellipsis on your bucket to edit bucket permissions. From here select ADD MEMBER, enter your service account as a new member and select your newly created role.
Then create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. -
path
string / array of strings requiredThe path in your bucket to the specific file or directory. If the path points to a file, only this file will be imported. For example:js/my_javascript_file.js
If it points to a directory, then all files from this directory will be imported. For example:js/
For Transloadit to recognize you want to import all files from a directory, make sure your path ends with a/
slash. Directories are not imported recursively. If you want to import files from subfolders and sub-subfolders, please do this with another Robot Step. If you want to import all files from the root directory, please use/
as the value here. In this case, make sure all your objects belong to a path. If you have objects in the root of your bucket that aren't prefixed with/
, you'll receive a 404 GOOGLE_IMPORT_NOT_FOUND error. You can also use an array of path strings here to import multiple paths in the same Robot Step. -
recursive
boolean ⋅ default:false
Setting this true will enable importing files from subfolders and sub-subfolders, etc. of the given path. Please use the pagination parametersstart_file_name
andfiles_per_page
wisely here. -
next_page_token
string ⋅ default:""
A string token used for pagination. The returned files of one paginated call have the next page token inside of their meta data, which needs to be used for the subsequent paging call. -
files_per_page
integer ⋅ default:1000
The pagination page size. this only works when recursive istrue
for now in order to not break backwards compatibility in non-recursive imports. -
ignore_errors
array of strings / boolean ⋅ default:[]
Possible array members are"meta"
and"import"
. There might be an error coming up when trying to extract metadata from your imported files. This happens for files that are zero bytes big for example. Including"meta"
in the array will cause the Robot to not stop the import (and the entire Assembly) when that happens. Including"import"
in the array will ensure the Robot does not error out on any import errors either. To keep backwards compatibility, setting this parameter totrue
will set it to["meta", "import"]
internally.
Demos featuring the /google/import Robot
Import files from web servers

The /http/import Robot imports any file that is publicly available via a web URL into Transloadit.
The result of this Robot will carry a field import_url
in their metadata, which references the URL from which they were imported. Further conversion results that use this file will also carry this import_url
field. This allows you to to match conversion results with the original import URL that you used.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
url
string / array of strings requiredThe URL from which the file to be imported can be retrieved. You can also specify an array of URLs or a string of|
delimited URLs to import several files at once. Please also check theurl_delimiter
parameter for that. -
url_delimiter
string ⋅ default:"|"
Provides the delimiter that is used to split the URLs in yoururl
parameter value. -
headers
array of strings ⋅ default:[]
Custom headers to be sent for file import. This is an empty array by default, such that no additional headers expect the necessary ones (e.g. Host) are sent. -
force_name
string / null ⋅ default:null
Custom name for the imported file. Defaults tonull
, which means the file name is derived from the supplied URL. -
ignore_errors
array of strings / boolean ⋅ default:[]
Possible array members are"meta"
and"import"
. There might be an error coming up when trying to extract metadata from your imported files. This happens for files that are zero bytes big for example. Including"meta"
in the array will cause the Robot to not stop the import (and the entire Assembly) when that happens. Including"import"
in the array will ensure the Robot does not error out on any import errors either. To keep backwards compatibility, setting this parameter totrue
will set it to["meta", "import"]
internally.
Demos featuring the /http/import Robot
- Add an empty audio track to still video
- Add watermark to a song
- Automatically make a slideshow from recognized objects in an image
- Concatenate two audio files
- Concatenate video files
- Copy files from Webservers to Amazon S3
- Copy files from web servers to Amazon S3
- Encode a fade effect between concatenated video files.
- Generate a slideshow from a series of images
- Generate a video from an image sequence
- Import files over HTTP
- Insert an ad into a video at a specific time
- Insert cover art into an audio file
- Merge an audio and a video file
- Merge an audio file and an image to generate a video
Blog posts
We wrote the following posts about the /http/import Robot on our blog:
- Two Small Feature Updates February 11, 2012
- Adding Support for Audio Encoding November 21, 2011
Import files from min.io

The /minio/import Robot imports whole directories of files from your min.io bucket.
Since you need to provide credentials to this Robot, please always use this together with Templates and/or Template Credentials, so that you can never leak any secrets while transmitting your Assembly Instructions.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your minio bucket, key, secret and bucket region. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:"bucket"
,"host"
,"key"
,"secret"
. -
path
string / array of strings requiredThe path in your bucket to the specific file or directory. If the path points to a file, only this file will be imported. For example:js/my_javascript_file.js
If it points to a directory, then all files from this directory will be imported. For example:js/
For Transloadit to recognize you want to import all files from a directory, make sure your path ends with a/
slash. Directories are not imported recursively. If you want to import files from subfolders and sub-subfolders, please do this with another Robot Step. If you want to import all files from the root directory, please use/
as the value here. In this case, make sure all your objects belong to a path. If you have objects in the root of your bucket that aren't prefixed with/
, you'll receive an error:A client error (NoSuchKey) occurred when calling the GetObject operation: The specified key does not exist.
You can also use an array of path strings here to import multiple paths in the same Robot Step. -
recursive
boolean ⋅ default:false
Setting this true will enable importing files from subfolders and sub-subfolders, etc. of the given path. Please use the pagination parameterspage_number
andfiles_per_page
wisely here. -
page_number
integer ⋅ default:1
The pagination page number. To not break backwards compatibility in non-recursive imports, this for now only works when recursive is totrue
. When doing big imports, make sure no files are added or removed from other scripts within your path, otherwise you might get weird results with the pagination. -
files_per_page
integer ⋅ default:1000
The pagination page size. this only works when recursive istrue
for now in order to not break backwards compatibility in non-recursive imports. -
ignore_errors
array of strings / boolean ⋅ default:[]
Possible array members are"meta"
and"import"
. There might be an error coming up when trying to extract metadata from your imported files. This happens for files that are zero bytes big for example. Including"meta"
in the array will cause the Robot to not stop the import (and the entire Assembly) when that happens. Including"import"
in the array will ensure the Robot does not error out on any import errors either. To keep backwards compatibility, setting this parameter totrue
will set it to["meta", "import"]
internally.
Demos featuring the /minio/import Robot
Import files from Amazon S3

The /s3/import Robot imports whole directories of files from your S3 bucket.
Since you need to provide credentials to this Robot, please always use this together with Templates and/or Template Credentials, so that you can never leak any secrets while transmitting your Assembly Instructions.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your S3 bucket, key, secret and bucket region. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:"bucket"
,"bucket_region"
(for example:"us-east-1"
or"eu-west-2"
),"key"
,"secret"
. -
path
string / array of strings requiredThe path in your bucket to the specific file or directory. If the path points to a file, only this file will be imported. For example:js/my_javascript_file.js
If it points to a directory, then all files from this directory will be imported. For example:js/
For Transloadit to recognize you want to import all files from a directory, make sure your path ends with a/
slash. Directories are not imported recursively. If you want to import files from subfolders and sub-subfolders, please do this with another Robot Step. If you want to import all files from the root directory, please use/
as the value here. In this case, make sure all your objects belong to a path. If you have objects in the root of your bucket that aren't prefixed with/
, you'll receive an error:A client error (NoSuchKey) occurred when calling the GetObject operation: The specified key does not exist.
You can also use an array of path strings here to import multiple paths in the same Robot Step. -
recursive
boolean ⋅ default:false
Setting this true will enable importing files from subfolders and sub-subfolders, etc. of the given path. Please use the pagination parameterspage_number
andfiles_per_page
wisely here. -
page_number
integer ⋅ default:1
The pagination page number. To not break backwards compatibility in non-recursive imports, this for now only works when recursive is totrue
. When doing big imports, make sure no files are added or removed from other scripts within your path, otherwise you might get weird results with the pagination. -
files_per_page
integer ⋅ default:1000
The pagination page size. this only works when recursive istrue
for now in order to not break backwards compatibility in non-recursive imports. -
ignore_errors
array of strings / boolean ⋅ default:[]
Possible array members are"meta"
and"import"
. There might be an error coming up when trying to extract metadata from your imported files. This happens for files that are zero bytes big for example. Including"meta"
in the array will cause the Robot to not stop the import (and the entire Assembly) when that happens. Including"import"
in the array will ensure the Robot does not error out on any import errors either. To keep backwards compatibility, setting this parameter totrue
will set it to["meta", "import"]
internally.
Demos featuring the /s3/import Robot
- Copy files from Amazon S3 to Backblaze
- Copy files from Amazon S3 to DigitalOcean Spaces
- Copy files from Amazon S3 to Dropbox
- Copy files from Amazon S3 to FTP servers
- Copy files from Amazon S3 to Google Storage
- Copy files from Amazon S3 to Microsoft Azure
- Copy files from Amazon S3 to Openstack Swift
- Copy files from Amazon S3 to Rackspace Cloud Files
- Copy files from Amazon S3 to SFTP servers
- Copy files from Amazon S3 to Vimeo
- Copy files from Amazon S3 to Wasabi
- Copy files from Amazon S3 to YouTube
- Copy files from Amazon S3 to min.io
- Import a specific file from S3
- Import an entire folder of files from S3
- Resize all images in an S3 bucket
Blog posts
We wrote the following posts about the /s3/import Robot on our blog:
- Kicking Transloadit Into Gear for the New Year February 1, 2015
- Introducing the new /s3/import Robot July 17, 2013
Import files from SFTP servers

The /sftp/import Robot imports whole libraries of files from your SFTP servers into Transloadit. This Robot relies on public key authentication.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your SFTP host, user and optional custom public key. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:"host"
,"port"
,"user"
,"public_key"
(optional). -
path
string requiredThe path on your SFTP server where to search for files. -
ignore_errors
array of strings / boolean ⋅ default:[]
Possible array members are"meta"
and"import"
. There might be an error coming up when trying to extract metadata from your imported files. This happens for files that are zero bytes big for example. Including"meta"
in the array will cause the Robot to not stop the import (and the entire Assembly) when that happens. Including"import"
in the array will ensure the Robot does not error out on any import errors either. To keep backwards compatibility, setting this parameter totrue
will set it to["meta", "import"]
internally. -
port
integer ⋅ default:22
The port to use for the connection.
Things to Keep in Mind
- Your server might be unresponsive from time to time. Since (S)FTP servers are harder to scale, we see this happen a lot. As a result, if this Robot fails to store one of your files, it will retry to store the file 5 times over 15 minutes.
- This also means that when you provided the wrong credentials (when testing for example) Assemblies can take up to 15 minutes to complete.
- If an Assembly has an export Step and takes long to execute, it is almost always due to the export Step having wrong credentials or the server being unreachable.
This robot uses SSH keys, which offer more security at the trade-off of a moderate degree of complexity in setting up. If you prefer a less secure, but easier-to-setup solution, then please have a look at our /ftp/store and /ftp/import Robots.
Installation on Your Server
The method explained here is slightly more elaborate than handing out an SSH account with an authorized public key, but is more secure as the user will not be able to traverse outside their home directory. This way, even if the user account is compromised at some point, the accessible data would be recently uploaded files.
The following explains how to create a dedicated user and group for Transloadit, and restrict access as shown in this article.
First, let's create a dedicated group and user:
# Change these variables to suit your needs.
# For additional security, use a randomly picked username.
TL_USER="random873"
TL_PUBLIC_PATH="uploads"
groupadd sftponly
useradd -g sftponly -m ${TL_USER}
# This line sets a random 20-character password for the user.
# We work with keys, but this is required because some operating systems will
# consider the account locked without one.
echo "${TL_USER}:$(cat /dev/urandom | tr -dc _A-Z-a-z-0-9 | head -c20)" |chpasswd
mkdir -p /home/${TL_USER}/.ssh /home/${TL_USER}/${TL_PUBLIC_PATH}
echo "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA57GdwNLqsWz03X8MBEe4KoMSY2HOURjnUUe9zeTivASI+BLEe3cZcuJjsEBaRpISvCH04hosWUI0H4BQeB1dZZUUW1s4ttnVohCD9CfNiXJ7pwJAvgWb01dTW4YUWFKUTpTeUwQzgcNVLDtSVaQOYh4lAKvCZEcz17X9iZ7AeSEuQKe+QsrcwQoBdSpQ6FnzKwSZsggK81dPiGIW9Cw2z/EZWJpl9QBTYhw25NbNRtZj3fXVbrejnQQ985eZ6TlrvQFpUVwyk0QNHDsN+7zVISM3eXNpxof+vJyQNDLN9tb8vNPf/HXuw7MDJWMphrQevF5V26aMzszl3ZeO1779Mw== sftp@transloadit.com" >> /home/${TL_USER}/.ssh/authorized_keys
chown -R ${TL_USER}.sftponly /home/${TL_USER}
chown root.root /home/${TL_USER}
chmod -R 600 /home/${TL_USER}/.ssh /home/${TL_USER}/${TL_PUBLIC_PATH}
chmod -R u+X /home/${TL_USER}/.ssh /home/${TL_USER}/${TL_PUBLIC_PATH}
Make sure to change ${TL_USER}
and ${TL_PUBLIC_PATH}
to suit your needs. Remember to use a random username for additional security.
Please also give the subfolder where you intend to store your files sufficient permissions for your user to be able create sub-directories via mkdir
.
A combination of chown
and chmod
should achieve this.
Next, we will set up SSH to cage SFTP users in their home directory, and deny them regular shell access.
Enter ${EDITOR} /etc/ssh/sshd_config
, and then find and comment out this line:
# Subsystem sftp /usr/lib/openssh/sftp-server
At the bottom of the same file, add the following:
Subsystem sftp internal-sftp
Match group sftponly
ChrootDirectory /home/%u
X11Forwarding no
AllowTcpForwarding no
ForceCommand internal-sftp
Finally, enter /etc/init.d/ssh restart
to reflect the changes made.
Demos featuring the /sftp/import Robot
Blog posts
We wrote the following posts about the /sftp/import Robot on our blog:
- A Happy 2014 from Transloadit! January 14, 2014
- Introducing Our New /sftp/import Robot October 30, 2012
Import files from Openstack/Swift

The /swift/import Robot imports whole directories of files from your Openstack/Swift bucket.
Since you need to provide credentials to this Robot, please always use this together with Templates and/or Template Credentials, so that you can never leak any secrets while transmitting your Assembly Instructions.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your swift bucket, key, secret and bucket region. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:"bucket"
,"host"
,"key"
,"secret"
. -
path
string / array of strings requiredThe path in your bucket to the specific file or directory. If the path points to a file, only this file will be imported. For example:js/my_javascript_file.js
If it points to a directory, then all files from this directory will be imported. For example:js/
For Transloadit to recognize you want to import all files from a directory, make sure your path ends with a/
slash. Directories are not imported recursively. If you want to import files from subfolders and sub-subfolders, please do this with another Robot Step. If you want to import all files from the root directory, please use/
as the value here. In this case, make sure all your objects belong to a path. If you have objects in the root of your bucket that aren't prefixed with/
, you'll receive an error:A client error (NoSuchKey) occurred when calling the GetObject operation: The specified key does not exist.
You can also use an array of path strings here to import multiple paths in the same Robot Step. -
recursive
boolean ⋅ default:false
Setting this true will enable importing files from subfolders and sub-subfolders, etc. of the given path. Please use the pagination parameterspage_number
andfiles_per_page
wisely here. -
page_number
integer ⋅ default:1
The pagination page number. To not break backwards compatibility in non-recursive imports, this for now only works when recursive is totrue
. When doing big imports, make sure no files are added or removed from other scripts within your path, otherwise you might get weird results with the pagination. -
files_per_page
integer ⋅ default:1000
The pagination page size. this only works when recursive istrue
for now in order to not break backwards compatibility in non-recursive imports. -
ignore_errors
array of strings / boolean ⋅ default:[]
Possible array members are"meta"
and"import"
. There might be an error coming up when trying to extract metadata from your imported files. This happens for files that are zero bytes big for example. Including"meta"
in the array will cause the Robot to not stop the import (and the entire Assembly) when that happens. Including"import"
in the array will ensure the Robot does not error out on any import errors either. To keep backwards compatibility, setting this parameter totrue
will set it to["meta", "import"]
internally.
Demos featuring the /swift/import Robot
Import files from Wasabi

The /wasabi/import Robot imports whole directories of files from your wasabi bucket.
Since you need to provide credentials to this Robot, please always use this together with Templates and/or Template Credentials, so that you can never leak any secrets while transmitting your Assembly Instructions.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your wasabi bucket, key, secret and bucket region. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:"bucket"
,"host"
,"key"
,"secret"
. -
path
string / array of strings requiredThe path in your bucket to the specific file or directory. If the path points to a file, only this file will be imported. For example:js/my_javascript_file.js
If it points to a directory, then all files from this directory will be imported. For example:js/
For Transloadit to recognize you want to import all files from a directory, make sure your path ends with a/
slash. Directories are not imported recursively. If you want to import files from subfolders and sub-subfolders, please do this with another Robot Step. If you want to import all files from the root directory, please use/
as the value here. In this case, make sure all your objects belong to a path. If you have objects in the root of your bucket that aren't prefixed with/
, you'll receive an error:A client error (NoSuchKey) occurred when calling the GetObject operation: The specified key does not exist.
You can also use an array of path strings here to import multiple paths in the same Robot Step. -
recursive
boolean ⋅ default:false
Setting this true will enable importing files from subfolders and sub-subfolders, etc. of the given path. Please use the pagination parameterspage_number
andfiles_per_page
wisely here. -
page_number
integer ⋅ default:1
The pagination page number. To not break backwards compatibility in non-recursive imports, this for now only works when recursive is totrue
. When doing big imports, make sure no files are added or removed from other scripts within your path, otherwise you might get weird results with the pagination. -
files_per_page
integer ⋅ default:1000
The pagination page size. this only works when recursive istrue
for now in order to not break backwards compatibility in non-recursive imports. -
ignore_errors
array of strings / boolean ⋅ default:[]
Possible array members are"meta"
and"import"
. There might be an error coming up when trying to extract metadata from your imported files. This happens for files that are zero bytes big for example. Including"meta"
in the array will cause the Robot to not stop the import (and the entire Assembly) when that happens. Including"import"
in the array will ensure the Robot does not error out on any import errors either. To keep backwards compatibility, setting this parameter totrue
will set it to["meta", "import"]
internally.
Demos featuring the /wasabi/import Robot
Video Encoding
Convert videos to HLS and MPEG-Dash

The /video/adaptive Robot encodes videos into HTTP Live Streaming (HLS) and MPEG-Dash supported formats and generates the necessary manifest and playlist files.
The /video/adaptive Robot generates the necessary manifest and playlist files based on a set of used video and audio files to make implementing HTTP Live Streaming (HLS) and MPEG-Dash streaming easy.
This Robot accepts all types of video files and audio files. Do not forget to use Step bundling in your use
parameter
to make the Robot work on several input files at once.
We have implemented video and audio encoding presets specifically for MPEG-Dash and HTTP Live Streaming support.
These presets are prefixed with "dash"
and "hls"
.
We deem this Robot ready for production, but since it hasn't seen a lot of such traffic yet, it's still labeled as beta.
Required CORS settings for MPEG-Dash
Playing back MPEG-Dash Manifest files requires CORS definitions on your Amazon S3 Bucket or other storage location. For convenience here you can find a working CORS definition:
<CORSConfiguration>
<CORSRule>
<AllowedOrigin>*</AllowedOrigin>
<AllowedMethod>GET</AllowedMethod>
<ExposeHeader>Access-Control-Allow-Origin</ExposeHeader>
<AllowedHeader>*</AllowedHeader>
</CORSRule>
</CORSConfiguration>
To set up CORS for your S3 bucket:
- Visit: https://s3.console.aws.amazon.com/s3/buckets/
- Click on your bucket
- Click "Permissions"
- Click "CORS configuration"
Required CORS settings for HTTP Live Streaming
Playing back HLS playlist files may require a crossdomain policy file. For convenience here you can find a working file.
Please save this to a crossdomain.xml
file and store it in the root folder of your Amazon S3 Bucket or other storage location of choice.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cross-domain-policy SYSTEM "https://www.macromedia.com/xml/dtds/cross-domain-policy.dtd">
<cross-domain-policy>
<allow-access-from domain="*" secure="false" />
<allow-http-request-headers-from domain="*" headers="*" />
</cross-domain-policy>
Storing Segments and Playlist files
The Robot gives its result files (segments, initialization segments, MPD manifest files and M3U8 playlist files) the right metadata property relative_path
, so that you can store them easily using one of our storage Robots.
In the path
parameter of the storage Robot of your choice, please use the Assembly Variable ${file.meta.relative_path}
to store files in the proper paths to make the playlist files work.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
technique
string ⋅ default:"dash"
Determines which streaming technique should be used. Currently supports"dash"
for MPEG-Dash and"hls"
for HTTP Live Streaming. -
playlist_name
string ⋅ default:"playlist.mpd"
The filename for the generated manifest/playlist file. The default is"playlist.mpd"
if yourtechnique
is"dash"
, and"playlist.m3u8"
if yourtechnique
is"hls"
. -
segment_duration
integer ⋅ default:10
The duration for each segment in seconds. -
closed_captions
boolean ⋅ default:true
Determines whether you want closed caption support when using the"hls"
technique.
FFmpeg Parameters
-
ffmpeg_stack
string ⋅ default:"v3.3.3"
Selects the FFmpeg stack version to use for encoding. These versions do not reflect any real FFmpeg versions, they reflect our own internal (non-semantic) versioning for our custom FFmpeg builds. The current recommendation is to use"v3.3.3"
Other valid values can be found here.
Demos featuring the /video/adaptive Robot
- Implement HTTP Live Streaming (HLS)
- Implement MPEG-Dash using Transloadit
- Make video compatible for all devices
Blog posts
We wrote the following posts about the /video/adaptive Robot on our blog:
- Adding support for MPEG-Dash October 11, 2016
- Helping Coursera Bring Education to Millions Around the World February 11, 2015
Concatenate videos

The /video/concat Robot concatenates several videos together.
Important All videos you concatenate must have the same dimensions (width and height) and the same streams (audio and video streams) otherwise you will run into errors! If your videos do not have the desired dimensions when passing them to the /video/concat Robot, please encode them first with our /video/encode Robot.
It is possible to concatenate a virtually infinite number of video files using the /video/concat Robot.
Imagine you have three file input fields in the same upload form for video files that you want to concatenate. You can tell Transloadit in which order it should concatenate them using the file input field's name
attribute. Just use the value for the name attribute as the value for the fields
key in the JSON. Then set the proper order values in the as
parameter. Valid values here are video_[[index]]
. Transloadit will then concatenate them in the order of the index ascending:
"concatenated": {
"robot": "/video/concat",
"preset": "ipad-high",
"use": {
"steps": [
{ "name": ":original", "fields": "first_video_file", "as": "video_1" },
{ "name": ":original", "fields": "second_video_file", "as": "video_2" },
{ "name": ":original", "fields": "third_video_file", "as": "video_3" }
]
}
}
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
preset
string ⋅ default:"flash"
Performs conversion using pre-configured settings. If you specify your own FFmpeg parameters using the Robot'sffmpeg
parameter and you have not specified a preset, then the default"flash"
preset is not applied. This is to prevent you from having to override each of the flash preset's values manually. For a list of video presets, see video presets. -
video_fade_seconds
float ⋅ default:1.0
When used this adds a video fade in and out effect between each section of your concatenated video. The float value is used so if you want a video delay effect of 500 milliseconds between each video section you would select 0.5, however, integer values can also be represented. This parameter does not add a video fade effect at the beginning or end of your video. If you want to do so, create an additional /video/encode step and use ourffmpeg
parameter as shown in this demo. Please note this parameter is independent of adding audio fades between sections. -
audio_fade_seconds
float ⋅ default:1.0
When used this adds an audio fade in and out effect between each section of your concatenated video. The float value is used so if you want an audio delay effect of 500 milliseconds between each video section you would select 0.5, however, integer values can also be represented. This parameter does not add an audio fade effect at the beginning or end of your video. If you want to do so, create an additional /video/encode step and use ourffmpeg
parameter as shown in this demo. Please note this parameter is independent of adding video fades between sections.
FFmpeg Parameters
-
ffmpeg_stack
string ⋅ default:"v3.3.3"
Selects the FFmpeg stack version to use for encoding. These versions do not reflect any real FFmpeg versions, they reflect our own internal (non-semantic) versioning for our custom FFmpeg builds. The current recommendation is to use"v3.3.3"
Other valid values can be found here. -
ffmpeg
object ⋅ default:{}
A parameter object to be passed to FFmpeg. If a preset is used, the options specified are merged on top of the ones from the preset. For available options, see the FFmpeg documentation. Options specified here take precedence over the preset options.
Demos featuring the /video/concat Robot
- Concatenate video files
- Encode a fade effect between concatenated video files.
- Insert an ad into a video at a specific time
- Join multiple videos sharing one audio track
Blog posts
We wrote the following posts about the /video/concat Robot on our blog:
- Happy 2016 from Transloadit December 31, 2015
- Adding Four New Robots to Our Family! September 24, 2015
- Upgrading Encoding Engines July 31, 2015
Transcode, resize, or watermark videos

The /video/encode Robot encodes, resizes, applies watermarks to videos and animated GIFs.
On Watermarking
With watermarking you can add an image to a video. This is usually used for logos, but you could also Surround a video with a frame if you cut out a transparent center from your image.
Supplying the Watermark via an Assembly Step
You can also also pass both the video and the watermark image to an Assembly Step via the use
parameter, allowing you to have both be part of the upload, or to use the results of other Assembly Steps as input to your /video/encode Step.
For this to work, you just need to use the as
-syntax:
"my_video_step": {
"bundle_steps": true,
"robot": "/video/encode",
"use": {
"steps": [
{ "name": ":original", "as": "video" },
{ "name": ":original", "as": "watermark" }
]
}
}
Here both the video and the watermark image are taken from the uploaded files. They are recognized automatically based on their file type.
If you use several file input fields, then you can tell Transloadit which field supplies the base video and which the watermark. Suppose you have two file input fields named the_video
and the_watermark
. These Assembly Instructions will make it work using the fields
condition:
"my_video_step": {
"bundle_steps": true,
"robot": "/video/encode",
"use": {
"steps": [
{ "name": ":original", "fields": "the_video", "as": "video" },
{ "name": ":original", "fields": "the_watermark", "as": "watermark" }
]
}
}
Please note that the Robot's watermark_url
parameter will still continue to work.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
preset
string ⋅ default:"flash"
Converts a video according to pre-configured settings. If you specify your own FFmpeg parameters using the Robot's and/or do not not want Transloadit to set any encoding setting, startingffmpeg_stack: "v3.3.3"
, you can use the value'empty'
here. -
width
integer(1
-1920
) ⋅ default: Width of the input videoWidth of the new video, in pixels. -
height
integer(1
-1080
) ⋅ default: Height of the input videoHeight of the new video, in pixels. -
resize_strategy
string ⋅ default:"pad"
See the available resize strategies. -
zoom
boolean ⋅ default:true
If this is set tofalse
, smaller videos will not be stretched to the desired width and height. For details about the impact of zooming for your preferred resize strategy, see the list of available resize strategies. -
crop
object / json string ⋅ default:null
Specify an object containing coordinates for the top left and bottom right corners of the rectangle to be cropped from the original video(s). Values can be integers for absolute pixel values or strings for percentage based values. For example:
will crop the area from{ "x1": 80, "y1": 100, "x2": "60%", "y2": "80%" }
(80, 100)
to(600, 800)
from a 1000x1000 pixels video, which is a square whose width is 520px and height is 700px. Ifcrop
is set, the width and height parameters are ignored, and theresize_strategy
is set tocrop
automatically. You can also use a JSON string of such an object with coordinates in similar fashion:"{ \"x1\": <Integer>, \"y1\": <Integer>, \"x2\": <Integer>, \"y2\": <Integer> }"
-
background
string ⋅ default:"00000000"
The background color of the resulting video the "rrggbbaa" format (red, green, blue, alpha) when used with the"pad"
resize strategy. The default color is black. -
rotate
integer ⋅ default: AutoForces the video to be rotated by the specified degree integer. Currently, only multiples of 90 are supported. We automatically correct the orientation of many videos when the orientation is provided by the camera. This option is only useful for videos requiring rotation because it was not detected by the camera. If you setrotate
tofalse
no rotation is performed, even if the metadata contains such instructions. -
hint
boolean ⋅ default:false
Enables hinting for mp4 files, for RTP/RTSP streaming. -
turbo
boolean ⋅ default:false
Splits the video into multiple chunks so that each chunk can be encoded in parallel before all encoded chunks are stitched back together to form the result video. This comes at the expense of extra Priority Job Slots and may prove to be counter-productive for very small video files. -
chunk_duration
integer ⋅ default: AutoAllows you to specify the duration of each chunk whenturbo
is set totrue
. This means you can take advantage of that feature while using fewer Priority Job Slots. For instance, the longer each chunk is, the fewer Encoding Jobs will need to be used.
FFmpeg Parameters
-
ffmpeg_stack
string ⋅ default:"v3.3.3"
Selects the FFmpeg stack version to use for encoding. These versions do not reflect any real FFmpeg versions, they reflect our own internal (non-semantic) versioning for our custom FFmpeg builds. The current recommendation is to use"v3.3.3"
Other valid values can be found here. -
ffmpeg
object ⋅ default:{}
A parameter object to be passed to FFmpeg. For available options, see the FFmpeg documentation. If a preset is used, the options specified are merged on top of the ones from the preset. The FFmpegr
parameter (framerate) has a default value of25
and maximum value of60
. If you setr
tonull
, you clear the default of25
and can preserve the original video's framerate. For example:"steps": { "video_encode": { "robot": "/video/encode", "use": ":original", "ffmpeg_stack": "v3.3.3", "preset": "iphone-high", "ffmpeg": { "b": "600k" } } }
Watermarking Parameters
-
watermark_url
string ⋅ default:""
A URL indicating a PNG image to be overlaid above this image. Please note that you can also supply the watermark via another Assembly Step. -
watermark_position
string / array of strings ⋅ default:"center"
The position at which the watermark is placed. The available options are"center"
,"top"
,"bottom"
,"left"
, and"right"
. You can also combine options, such as"bottom-right"
. An array of possible values can also be specified, in which case one value will be selected at random, such as[ "center", "left", "bottom-left", "bottom-right" ]
. This setting puts the watermark in the specified corner. To use a specific pixel offset for the watermark, you will need to add the padding to the image itself. -
watermark_x_offset
integer ⋅ default:0
The x-offset in number of pixels at which the watermark will be placed in relation to the position it has due towatermark_position
. Values can be both positive and negative and yield different results depending on thewatermark_position
parameter. Positive values move the watermark closer to the image's center point, whereas negative values move the watermark further away from the image's center point. -
watermark_y_offset
integer ⋅ default:0
The y-offset in number of pixels at which the watermark will be placed in relation to the position it has due towatermark_position
. Values can be both positive and negative and yield different results depending on thewatermark_position
parameter. Positive values move the watermark closer to the image's center point, whereas negative values move the watermark further away from the image's center point. -
watermark_size
string ⋅ default:""
The size of the watermark, as a percentage, such as"50%"
. How the watermark is resized greatly depends on thewatermark_resize_strategy
. -
watermark_resize_strategy
string ⋅ default:"fit"
Available values are"fit"
,"stretch"
and"area"
. To explain how the resize strategies work, let's assume our target video size is 800×800 pixels and our watermark image is 400×300 pixels. Let's also assume, thewatermark_size
parameter is set to"25%"
. For the"fit"
resize strategy, the watermark is scaled so that the longer side of the watermark takes up 25% of the corresponding video side. And the other side is scaled according to the aspect ratio of the watermark image. So with our watermark, the width is the longer side, and 25% of the video size would be 200px. Hence, the watermark would be resized to 200×150 pixels. If thewatermark_size
was set to"50%"
", it would be resized to 400×300 pixels (so just left at its original size). For the"stretch"
resize strategy, the watermark image is stretched (meaning, it is resized without keeping its aspect ratio in mind) so that both sides take up 25% of the corresponding video side. Since our video is 800×800 pixels, for a watermark size of 25% the watermark would be resized to 200×200 pixels. Its height would appear stretched, because keeping the aspect ratio in mind it would be resized to 200×150 pixels instead. For the"area"
resize strategy, the watermark is resized (keeping its aspect ratio in check) so that it covers"xx%"
of the video's surface area. The value fromwatermark_size
is used for the percentage area size. -
watermark_start_time
float ⋅ default:0.0
The delay in seconds from the start of the video for the watermark to appear. By default the watermark is immediately shown. -
watermark_duration
float ⋅ default:-1.0
The duration in seconds for the watermark to be shown. Can be used together withwatermark_start_time
to create nice effects. The default value is-1.0
, which means that the watermark is shown for the entire duration of the video. -
watermark_opacity
float ⋅ default:1.0
The opacity of the watermark. Valid values are between0
(invisible) and1.0
(full visibility).
HLS Parameters
This Robot used to support HLS parameters, but we now recommend using our specialized /video/adaptive Robot instead.
Demos featuring the /video/encode Robot
- Apply a watermark to videos
- Automatically decompress uploaded archives
- Automatically filter files to separate encoding steps
- Automatically process multiple file types
- Concatenate video files
- Crop a video to fit a LinkedIn feed post
- Encode a fade effect between concatenated video files.
- Encode a video into WebM
- Encode a video, extract 8 thumbnails and store everything in an S3 bucket
- Encode blur-out effect into video file
- Encode video for Android
- Encode video for Android, preserving the original quality
- Encode video for Apple iPhone 11 Pro Max
- Encode video for browsers in 720p
- Encode video for iPhone and strip the sound
- Encode video to HEVC
- Export a video to YouTube
- Extract 10 thumbnails and modify their size
- Extract a 10 second clip from a video
- Extract audio from video files
- Insert an ad into a video at a specific time
- Join multiple videos sharing one audio track
- Optimize videos for iPad
- Overlay videos with dynamic artwork, generated with HTML & JS
- Reject videos that do not have an audio track
- Segment video files and create a playlist
- Specify multiple encoding Steps for a single file
- Surround a video with a frame using a watermark
Blog posts
We wrote the following posts about the /video/encode Robot on our blog:
- The importance of a watermark: new watermark parameters February 20, 2019
- Adding support for MPEG-Dash October 11, 2016
- Happy 2016 from Transloadit December 31, 2015
- Upgrading Encoding Engines July 31, 2015
- Helping Coursera Bring Education to Millions Around the World February 11, 2015
- Adding Support for Audio Encoding November 21, 2011
- We Have Added Support for WebM April 27, 2011
- Real-Time Encoding - Over 150x Faster December 20, 2010
- Auto Rotation for iPhone Videos November 19, 2010
Merge video, audio, images into one video

The /video/merge Robot composes a new video by adding an audio track to existing still image(s) or video.
This Robot is able to generate a video from:
- an image and an audio file
- a video and an audio file
- several images
Merging an Audio File and an Image
To merge an audio file and an image to create a video please pass both the audio file and the image to an Assembly Step via the use
parameter. For this to work, you just need to use the as-syntax:
"merged": {
"robot": "/video/merge",
"preset": "ipad-high",
"use": {
"steps": [
{ "name": ":original", "as": "audio" },
{ "name": ":original", "as": "image" }
],
"bundle_steps": true
}
}
Imagine you have uploaded both an image and an audio file in the same upload form. In the above example the system will automatically recognize the files properly if you use the same Step name twice (":original"
in this case). Instead of using :original
you could also use any other valid Assembly Step name.
If you are using multiple file input fields, then you can tell Transloadit which field supplies the audio file and which supplies the image. Suppose you have two file input fields named the_image
and the_audio
. These Assembly Instructions will make it work:
"merged": {
"robot": "/video/merge",
"preset": "ipad-high",
"use": {
"steps": [
{ "name": ":original", "fields": "the_audio", "as": "audio" },
{ "name": ":original", "fields": "the_image", "as": "image" }
],
"bundle_steps": true
}
}
Merging an Audio File and a Video
If you have a video file (without sound for example) and an audio track that you want the video to use you can merge them together with Transloadit. Just label the video as video
and the audio file as audio
using the as
key in the JSON.
Imagine you have two file input fields in the same upload form - one to upload a video file and one for an audio file. You can tell Transloadit which field supplies the video and which the audio file using the file input field's name
attribute. Just use the value for the name attribute as the value for the fields
key in the JSON:
"merged": {
"robot": "/video/merge",
"preset": "ipad-high",
"use": {
"steps": [
{ "name": ":original", "fields": "the_video", "as": "video" },
{ "name": ":original", "fields": "the_audio", "as": "audio" }
],
"bundle_steps": true
}
}
You can also supply the video and audio file using other Assembly Steps of course and leave out the fields
attribute.
Important When merging audio and video files, it's recommended to set target a format & codecs via a preset
or via ffmpeg.codec:v
, ffmpeg.codec:a
and ffmpeg.f
. If not, merging will default to backwards compatible, but non-desirable legacy codecs.
Merging Several Images to Generate a Video
It is possible to create a video from images with Transloadit. Just label all images as image
using the as
key in the JSON:
"merged": {
"robot": "/video/merge",
"preset": "ipad-high",
"use": {
"steps": [
{ "name": ":original", "as": "image" }
],
"bundle_steps": true
},
"framerate": "1/10",
"duration": 8.5
}
This will work fine in a multi-file upload context. Files are sorted by their basename. So if you name them 01.jpeg
and 02.jpeg
, they will be merged in the correct order.
You can also supply your images using other Assembly Steps of course, results from /image/resize Steps for example.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
preset
string ⋅ default:"flash"
Generates the video according to pre-configured video presets. If you specify your own FFmpeg parameters using the Robot'sffmpeg
parameter and you have not specified a preset, then the default"flash"
preset is not applied. This is to prevent you from having to override each of the flash preset's values manually. -
width
integer(1
-1920
) ⋅ default: Width of the input imageWidth of the generated video, in pixels. -
height
integer(1
-1080
) ⋅ default: Height of the input imageHeight of the generated video, in pixels. -
resize_strategy
string ⋅ default:"pad"
If the given width/height parameters are bigger than the input image's dimensions, then theresize_strategy
determines how the image will be resized to match the provided width/height. See the available resize strategies. -
background
string ⋅ default:"00000000"
The background color of the resulting video the "rrggbbaa" format (red, green, blue, alpha) when used with the"pad"
resize strategy. The default color is black. -
framerate
string ⋅ default:"1/5"
When merging images to generate a video this is the input framerate. A value of "1/5" means each image is given 5 seconds before the next frame appears (the inverse of a framerate of "5"). Likewise for "1/10", "1/20", etc. A value of "5" means there are 5 frames per second. -
duration
float ⋅ default:5.0
When merging images to generate a video or when merging audio and video this is the desired target duration in seconds. The float value can take one decimal digit. If you want all images to be displayed exactly once, then you can set the duration according to this formula:duration = numberOfImages / framerate
. This also works for the inverse framerate values like1/5
. If you set this value tonull
, then the duration of the input audio file will be used. -
audio_delay
float ⋅ default:0.0
When merging a video and an audio file, and when merging images and an audio file to generate a video, this is the desired delay in seconds for the audio file to start playing. Imagine you merge a video file without sound and an audio file, but you wish the audio to start playing after 5 seconds and not immediately, then this is the parameter to use.
FFmpeg Parameters
-
ffmpeg_stack
string ⋅ default:"v3.3.3"
Selects the FFmpeg stack version to use for encoding. These versions do not reflect any real FFmpeg versions, they reflect our own internal (non-semantic) versioning for our custom FFmpeg builds. The current recommendation is to use"v3.3.3"
Other valid values can be found here. -
ffmpeg
object ⋅ default:{}
A parameter object to be passed to FFmpeg. For available options, see the FFmpeg documentation. If a preset is used, the options specified are merged on top of the ones from the preset.
Demos featuring the /video/merge Robot
- Add an audio track to video footage
- Add an empty audio track to still video
- Automatically make a slideshow from recognized objects in an image
- Convert any video to animated GIF
- Generate a slideshow from a series of images
- Generate a video from an image sequence
- Join multiple videos sharing one audio track
- Merge an audio and a video file
- Merge an audio file and an image to generate a video
- Merge an audio file with a video file, keeping the shortest input stream duration intact
Blog posts
We wrote the following posts about the /video/merge Robot on our blog:
- Tutorial: Using /video/merge to develop video slideshows June 14, 2019
- Happy 2016 from Transloadit December 31, 2015
- Upgrading Encoding Engines July 31, 2015
- Kicking Transloadit Into Gear for the New Year February 1, 2015
- On Upgrades & Goodbyes August 8, 2014
- A Happy 2014 from Transloadit! January 14, 2014
- Merging Image and Audio Files to Create Videos August 7, 2013
Add subtitles to videos

The /video/subtitle Robot adds subtitles to videos.
This Robot supports both SRT and VTT subtitle files.
Imagine you have two file input fields in the same upload form - one for a video file and one for an SRT or VTT subtitle file. They are named input_video
and input_srt
(with the HTML name
attribute). This is how you would go about adding the SRT subtitles into the video with Transloadit:
"subtitled": {
"robot": "/video/subtitle",
"preset": "ipad-high",
"use": {
"steps": [
{ "name": ":original", "fields": "input_video", "as": "video" },
{ "name": ":original", "fields": "input_srt", "as": "subtitles" }
]
}
}
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
preset
string ⋅ default:"empty"
Performs conversion using pre-configured settings. By default, no settings are applied and the original settings of the video are preserved. For a list of video presets, see video presets.
FFmpeg Parameters
-
ffmpeg_stack
string ⋅ default:"v3.3.3"
Selects the FFmpeg stack version to use for encoding. These versions do not reflect any real FFmpeg versions, they reflect our own internal (non-semantic) versioning for our custom FFmpeg builds. The current recommendation is to use"v3.3.3"
Other valid values can be found here. -
ffmpeg
object ⋅ default:{}
A parameter object to be passed to FFmpeg. If a preset is used, the options specified are merged on top of the ones from the preset. For available options, see the FFmpeg documentation. Options specified here take precedence over the preset options.
Demos featuring the /video/subtitle Robot
Blog posts
We wrote the following posts about the /video/subtitle Robot on our blog:
- An introduction to the Subtitle Robot December 6, 2018
Extract thumbnails from videos

The /video/thumbs Robot extracts any number of images from videos for use as previews.
Note Even though thumbnails are extracted from videos in parallel, we sort the thumbnails before adding them to the Assembly results. So the order in which they appear there reflects the order in which they appear in the video. You can also make sure by checking the thumb_index
meta key.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
count
integer(1
-999
) ⋅ default:8
The number of thumbnails to be extracted. As some videos have incorrect durations, the actual number of thumbnails generated may be less in rare cases. The maximum number of thumbnails we currently allow is 999. -
offsets
array of integers / array of strings ⋅ default:[]
An array of offsets representing seconds of the file duration, such as[ 2, 45, 120 ]
. Millisecond durations of a file can also be used by using decimal place values. For example, an offset from 1250 milliseconds would be represented with1.25
. Offsets can also be percentage values such as[ "2%", "50%", "75%" ]
. This option cannot be used with thecount
parameter, and takes precedence if both are specified. Out-of-range offsets are silently ignored. -
format
string ⋅ default:"jpeg"
The format of the extracted thumbnail. Supported values are"jpg"
,"jpeg"
and"png"
. Even if you specify the format to be"jpeg"
the resulting thumbnails will have a"jpg"
file extension. -
width
integer(1
-1920
) ⋅ default: Width of the videoThe width of the thumbnail, in pixels. -
height
integer(1
-1080
) ⋅ default: Height of the videoThe height of the thumbnail, in pixels. -
resize_strategy
string ⋅ default:"pad"
One of the available resize strategies. -
background
string ⋅ default:"00000000"
The background color of the resulting thumbnails in the "rrggbbaa" format (red, green, blue, alpha) when used with the"pad"
resize strategy. The default color is black. -
rotate
integer ⋅ default: AutoForces the video to be rotated by the specified degree integer. Currently, only multiples of 90 are supported. We automatically correct the orientation of many videos when the orientation is provided by the camera. This option is only useful for videos requiring rotation because it was not detected by the camera.
FFmpeg Parameters
-
ffmpeg_stack
string ⋅ default:"v3.3.3"
Selects the FFmpeg stack version to use for encoding. These versions do not reflect any real FFmpeg versions, they reflect our own internal (non-semantic) versioning for our custom FFmpeg builds. The current recommendation is to use"v3.3.3"
Other valid values can be found here.
Demos featuring the /video/thumbs Robot
- Automatically process multiple file types
- Convert any video to animated GIF
- Encode a video, extract 8 thumbnails and store everything in an S3 bucket
- Encode video for browsers in 720p
- Extract 10 thumbnails and modify their size
- Make video compatible for all devices
- Save your results to Dropbox
- Specify multiple encoding Steps for a single file
- Use Google Cloud Storage to store your results from Transloadit
Blog posts
We wrote the following posts about the /video/thumbs Robot on our blog:
- Upgrading Encoding Engines July 31, 2015
- Kicking Transloadit Into Gear for the New Year February 1, 2015
Video Encoding Presets
These are supported if you were to specify ffmpeg_stack: "v3.3.3"
in your Assembly Instructions.
The recommended version is: v3.3.3
Name | Format | Audio codec | Audio bitrate | Audio frequency | Video codec | Video bitrate | Video resolution |
---|---|---|---|---|---|---|---|
android-high
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
700000
|
480x320
|
android-low
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
96000
|
480x320
|
android
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
512000
|
480x320
|
dash-1080p-video
|
mp4
|
|
|
|
libx264
|
7500000
|
1920x1080
|
dash-270p-video
|
mp4
|
|
|
|
libx264
|
460000
|
480x270
|
dash-360p-video
|
mp4
|
|
|
|
libx264
|
800000
|
640x360
|
dash-480p-video
|
mp4
|
|
|
|
libx264
|
1300000
|
854x480
|
dash-540p-video
|
mp4
|
|
|
|
libx264
|
1850000
|
960x540
|
dash-576p-video
|
mp4
|
|
|
|
libx264
|
2100000
|
1024x576
|
dash-720p-video
|
mp4
|
|
|
|
libx264
|
3300000
|
1280x720
|
flash
|
flv
|
libmp3lame
|
64000
|
44100
|
flv
|
512000
|
320x240
|
hevc
|
mp4
|
libfdk_aac
|
128k
|
44100
|
libx265
|
1200000
|
|
hls-1080p
|
mp4
|
libfdk_aac
|
256000
|
44100
|
libx264
|
7500000
|
1920x1080
|
hls-270p
|
mp4
|
libfdk_aac
|
32000
|
44100
|
libx264
|
550000
|
480x270
|
hls-360p
|
mp4
|
libfdk_aac
|
64000
|
44100
|
libx264
|
1000000
|
640x360
|
hls-480p
|
mp4
|
libfdk_aac
|
64000
|
44100
|
libx264
|
1300000
|
854x480
|
hls-540p
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
1600000
|
960x540
|
hls-576p
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
2100000
|
1024x576
|
hls-720p
|
mp4
|
libfdk_aac
|
192000
|
44100
|
libx264
|
4000000
|
1280x720
|
ipad-high
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
1200000
|
1024x768
|
ipad-low
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
512000
|
1024x768
|
ipad
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
700000
|
1024x768
|
iphone-high
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
700000
|
480x320
|
iphone-low
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
96000
|
480x320
|
iphone
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
512000
|
480x320
|
ogv
|
ogg
|
libvorbis
|
128000
|
48000
|
libtheora
|
700000
|
|
webm-1080p
|
webm
|
libvorbis
|
256000
|
48000
|
libvpx
|
7500000
|
1920x1080
|
webm-270p
|
webm
|
libvorbis
|
64000
|
48000
|
libvpx
|
460000
|
480x270
|
webm-360p
|
webm
|
libvorbis
|
64000
|
48000
|
libvpx
|
800000
|
640x360
|
webm-480p
|
webm
|
libvorbis
|
64000
|
48000
|
libvpx
|
1400000
|
854x480
|
webm-540p
|
webm
|
libvorbis
|
128000
|
48000
|
libvpx
|
1850000
|
960x540
|
webm-576p
|
webm
|
libvorbis
|
128000
|
48000
|
libvpx
|
2100000
|
1024x576
|
webm-720p
|
webm
|
libvorbis
|
192000
|
48000
|
libvpx
|
3300000
|
1280x720
|
webm
|
webm
|
libvorbis
|
128000
|
48000
|
libvpx
|
700000
|
|
wmv
|
asf
|
wmav2
|
|
|
wmv2
|
|
|
You can override any preset's setting, such as a file's bitrate, or even the file's format & codecs via
a Robot's ffmpeg
parameter.
The hls-
and dash-
presets are intended for use
in combination with our /video/adaptive Robot.
These are supported if you were to specify ffmpeg_stack: "v4.2.1"
in your Assembly Instructions.
The recommended version is: v3.3.3
Name | Format | Audio codec | Audio bitrate | Audio frequency | Video codec | Video bitrate | Video resolution |
---|---|---|---|---|---|---|---|
android-high
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
700000
|
480x320
|
android-low
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
96000
|
480x320
|
android
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
512000
|
480x320
|
dash-1080p-video
|
mp4
|
|
|
|
libx264
|
7500000
|
1920x1080
|
dash-270p-video
|
mp4
|
|
|
|
libx264
|
460000
|
480x270
|
dash-360p-video
|
mp4
|
|
|
|
libx264
|
800000
|
640x360
|
dash-480p-video
|
mp4
|
|
|
|
libx264
|
1300000
|
854x480
|
dash-540p-video
|
mp4
|
|
|
|
libx264
|
1850000
|
960x540
|
dash-576p-video
|
mp4
|
|
|
|
libx264
|
2100000
|
1024x576
|
dash-720p-video
|
mp4
|
|
|
|
libx264
|
3300000
|
1280x720
|
flash
|
flv
|
libmp3lame
|
64000
|
44100
|
flv
|
512000
|
320x240
|
hevc
|
mp4
|
libfdk_aac
|
128k
|
44100
|
libx265
|
1200000
|
|
hls-1080p
|
mp4
|
libfdk_aac
|
256000
|
44100
|
libx264
|
7500000
|
1920x1080
|
hls-270p
|
mp4
|
libfdk_aac
|
32000
|
44100
|
libx264
|
550000
|
480x270
|
hls-360p
|
mp4
|
libfdk_aac
|
64000
|
44100
|
libx264
|
1000000
|
640x360
|
hls-480p
|
mp4
|
libfdk_aac
|
64000
|
44100
|
libx264
|
1300000
|
854x480
|
hls-540p
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
1600000
|
960x540
|
hls-576p
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
2100000
|
1024x576
|
hls-720p
|
mp4
|
libfdk_aac
|
192000
|
44100
|
libx264
|
4000000
|
1280x720
|
ipad-high
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
1200000
|
1024x768
|
ipad-low
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
512000
|
1024x768
|
ipad
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
700000
|
1024x768
|
iphone-high
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
700000
|
480x320
|
iphone-low
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
96000
|
480x320
|
iphone
|
mp4
|
libfdk_aac
|
128000
|
44100
|
libx264
|
512000
|
480x320
|
ogv
|
ogg
|
libvorbis
|
128000
|
48000
|
libtheora
|
700000
|
|
webm-1080p
|
webm
|
libvorbis
|
256000
|
48000
|
libvpx
|
7500000
|
1920x1080
|
webm-270p
|
webm
|
libvorbis
|
64000
|
48000
|
libvpx
|
460000
|
480x270
|
webm-360p
|
webm
|
libvorbis
|
64000
|
48000
|
libvpx
|
800000
|
640x360
|
webm-480p
|
webm
|
libvorbis
|
64000
|
48000
|
libvpx
|
1400000
|
854x480
|
webm-540p
|
webm
|
libvorbis
|
128000
|
48000
|
libvpx
|
1850000
|
960x540
|
webm-576p
|
webm
|
libvorbis
|
128000
|
48000
|
libvpx
|
2100000
|
1024x576
|
webm-720p
|
webm
|
libvorbis
|
192000
|
48000
|
libvpx
|
3300000
|
1280x720
|
webm
|
webm
|
libvorbis
|
128000
|
48000
|
libvpx
|
700000
|
|
wmv
|
asf
|
wmav2
|
|
|
wmv2
|
|
|
You can override any preset's setting, such as a file's bitrate, or even the file's format & codecs via
a Robot's ffmpeg
parameter.
The hls-
and dash-
presets are intended for use
in combination with our /video/adaptive Robot.
Audio Encoding
Extract or insert audio artwork

The /audio/artwork Robot extracts the embedded cover artwork from audio files and allows you to pipe it into other Steps, for example into /image/resize Steps. It can also insert images into audio files as cover artwork.
For extraction this Robot uses the image format with which the cover was encoded into the audio file - most of the time this should be jpg
.
If you need the image in a different format, please pipe the result of this Robot into the /image/resize Robot.
The method
parameter determines whether to extract or insert.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
method
string ⋅ default:"extract"
What should be done with the audio file. A value of"extract"
means audio artwork will be extract. A value of"insert"
means the provided image will be inserted as audio artwork.
FFmpeg Parameters
-
ffmpeg_stack
string ⋅ default:"v3.3.3"
Selects the FFmpeg stack version to use for encoding. These versions do not reflect any real FFmpeg versions, they reflect our own internal (non-semantic) versioning for our custom FFmpeg builds. The current recommendation is to use"v3.3.3"
Other valid values can be found here.
Demos featuring the /audio/artwork Robot
Blog posts
We wrote the following posts about the /audio/artwork Robot on our blog:
- Adding support for audio artwork insertion March 10, 2016
- On Upgrades & Goodbyes August 8, 2014
- Releasing our new /audio/artwork Robot June 20, 2014
Concatenate audio

The /audio/concat Robot concatenates several audio files together.
It is possible to concatenate a virtually infinite number of audio files using the /audio/concat Robot.
Imagine you have three file input fields in the same upload form for audio files that you want to concatenate. You can tell Transloadit in which order it should concatenate them using the file input field's name
attribute. Just use the value for the name attribute as the value for the fields
key in the JSON. Then set the proper order in the as
parameter. Valid values here are audio_[[index]]
. Transloadit will then concatenate them in the order of the index ascending:
"concatenated": {
"robot": "/audio/concat",
"preset": "mp3",
"use": {
"steps": [
{ "name": ":original", "fields": "first_audio_file", "as": "audio_1" },
{ "name": ":original", "fields": "second_audio_file", "as": "audio_2" },
{ "name": ":original", "fields": "third_audio_file", "as": "audio_3" }
]
}
}
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
preset
string ⋅ default:"mp3"
Performs conversion using pre-configured settings. If you specify your own FFmpeg parameters using the Robot'sffmpeg
parameter and you have not specified a preset, then the defaultmp3
preset is not applied. This is to prevent you from having to override each of the MP3 preset's values manually. For a list of audio presets, see audio presets. -
bitrate
integer ⋅ default: AutoBit rate of the resulting audio file, in bits per second. If not specified will default to the bit rate of the input audio file -
sample_rate
integer ⋅ default: AutoSample rate of the resulting audio file, in Hertz. If not specified will default to the sample rate of the input audio file -
audio_fade_seconds
float ⋅ default:1.0
When used this adds an audio fade in and out effect between each section of your concatenated audio file. The float value is used so if you want an audio delay effect of 500 milliseconds between each video section you would select 0.5, however, integer values can also be represented. This parameter does not add an audio fade effect at the beginning or end of your result audio file. If you want to do so, create an additional /audio/encode step and use ourffmpeg
parameter as shown in this demo.
FFmpeg Parameters
-
ffmpeg_stack
string ⋅ default:"v3.3.3"
Selects the FFmpeg stack version to use for encoding. These versions do not reflect any real FFmpeg versions, they reflect our own internal (non-semantic) versioning for our custom FFmpeg builds. The current recommendation is to use"v3.3.3"
Other valid values can be found here. -
ffmpeg
object ⋅ default:{}
A parameter object to be passed to FFmpeg. If a preset is used, the options specified are merged on top of the ones from the preset. For available options, see the FFmpeg documentation. Options specified here take precedence over the preset options.
Demos featuring the /audio/concat Robot
Blog posts
We wrote the following posts about the /audio/concat Robot on our blog:
- Happy 2016 from Transloadit December 31, 2015
- Adding Four New Robots to Our Family! September 24, 2015
- Upgrading Encoding Engines July 31, 2015
Encode audio

The /audio/encode Robot converts audio files into all kinds of formats for you. We provide encoding presets for the most common formats.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
preset
string ⋅ default:"mp3"
Performs conversion using pre-configured settings. If you specify your own FFmpeg parameters using the Robot'sffmpeg
parameter and you have not specified a preset, then the defaultmp3
preset is not applied. This is to prevent you from having to override each of themp3
preset's values manually. For a list of audio presets, see audio presets. -
bitrate
integer ⋅ default: AutoBit rate of the resulting audio file, in bits per second. If not specified will default to the bit rate of the input audio file -
sample_rate
integer ⋅ default: AutoSample rate of the resulting audio file, in Hertz. If not specified will default to the sample rate of the input audio file
FFmpeg Parameters
-
ffmpeg_stack
string ⋅ default:"v3.3.3"
Selects the FFmpeg stack version to use for encoding. These versions do not reflect any real FFmpeg versions, they reflect our own internal (non-semantic) versioning for our custom FFmpeg builds. The current recommendation is to use"v3.3.3"
Other valid values can be found here. -
ffmpeg
object ⋅ default:{}
A parameter object to be passed to FFmpeg. If a preset is used, the options specified are merged on top of the ones from the preset. For available options, see the FFmpeg documentation. Options specified here take precedence over the preset options.
HLS Parameters
This Robot used to support HLS parameters, but we now recommend using our specialized /video/adaptive Robot instead.
Demos featuring the /audio/encode Robot
- Downmix multiple audio channels into one
- Encode to OGG with custom FFmpeg parameters
- Encoding with a specific bit rate
- Extract a 10 second clip from audio
- Fade in and out audio file
- Fade-in and out multiple times within the same audio file
- High-quality FLAC encoding
- High-quality MP3 encoding
- Loudness Normalization
- Reverse audio track
Blog posts
We wrote the following posts about the /audio/encode Robot on our blog:
- How Transloadit helps to keep the records spinning at Promo Push November 17, 2016
- Adding support for MPEG-Dash October 11, 2016
- Upgrading Encoding Engines July 31, 2015
- Helping Coursera Bring Education to Millions Around the World February 11, 2015
- Adding Support for Audio Encoding November 21, 2011
Loop audio

The /audio/loop Robot loops one audio file as often as is required to match a given duration.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
preset
string ⋅ default:"mp3"
Performs conversion using pre-configured settings. If you specify your own FFmpeg parameters using the Robot'sffmpeg
parameter and you have not specified a preset, then the defaultmp3
preset is not applied. This is to prevent you from having to override each of themp3
preset's values manually. For a list of audio presets, see audio presets. -
bitrate
integer ⋅ default: AutoBit rate of the resulting audio file, in bits per second. If not specified will default to the bit rate of the input audio file -
sample_rate
integer ⋅ default: AutoSample rate of the resulting audio file, in Hertz. If not specified will default to the sample rate of the input audio file -
duration
float ⋅ default:60.0
Target duration for the whole process in seconds. The Robot will loop the input audio file for as long as this target duration is not reached yet.
FFmpeg Parameters
-
ffmpeg_stack
string ⋅ default:"v3.3.3"
Selects the FFmpeg stack version to use for encoding. These versions do not reflect any real FFmpeg versions, they reflect our own internal (non-semantic) versioning for our custom FFmpeg builds. The current recommendation is to use"v3.3.3"
Other valid values can be found here. -
ffmpeg
object ⋅ default:{}
A parameter object to be passed to FFmpeg. If a preset is used, the options specified are merged on top of the ones from the preset. For available options, see the FFmpeg documentation. Options specified here take precedence over the preset options.
Demos featuring the /audio/loop Robot
Blog posts
We wrote the following posts about the /audio/loop Robot on our blog:
- Happy 2016 from Transloadit December 31, 2015
- Adding Four New Robots to Our Family! September 24, 2015
Merge audio files into one

The /audio/merge Robot overlays several audio files on top of each other.
It is possible to merge a virtually infinite number of audio files using the /audio/merge Robot.
Imagine you have three file input fields in the same upload form for audio files that you want to merge. You can tell Transloadit to merge them using the file input field's name
attribute. Just use the value for the name attribute as the value for the fields
key in the JSON and audio
as the as
parameter:
"merged": {
"robot": "/audio/merge",
"preset": "mp3",
"use": {
"steps": [
{ "name": ":original", "fields": "first_audio_file", "as": "audio" },
{ "name": ":original", "fields": "second_audio_file", "as": "audio" },
{ "name": ":original", "fields": "third_audio_file", "as": "audio" }
]
}
}
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
preset
string ⋅ default:"mp3"
Performs conversion using pre-configured settings. If you specify your own FFmpeg parameters using the Robot'sffmpeg
parameter and you have not specified a preset, then the default "mp3" preset is not applied. This is to prevent you from having to override each of the mp3 preset's values manually. For a list of audio presets, see audio presets. -
bitrate
integer ⋅ default: AutoBit rate of the resulting audio file, in bits per second. If not specified will default to the bit rate of the input audio file -
sample_rate
integer ⋅ default: AutoSample rate of the resulting audio file, in Hertz. If not specified will default to the sample rate of the input audio file -
duration
string ⋅ default:"longest"
Duration of the output file compared to the duration of all merged audio files. Can be"first"
(duration of the first input file),"shortest"
(duration of the shortest audio file) or"longest"
for the duration of the longest input file. -
loop
boolean ⋅ default:false
Specifies if any input files that do not match the target duration should be looped to match it. Useful for audio merging where your overlay file is typically much shorter than the main audio file. -
volume
string ⋅ default:"average"
Valid values are"average"
and"sum"
here."average"
means each input is scaled 1/n (n is the number of inputs) or"sum"
which means each individual audio stays on the same volume, but since we merge tracks 'on top' of eachother, this could result in very loud output.
FFmpeg Parameters
-
ffmpeg_stack
string ⋅ default:"v3.3.3"
Selects the FFmpeg stack version to use for encoding. These versions do not reflect any real FFmpeg versions, they reflect our own internal (non-semantic) versioning for our custom FFmpeg builds. The current recommendation is to use"v3.3.3"
Other valid values can be found here. -
ffmpeg
object ⋅ default:{}
A parameter object to be passed to FFmpeg. If a preset is used, the options specified are merged on top of the ones from the preset. For available options, see the FFmpeg documentation. Options specified here take precedence over the preset options.
Demos featuring the /audio/merge Robot
Blog posts
We wrote the following posts about the /audio/merge Robot on our blog:
- Happy 2016 from Transloadit December 31, 2015
- Adding Four New Robots to Our Family! September 24, 2015
Generate waveform images from audio

The /audio/waveform Robot generates waveform images for your audio files and allows you to change their colors and dimensions.
We recommend that you use an /audio/encode Step prior to your waveform Step to convert audio files to MP3. This way it is guaranteed that the /audio/waveform Robot accepts your audio file and you can also down-sample large audio files and save some money.
Similarly, if you need the output image in a different format, please pipe the result of this Robot into the /image/resize Robot.
Here is an example waveform image:
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
format
string ⋅ default:"image"
The format of the result file. Can be"image"
or"json"
. -
width
integer ⋅ default:256
The width of the resulting image if the format"image"
was selected. -
height
integer ⋅ default:64
The height of the resulting image if the format"image"
was selected. -
background_color
string ⋅ default:"00000000"
The background color of the resulting image in the "rrggbbaa" format (red, green, blue, alpha), if the format"image"
was selected. -
center_color
string ⋅ default:"000000ff"
The color used in the center of the gradient. The format is "rrggbbaa" (red, green, blue, alpha). -
outer_color
string ⋅ default:"000000ff"
The color used in the outer parts of the gradient. The format is "rrggbbaa" (red, green, blue, alpha).
Demos featuring the /audio/waveform Robot
Blog posts
We wrote the following posts about the /audio/waveform Robot on our blog:
- Kicking Transloadit Into Gear for the New Year February 1, 2015
- Adding Support for Waveform Images November 22, 2012
Audio Encoding Presets
These are supported if you were to specify ffmpeg_stack: "v3.3.3"
in your Assembly Instructions.
The recommended version is: v3.3.3
Name | Format | Audio codec | Audio bitrate | Audio frequency | Video codec | Video bitrate | Video resolution |
---|---|---|---|---|---|---|---|
aac
|
mp4
|
libfdk_aac
|
128000
|
44100
|
|
|
|
alac
|
ipod
|
alac
|
128000
|
44100
|
|
|
|
dash-128k-audio
|
mp4
|
|
128000
|
44100
|
|
|
|
dash-256k-audio
|
mp4
|
|
256000
|
44100
|
|
|
|
dash-32k-audio
|
mp4
|
|
32000
|
44100
|
|
|
|
dash-64k-audio
|
mp4
|
|
64000
|
44100
|
|
|
|
empty
|
|
|
|
|
|
|
|
flac
|
flac
|
|
128000
|
44100
|
|
|
|
gif
|
gif
|
|
|
|
|
|
480x270
|
mp3
|
mp3
|
libmp3lame
|
128000
|
44100
|
|
|
|
ogg
|
ogg
|
libvorbis
|
|
|
|
|
|
opus
|
ogg
|
|
128000
|
48000
|
|
|
|
speech
|
wav
|
|
|
16000
|
|
|
|
wav
|
wav
|
pcm_s16le
|
|
|
|
|
|
You can override any preset's setting, such as a file's bitrate, or even the file's format & codecs via
a Robot's ffmpeg
parameter.
The hls-
and dash-
presets are intended for use
in combination with our /video/adaptive Robot.
These are supported if you were to specify ffmpeg_stack: "v4.2.1"
in your Assembly Instructions.
The recommended version is: v3.3.3
Name | Format | Audio codec | Audio bitrate | Audio frequency | Video codec | Video bitrate | Video resolution |
---|---|---|---|---|---|---|---|
aac
|
mp4
|
libfdk_aac
|
128000
|
44100
|
|
|
|
alac
|
ipod
|
alac
|
128000
|
44100
|
|
|
|
dash-128k-audio
|
mp4
|
|
128000
|
44100
|
|
|
|
dash-256k-audio
|
mp4
|
|
256000
|
44100
|
|
|
|
dash-32k-audio
|
mp4
|
|
32000
|
44100
|
|
|
|
dash-64k-audio
|
mp4
|
|
64000
|
44100
|
|
|
|
empty
|
|
|
|
|
|
|
|
flac
|
flac
|
|
128000
|
44100
|
|
|
|
gif
|
gif
|
|
|
|
|
|
480x270
|
mp3
|
mp3
|
libmp3lame
|
128000
|
44100
|
|
|
|
ogg
|
ogg
|
libvorbis
|
|
|
|
|
|
opus
|
ogg
|
|
128000
|
48000
|
|
|
|
speech
|
wav
|
|
|
16000
|
|
|
|
wav
|
wav
|
pcm_s16le
|
|
|
|
|
|
You can override any preset's setting, such as a file's bitrate, or even the file's format & codecs via
a Robot's ffmpeg
parameter.
The hls-
and dash-
presets are intended for use
in combination with our /video/adaptive Robot.
Image Manipulation
Optimize images without quality loss

The /image/optimize Robot reduces the size of images while maintaining the same visual quality.
With this Robot it's possible to reduce the file size of your JPEG, PNG, GIF, WEBP and SVG images by up to 80% for big images and 65% for small to medium sized ones - while keeping their original quality!
This Robot enables you to lower your storage and bandwidth costs, and improves your user experience and monetization by reducing the load time of image-intensive web pages.
It works well together with the /image/resize Robot to bring the full power of resized and optimized images to your website or app.
Important This Robot accepts all image types and will just pass on unsupported image types unoptimized. Hence, there is no need to set up /file/filter Robot workflows for this.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
priority
string ⋅ default:compression-ratio
Provides different algorithms for better or worse compression for your images, but that run slower or faster. Valid values are"compression-ratio"
and"conversion-speed"
. The value"conversion-speed"
will result in an average compression ratio of 18%."compression-ratio"
will result in an average compression ratio of 31%. -
progressive
boolean ⋅ default:false
Interlaces the image if set totrue
, which makes the result image load progressively in browsers. Instead of rendering the image from top to bottom, the browser will first show a low-res blurry version of the image which is then quickly replaced with the actual image as the data arrives. This greatly increases the user experience, but comes at a loss of about 10% of the file size reduction. -
preserve_meta_data
boolean ⋅ default:true
Specifies if the image's metadata should be preserved during the optimization, or not. If it is not preserved, the file size is even further reduced. But be aware that this could strip a photographer's copyright information, which for obvious reasons can be frowned upon. -
fix_breaking_images
boolean ⋅ default:true
If set totrue
this parameter tries to fix images that would otherwise make the underlying tool error out and thereby break your Assemblies. This can sometimes result in a larger file size, though.
Demos featuring the /image/optimize Robot
- Crop a picture to fit the background dimensions of the Apple iPhone 11 Pro Max while keeping the file size low
- Import your Dropbox files to Transloadit for encoding
- Only resize larger images when resizing files
- Reduce image file sizes by up to 80% without quality loss
Blog posts
We wrote the following posts about the /image/optimize Robot on our blog:
- Happy 2016 from Transloadit December 31, 2015
- Image optimization improvements November 24, 2015
- On Upgrades & Goodbyes August 8, 2014
- Better PNG Optimization July 29, 2014
- A Happy 2014 from Transloadit! January 14, 2014
- Adding Support for Lossless Image Optimization June 6, 2013
Convert, resize, or watermark images

The /image/resize Robot resizes, crops, changes colorization, rotation, and applies text and watermarks to images.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
output_meta
object / boolean ⋅ default:{}
Allows you to specify a set of metadata that is more expensive on cpu power to calculate, and thus is disabled by default to keep your Assemblies processing fast. For images, you can add"has_transparency": true
in this object to extract if the image contains transparent parts and"dominant_colors": true
to extract an array of hexadecimal color codes from the image. You can also set this tofalse
to skip meta data extraction and speed up transcoding. -
format
string ⋅ default: nullThe output format for the modified image. Some of the most important available formats are"jpg"
,"png"
,"gif"
, and"tiff"
. For a complete lists of all formats that we can write to please check our supported image formats list. Ifnull
(default), then the input image's format will be used as the output format. If you wish to convert to"pdf"
, please consider the /document/convert Robot instead. -
width
integer(1
-5000
) ⋅ default: AutoWidth of the new image, in pixels. If not specified, will default to the width of the input image. -
height
integer(1
-5000
) ⋅ default: AutoHeight of the new image, in pixels. If not specified, will default to the height of the input image. -
resize_strategy
string ⋅ default:"fit"
See the list of available resize strategies. -
zoom
boolean ⋅ default:true
If this is set tofalse
, smaller images will not be stretched to the desired width and height. For details about the impact of zooming for your preferred resize strategy, see the list of available resize strategies. -
crop
object / json string ⋅ default:null
Specify an object containing coordinates for the top left and bottom right corners of the rectangle to be cropped from the original image(s). Values can be integers for absolute pixel values or strings for percentage based values. For example:
will crop the area from{ "x1": 80, "y1": 100, "x2": "60%", "y2": "80%" }
(80, 100)
to(600, 800)
from a 1000x1000 pixels image, which is a square whose width is 520px and height is 700px. Ifcrop
is set, the width and height parameters are ignored, and theresize_strategy
is set tocrop
automatically. You can also use a JSON string of such an object with coordinates in similar fashion:"{ \"x1\": <Integer>, \"y1\": <Integer>, \"x2\": <Integer>, \"y2\": <Integer> }"
To crop around human faces, see our /image/facedetect Robot. -
gravity
string ⋅ default:center
The direction from which the image is to be cropped, when"resize_strategy"
is set to"crop"
, but no crop coordinates are defined. The available options are"center"
,"top"
,"bottom"
,"left"
, and"right"
. You can also combine options with a hyphen, such as"bottom-right"
. -
strip
boolean ⋅ default:false
Strips all metadata from the image. This is useful to keep thumbnails as small as possible. -
alpha
string ⋅ default:""
Gives control of the alpha/matte channel of an image. Valid options are"Activate"
,"Background"
,"Copy"
,"Deactivate"
,"Extract"
,"Off"
,"On"
,"Opaque"
,"Remove"
,"Set"
,"Shape"
,"Transparent"
-
preclip_alpha
string ⋅ default:""
Gives control of the alpha/matte channel of an image before applying the clipping path viaclip: true
. Valid options are"Activate"
,"Background"
,"Copy"
,"Deactivate"
,"Extract"
,"Off"
,"On"
,"Opaque"
,"Remove"
,"Set"
,"Shape"
,"Transparent"
-
flatten
boolean ⋅ default:true
Flattens all layers onto the specified background to achieve better results from transparent formats to non-transparent formats, as explained in the ImageMagick documentation. To preserve animations, GIF files are not flattened when this is set totrue
. To flatten GIF animations, use theframe
parameter. -
correct_gamma
boolean ⋅ default:false
Prevents gamma errors common in many image scaling algorithms. -
quality
integer(1
-100
) ⋅ default: AutoControls the image compression for JPG and PNG images. Please also take a look at our /image/optimize Robot.
Before:
Quality92
applied:
Quality40
applied:
If this parameter is not specified it will default to the quality of the input image, or92
-
background
string ⋅ default:"#FFFFFF"
-
frame
integer / null ⋅ default:null
Use this parameter when dealing with animated GIF files to specify which frame of the GIF is used for the operation. Specify1
to use the first frame,2
to use the second, and so on.null
means all frames. -
colorspace
string ⋅ default:""
Sets the image colorspace. For details about the available values, see the ImageMagick documentation. Please note that if you were using"RGB"
, we recommend using"sRGB"
instead as of 2014-02-04. ImageMagick might try to find the most efficientcolorspace
based on the color of an image, and default to e.g."Gray"
. To force colors, you might then have to use this parameter in combination withtype
"TrueColor"
-
type
string ⋅ default:""
Sets the image color type. For details about the available values, see the ImageMagick documentation. If you're usingcolorspace
, ImageMagick might try to find the most efficient based on the color of an image, and default to e.g."Gray"
. To force colors, you could e.g. set this parameter to"TrueColor"
-
sepia
integer(0
-99
) / null ⋅ default:null
Applies a sepia tone effect in percent. -
rotation
string / boolean / integer ⋅ default:true
Determines whether the image should be rotated. Set this totrue
to auto-rotate images that are rotated in a wrong way, or depend on EXIF rotation settings. You can also set this to an integer to specify the rotation in degrees. Specifyfalse
to disable auto-fixing of images that are rotated in a wrong way. -
compress
string / null ⋅ default:null
Specifies pixel compression for when the image is written. Valid values are"None"
,"BZip"
,"Fax"
,"Group4"
,"JPEG"
,"JPEG2000"
,"Lossless"
,"LZW"
,"RLE"
, and"Zip"
. Compression is disabled by default. Please also take a look at our /image/optimize Robot. -
blur
string / null ⋅ default:null
Specifies gaussian blur, using a value with the form{radius}x{sigma}
. The radius value specifies the size of area the operator should look at when spreading pixels, and should typically be either"0"
or at least two times the sigma value. The sigma value is an approximation of how many pixels the image is "spread"; think of it as the size of the brush used to blur the image. This number is a floating point value, enabling small values like"0.5"
to be used. -
progressive
boolean ⋅ default:false
Interlaces the image if set totrue
, which makes the image load progressively in browsers. Instead of rendering the image from top to bottom, the browser will first show a low-res blurry version of the images which is then quickly replaced with the actual image as the data arrives. This greatly increases the user experience, but comes at a cost of a file size increase by around 10%. -
transparent
string ⋅ default:""
Make this color transparent within the image. Formats which support this parameter include"GIF"
,"PNG"
,"BMP"
,"TIFF"
,"WebP"
, and"JP2"
. -
trim_whitespace
boolean ⋅ default:false
This determines if additional whitespace around the image should first be trimmed away. If you set this totrue
this parameter removes any edges that are exactly the same color as the corner pixels. -
clip
boolean / string ⋅ default:false
Apply the clipping path to other operations in the resize job, if one is present. If set totrue
, it will automatically take the first clipping path. If set to a String it finds a clipping path by that name. -
negate
boolean ⋅ default:false
Replace each pixel with its complementary color, effectively negating the image. Especially useful when testing clipping. -
density
string ⋅ default:null
While in-memory quality and file format depth specifies the color resolution, the density of an image is the spatial (space) resolution of the image. That is the density (in pixels per inch) of an image and defines how far apart (or how big) the individual pixels are. It defines the size of the image in real world terms when displayed on devices or printed. You can set this value to a specificwidth
or in the formatwidth
xheight
. If your converted image has a low resolution, please try using the density parameter to resolve that.
Text Overlay Parameters
-
text
array of objects ⋅ default:[]
An array of objects each containing text rules. The following text parameters are intended to be used as properties for your array of text overlays. Here is an example:"watermarked": { "use": "resized", "robot": "/image/resize", "imagemagick_stack": "v2.0.7", "text": [ { "text": "© 2018 Transloadit.com", "size": 12, "font": "Ubuntu", "color": "#eeeeee", "valign": "bottom", "align": "right", "x_offset": 16, "y_offset": -10 } ] }
Before:
After:
-
text.*.font
string ⋅ default:"Arial"
The font family to use. Also includes boldness and style of the font. Here is a list of all supported fonts. -
text.*.size
integer ⋅ default:12
The text size in pixels. -
text.*.rotate
integer ⋅ default:0
The rotation angle in degrees. -
text.*.color
string ⋅ default:"#000000"
The text color. All hex colors in the form"#xxxxxx"
are supported, where each x can be0-9
ora-f
."transparent"
is also supported if you want a transparent text color. In that case use "stroke" instead, otherwise your text will not be visible. -
text.*.background_color
string ⋅ default:"transparent"
The text color. All hex colors in the form"#xxxxxx"
are supported, where each x is can be0-9
ora-f
."transparent"
is also supported. -
text.*.stroke_width
integer ⋅ default:0
The stroke's width in pixels. -
text.*.stroke_color
string ⋅ default:"transparent"
The stroke's color. All hex colors in the form"#xxxxxx"
are supported, where each x is can be0-9
ora-f
."transparent"
is also supported. -
text.*.align
string ⋅ default:"center"
The horizontal text alignment. Can be"left"
,"center"
and"right"
. -
text.*.valign
string ⋅ default:"center"
The vertical text alignment. Can be"top"
,"center"
and"bottom"
. -
text.*.x_offset
integer ⋅ default:0
The horizontal offset for the text in pixels that is added (positive integer) or removed (negative integer) from the horizontal alignment. -
text.*.y_offset
integer ⋅ default:0
The vertical offset for the text in pixels that is added (positive integer) or removed (negative integer) from the vertical alignment.
Watermarking Parameters
-
watermark_url
string ⋅ default:""
A URL indicating a PNG image to be overlaid above this image. Please note that you can also supply the watermark via another Assembly Step. With watermarking you can add an image onto another image. This is usually used for logos.
Before:
After:
-
watermark_position
string / array of strings ⋅ default:"center"
The position at which the watermark is placed. The available options are"center"
,"top"
,"bottom"
,"left"
, and"right"
. You can also combine options, such as"bottom-right"
. An array of possible values can also be specified, in which case one value will be selected at random, such as[ "center", "left", "bottom-left", "bottom-right" ]
. This setting puts the watermark in the specified corner. To use a specific pixel offset for the watermark, you will need to add the padding to the image itself. -
watermark_x_offset
integer ⋅ default:0
The x-offset in number of pixels at which the watermark will be placed in relation to the position it has due towatermark_position
. Values can be both positive and negative and yield different results depending on thewatermark_position
parameter. Positive values move the watermark closer to the image's center point, whereas negative values move the watermark further away from the image's center point. -
watermark_y_offset
integer ⋅ default:0
The y-offset in number of pixels at which the watermark will be placed in relation to the position it has due towatermark_position
. Values can be both positive and negative and yield different results depending on thewatermark_position
parameter. Positive values move the watermark closer to the image's center point, whereas negative values move the watermark further away from the image's center point. -
watermark_size
string ⋅ default:""
The size of the watermark, as a percentage. For example, a value of"50%"
means that size of the watermark will be 50% of the size of image on which it is placed. The exact sizing depends onwatermark_resize_strategy
, too. -
watermark_resize_strategy
string ⋅ default:"fit"
Available values are"fit"
,"min_fit"
,"stretch"
and"area"
. To explain how the resize strategies work, let's assume our target image size is 800×800 pixels and our watermark image is 400×300 pixels. Let's also assume, thewatermark_size
parameter is set to"25%"
. For the"fit"
resize strategy, the watermark is scaled so that the longer side of the watermark takes up 25% of the corresponding image side. And the other side is scaled according to the aspect ratio of the watermark image. So with our watermark, the width is the longer side, and 25% of the image size would be 200px. Hence, the watermark would be resized to 200×150 pixels. If thewatermark_size
was set to"50%"
", it would be resized to 400×300 pixels (so just left at its original size). For the"min_fit"
resize strategy, the watermark is scaled so that the shorter side of the watermark takes up 25% of the corresponding image side. And the other side is scaled according to the aspect ratio of the watermark image. So with our watermark, the height is the shorter side, and 25% of the image size would be 200px. Hence, the watermark would be resized to 267×200 pixels. If thewatermark_size
was set to"50%"
", it would be resized to 533×400 pixels (so larger than its original size). For the"stretch"
resize strategy, the watermark is stretched (meaning, it is resized without keeping its aspect ratio in mind) so that both sides take up 25% of the corresponding image side. Since our image is 800×800 pixels, for a watermark size of 25% the watermark would be resized to 200×200 pixels. Its height would appear stretched, because keeping the aspect ratio in mind it would be resized to 200×150 pixels instead. For the"area"
resize strategy, the watermark is resized (keeping its aspect ratio in check) so that it covers"xx%"
of the image's surface area. The value fromwatermark_size
is used for the percentage area size.
ImageMagick Parameters
-
imagemagick_stack
string ⋅ default:"v2.0.7"
Selects the ImageMagick stack version to use for encoding. These versions do not reflect any real ImageMagick versions, they reflect our own internal (non-semantic) versioning for our custom ImageMagick builds. The current recommendation is to use"v2.0.7"
Other valid values can be found here.
Supplying the Watermark via an Assembly Step
You can also pass both the base image file and the watermark image to an Assembly Step via the use
parameter, allowing you to have both be part of the upload, or to use the results of other Assembly Steps as input to your /image/resize Step.
For this to work, you just need to use the as-syntax:
"my_image_step": {
"robot": "/image/resize",
"use": {
"steps": [
{ "name": ":original", "as": "base" },
{ "name": "watermark_step", "as": "watermark" }
]
}
}
Here the output of a watermark_step
step is used as the watermark whereas the base image is taken from the uploaded files.
If you use several file input fields, then you can tell Transloadit which field supplies the base image and which the watermark. Suppose you have two file input fields named the_image
and the_watermark
. These Assembly Instructions will make it work using the fields
condition:
"my_image_step": {
"robot": "/image/resize",
"use": {
"steps": [
{ "name": ":original", "fields": "the_image", "as": "base" },
{ "name": ":original", "fields": "the_watermark", "as": "watermark" }
]
}
}
Please note that the Robot's watermark_url
parameter will still continue to work.
Resize Strategies
The examples below show how the resize_strategy
impacts resizing a 400×300 pixel image to 100×100 pixels:
fit
Uses the larger side of the original image as a base for the resize. Aspect ratio is preserved. Either side will become at most 100 pixels.
For example: resizing a 400×300 image into 100×100, would produce a 100×75 image.
Before
After
fillcrop
Scales the image to fit into our 100×100 target while preserving aspect ratio, while trimming away any excess surface. This means both sides will become exactly 100 pixels, at the tradeoff of destroying parts of the image.
By default the resulting image is horizontally/vertically centered to fill the target rectangle. Use the gravity
parameter to change where to crop the image, such as "bottom"
or "left"
.
Before
After
min_fit
Uses the smaller side of the original image as a base for the resize. After resizing, the larger side will have a larger value than specified. Aspect ratio is preserved. Either side will become at least 100 pixels.
For example: resizing a 400×300 image into 100×100, would produce a 133×100 image.
Before
After
pad
Scales the image to fit while preserving aspect ratio. Both sides of the resized image become exactly 100 pixels, and any remaining surface is filled with a background color.
In this example, the background color is determined by the Assembly Variable ${file.meta.average_color}
. If you set zoom
to false
(default is true
), smaller images will be centered horizontally and vertically, and have the background padding all around them.
Before
After
stretch
Ignores aspect ratio, resizing the image to the exact width and height specified. This may result in a stretched or distorted image.
Before
After
crop
Cuts an area out of an image, discarding any overlapping parts. If the source image is smaller than the crop frame, it will be zoomed. This strategy is implied when you specify coordinates in the crop
parameter, and cannot be used without it.
To crop around human faces, see our /image/facedetect Robot instead.
Before
After
Demos featuring the /image/resize Robot
- Add a sepia effect to an image
- Apply a text watermark to images
- Apply a watermark to images
- Avoid zooming small images when resizing
- Change the quality of a JPEG
- Convert an image from JPG to PNG
- Convert an image to WebP
- Crop a picture to Twitter cover dimensions
- Crop a picture to fit a Facebook profile picture
- Crop a picture to fit the background dimensions of the Apple iPhone 11 Pro Max while keeping the file size low
- Crop an image based on cropping coordinates
- Properly preserve transparency across image types
- Remove a color around the edges of an image
- Resize an image to 75×75 pixels
- Resize and apply transparency, based on a clipping path inside an image
- Rotate uploaded images
Blog posts
We wrote the following posts about the /image/resize Robot on our blog:
- Ghostscript security incident (VU#332928) August 30, 2018
- Accidental breaking change for the crop resize strategy June 6, 2018
- Launching a new version of ImageMagick July 20, 2017
- A word on ImageTragick (CVE-2016–3714) May 4, 2016
- Performance Upgrades March 4, 2015
- Kicking Transloadit Into Gear for the New Year February 1, 2015
- On Upgrades & Goodbyes August 8, 2014
- We Have Added Support for SVG Images March 23, 2013
- Adding Support for Image Interlacing December 11, 2012
- Adding Support for Image Blurring October 21, 2012
- New Resize Strategy `fillcrop` Available February 14, 2012
- Adding Support for Audio Encoding November 21, 2011
- New `frame` Parameter for the /image/resize Robot May 26, 2011
- Adding More Options to Our Image Resize Robot May 9, 2011
- Now Offering Support for Image Rotation April 1, 2011
- Adding Support for Cropping by Coordinates January 31, 2011
- Is Your Image Scaling Software Up To Scratch? October 15, 2010
Artificial Intelligence
Recognize objects in images

The /image/describe Robot recognizes objects in images and returns them as English words.
As mentioned this Robot enables you to recognize objects on images.
You can use the labels that we return in your application to automatically classify images. You can also pass the labels down to other Robots to filter images that contain (or do not contain) certain content.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
provider
string requiredWhich AI provider to leverage. Valid values are"aws"
and"gcp"
. Transloadit outsources this task and abstracts the interface so you can expect the same data structures, but different latencies and information being returned. Different cloud vendors have different areas they shine in, and we recommend to try out and see what yields the best results for your use case. -
granularity
string ⋅ default:"full"
Wether to return a flow blown response ("full"
), or a flat list of descriptions ("list"
). -
format
string ⋅ default:"json"
In what format to return the descriptions."json"
returns a JSON file. "meta
" does not return a file, but stores the data inside Transloadit's file object (under${file.meta.descriptions}
) that's passed around between encoding Steps, so that you can use the values to burn the data into videos, filter on them, etc.
Demos featuring the /image/describe Robot
- Automatically make a slideshow from recognized objects in an image
- Recognize and reject certain objects in images
Blog posts
We wrote the following posts about the /image/describe Robot on our blog:
- 🧠 Tech Preview of our new AI bots February 17, 2020
Detect faces in images

The /image/facedetect Robot detects faces in images and returns their coordinates, or cuts them from the original images and returns those as new images.
As mentioned this Robot enables you to detect and extract human faces from your images. You can also specify a padding around the extracted faces.
It works well together with the /image/resize Robot to bring the full power of resized and optimized images to your website or app.
Important This Robot accepts all image types. By giving the format
parameter the value "preserve"
the result face images will have the same image format (JPG, PNG, etc.)
You can improve the accuracy with these tips:
- Please ensure that your pictures have the correct orientation. This Robot achieves the best performance when the faces in the image are oriented upright and not rotated.
- If the Robot detects objects other than a face, you can use
"faces": "max-confidence"
within your Template for selecting only the detection with the highest confidence. - The number of returned detections can also be controlled using the
min_confidence
parameter. Increasing its value will yield less results but each with a higher confidence. Decreasing the value on the other hand will provide more results but may also include objects other than faces.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
crop
boolean ⋅ default:false
Determine if the detected faces should be extracted. If this option is set tofalse
, then the Robot returns the input image again, but with the coordinates of all detected faces attached to file.meta.faces in the result JSON. If this parameter is set totrue
, the Robot will output all detected faces as images. -
crop_padding
string ⋅ default:"5px"
Specifies how much padding is added to the extracted face images ifcrop
is set totrue
. Values can be inpx
(pixels) or%
(percentage of the width and height of the particular face image). -
format
string ⋅ default:"preserve"
Determines the output format of the extracted face images ifcrop
is set totrue
. The default value"preserve"
means that the input image format is re-used. Valid values are"jpg"
,"png"
,"tiff"
and"preserve"
. -
min_confidence
integer(0
-100
) ⋅ default:70
Specifies the minimum confidence that a detected face must have. Only faces which have a higher confidence value than this threshold will be included in the result. -
faces
string / integer ⋅ default:"each"
Determines which of the detected faces should be returned. Valid values are:
-"each"
: Each face is returned individually.
-"max-confidence"
: Only the face with the highest confidence value is returned.
-"max-size"
: Only the face with the largest area is returned.
-"group"
: All detected faces are grouped together into one rectangle that contains all faces.
- any integer: The faces are sorted by their top-left corner and the integer determines the index of the returned face. Be aware the values are zero-indexed, meaning thatfaces: 0
will return the first face. If no face for a given index exists, no output is produced.
For the following examples, the input image is:
faces: "each"
applied:
faces: "max-confidence"
applied:
faces: "max-size"
applied:
faces: "group"
applied:
faces: 0
applied:
Demos featuring the /image/facedetect Robot
Blog posts
We wrote the following posts about the /image/facedetect Robot on our blog:
- 🧠 Tech Preview of our new AI bots February 17, 2020
- Showcase of the new faces parameter for the /image/facedetect Robot October 25, 2019
- Adding support for image face detection February 5, 2016
Recognize text in images

The /image/ocr Robot recognizes text in images and returns it in a machine-readable format.
With this Robot you can detect and extract text from images using optical character recognition (OCR).
For example, you can use the results to obtain the content of traffic signs, name tags, package labels and many more. You can also pass the text down to other Robots to filter images that contain (or do not contain) certain phrases.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
provider
string requiredWhich AI provider to leverage. Valid values are"aws"
and"gcp"
. Transloadit outsources this task and abstracts the interface so you can expect the same data structures, but different latencies and information being returned. Different cloud vendors have different areas they shine in, and we recommend to try out and see what yields the best results for your use case. -
granularity
string ⋅ default:"full"
Wether to return a flow blown response including coordinates for the text ("full"
), or a flat list of the extracted phrases ("list"
). This parameter has no effect if theformat
parameter is set to"text"
. -
format
string ⋅ default:"json"
In what format to return the extracted text."json"
returns a JSON file. "meta
" does not return a file, but stores the data inside Transloadit's file object (under${file.meta.recognized_text}
) that's passed around between encoding Steps, so that you can use the values to burn the data into videos, filter on them, etc."text"
returns the recognized text as a plain UTF-8 encoded text file.
Transcribe speech in audio or video files

The /speech/transcribe Robot transcribes speech in audio or video files.
As mentioned this Robot enables you to transcribe speech in audio or video files.
You can use the text that we return in your application, or you can pass the text down to other Robots to filter audio or video files that contain (or do not contain) certain content, or burn the text into images or video for example.
Another common use case is automatically subtitling videos, or making audio searchable.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
provider
string requiredWhich AI provider to leverage. Valid values are"aws"
and"gcp"
. Transloadit outsources this task and abstracts the interface so you can expect the same data structures, but different latencies and information being returned. Different cloud vendors have different areas they shine in, and we recommend to try out and see what yields the best results for your use case. -
granularity
string ⋅ default:"full"
Wether to return a flow blown response ("full"
), or a flat list of descriptions ("list"
). -
format
string ⋅ default:"json"
In what format to return the descriptions."text"
returns a plain text file that you can store and process."json"
returns a JSON file. "meta
" does not return a file, but stores the data inside Transloadit's file object (under${file.meta.transcription.text}
) that's passed around between encoding Steps, so that you can use the values to burn the data into videos, filter on them, etc. -
source_language
string ⋅ default:"en-US"
The spoken language of the audio or video. This will also be the language of the transcribed text. The language should be specified in the BCP-47 format, such as"en-GB"
,"de-DE"
or"fr-FR"
. Please also consult the list of supported languages for thegcp
provider and the theaws
provider.
Demos featuring the /speech/transcribe Robot
Blog posts
We wrote the following posts about the /speech/transcribe Robot on our blog:
- 🧠 Tech Preview of our new AI bots February 17, 2020
Document Processing
Convert documents into different formats

The /document/convert Robot converts documents into different formats.
This Robot can convert files to PDF, but cannot convert PDFs to different formats. If you want to convert PDFs to say, JPEG or TIFF, use the /image/resize Robot. If you want to turn them into text files or recognize (OCR) them to make them searchable, reach out, as we have a new Robot in the works for this.
Sometimes, a certain file type might not support what you are trying to accomplish. Perhaps your company is trying to automate document formatting, but it only works with docx, so all your docs need to be converted. Or maybe your stored jpg files are taking up too much space and you want a lighter format. Whatever the case, we have you covered.
Using this Robot, you can bypass the issues that certain file types may bring, by converting your file into the most suitable format. This also works in conjunction with our other Robots, allowing for even greater versatility when using our services.
Important A general rule of this Robot is that converting files into an alien format category will result in an error. For example, SRT files can be converted into the VTT format, but not to an image.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
format
string ⋅ default:""
The desired format for document conversion. We support the following values:doc
,docx
,html
,xhtml
,xml
,pdf
,jpg
,jpeg
,gif
,png
,svg
,ai
,eps
,ps
,txt
,text
,csv
,xls
,xlsx
,xla
,oda
,odt
,odd
,ott
,ppt
,pptx
,ppz
,pps
,pot
,rtf
,rtx
,latex
,vtt
, andsrt
.
Demos featuring the /document/convert Robot
Blog posts
We wrote the following posts about the /document/convert Robot on our blog:
- Re-loadit: the /document/convert Robot November 16, 2019
Extract thumbnail images from documents

The /document/thumbs Robot generates an image for each page in a PDF file or an animated gif file that loops through all pages.
Things to Keep in Mind
- If you convert a multi-page PDF file into several images, all result images will be sorted with the first image being the thumbnail of the first document page, etc.
- You can also check the
meta.thumb_index
key of each result image to find out which page it corresponds to. Keep in mind that these thumb indices start at 0 and not at 1!
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
page
integer / null ⋅ default:null
The PDF's page that you want to convert to an image. By default the value isnull
which means that all pages will be converted into images. -
format
string ⋅ default:"png"
The format of the extracted image(s). Supported values are"jpeg"
,"jpg"
,"gif"
and"png"
. If you specify the value"gif"
then an animated gif cycling through all pages is created. Please check out this demo to learn more about this. -
delay
integer / null ⋅ default:null
If your output format is"gif"
then this parameter sets the number of 100th seconds to pass before the next frame is shown in the animation. Set this to100
for example to allow 1 second to pass between the frames of the animated gif. If your output format is not"gif"
, then this parameter does not have any effect. -
width
integer(1
-5000
) ⋅ default: AutoWidth of the new image, in pixels. If not specified, will default to the width of the input image -
height
integer(1
-5000
) ⋅ default: AutoHeight of the new image, in pixels. If not specified, will default to the height of the input image -
resize_strategy
string ⋅ default:"pad"
One of the available resize strategies. -
background
string ⋅ default:"#FFFFFF"
-
alpha
string ⋅ default:""
Change how the alpha channel of the resulting image should work. Valid values are"Set"
to enable transparency and"Remove"
to remove transparency. For a list of all valid values please check the ImageMagick documentation here. -
density
string / null ⋅ default:null
While in-memory quality and file format depth specifies the color resolution, the density of an image is the spatial (space) resolution of the image. That is the density (in pixels per inch) of an image and defines how far apart (or how big) the individual pixels are. It defines the size of the image in real world terms when displayed on devices or printed. You can set this value to a specificwidth
or in the formatwidth
xheight
. If your converted image has a low resolution, please try using the density parameter to resolve that. -
colorspace
string ⋅ default:""
Sets the image colorspace. For details about the available values, see the ImageMagick documentation. Please note that if you were using"RGB"
, we recommend using"sRGB"
. ImageMagick might try to find the most efficientcolorspace
based on the color of an image, and default to e.g."Gray"
. To force colors, you might then have to use this parameter. -
trim_whitespace
boolean ⋅ default:true
This determines if additional whitespace around the PDF should first be trimmed away before it is converted to an image. If you set this totrue
only the real PDF page contents will be shown in the image. If you need to reflect the PDF's dimensions in your image, it is generally a good idea to set this tofalse
. -
pdf_use_cropbox
boolean ⋅ default:true
Some PDF documents lie about their dimensions. For instance they'll say they are landscape, but when opened in decent Desktop readers, it's really in portrait mode. This can happen if the document has a cropbox defined. When this option is enabled (by default), the cropbox is leading in determining the dimensions of the resulting thumbnails. -
output_meta
object / boolean ⋅ default:{}
Generally, this parameter allows you to specify a set of metadata that is more expensive on cpu power to calculate, and thus is disabled by default to keep your Assemblies processing fast. This Robot only supports the default value of{}
(meaning all meta data will be extracted) andfalse
. A value offalse
means that only width, height, size and thumb_index will be extracted for the result images, which would also provide a great performance boost for documents with many pages.
ImageMagick Parameters
-
imagemagick_stack
string ⋅ default:"v2.0.7"
Selects the ImageMagick stack version to use for encoding. These versions do not reflect any real ImageMagick versions, they reflect our own internal (non-semantic) versioning for our custom ImageMagick builds. The current recommendation is to use"v2.0.7"
Other valid values can be found here.
Demos featuring the /document/thumbs Robot
- Convert all pages of a document into an animated GIF
- Convert all pages of a document into separate images
- Convert the first page of a document into an image
Blog posts
We wrote the following posts about the /document/thumbs Robot on our blog:
- Kicking Transloadit Into Gear for the New Year February 1, 2015
- Adding `density` parameter to our /document/thumbs Robot April 17, 2013
- Convert PDF Files Into Animated Gifs - Animation Delays Now Supported December 12, 2012
- Make Document Thumbnails With Transloadit November 1, 2012
Take screenshots of webpages or html files

The /html/convert Robot takes screenshots of web pages or uploaded HTML pages.
A URL can be provided instead of an input HTML file, to capture a screenshot from the website referenced by the URL.
Use the /image/resize Robot to resize or crop the screenshot as needed.
Note A validation error will occur if neither an HTML file is uploaded nor a URL parameter is given.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
url
string / null ⋅ default:null
The URL of the web page to be converted. Optional, as you can also upload/import HTML files and pass it to this Robot -
format
string ⋅ default:"png"
The format of the resulting image. The supported values are"pdf"
,"jpg"
,"jpeg"
, and"png"
. -
fullpage
boolean ⋅ default:true
Determines if a screenshot of the full page should be taken or not. If set totrue
, theheight
parameter will not have any effect, as heights of websites vary. You can control the size of the resulting image somewhat, though, by setting thewidth
parameter. If set tofalse
, an image will be cropped from the top of the webpage according to yourwidth
andheight
parameters. -
omit_background
boolean ⋅ default:false
Determines whether to preserve a transparent background in HTML pages. Useful if you're generating artwork in HTML that you want to overlay on e.g. a video. The default offalse
fills transparent areas with a white background, for easier reading/printing. This parameter is only used whenformat
is notpdf
. -
width
integer ⋅ default:1024
The screen width that will be used, in pixels. Change this to change the dimensions of the resulting image. -
height
integer ⋅ default:768
The screen height that will be used, in pixels. By default this equals the length of the web page in pixels iffullpage
is set totrue
. Iffullpage
is set tofalse
, the height parameter takes effect and defaults to the value768
. -
delay
integer ⋅ default:0
The delay (in milliseconds) applied to allow the page and all of its JavaScript to render before taking the screenshot.
Demos featuring the /html/convert Robot
- Overlay videos with dynamic artwork, generated with HTML & JS
- Take a screenshot of a website (by uploading an HTML file)
- Take a screenshot of a website automatically (by using a URL)
Blog posts
We wrote the following posts about the /html/convert Robot on our blog:
- New Parameters for the /html/convert Robot April 29, 2013
- Two New Robots and More Features March 30, 2012
File Filtering
Filter files

The /file/filter Robot directs files to different encoding Steps based on your conditions.
Think of this Robot as your if/else checks to construct advanced file conversion workflows and to not convert certain files that your users uploaded depending on their metadata.
The accepts
and declines
parameters can each be set to an array with three members:
- A value or job variable, such as
${file.mime}
- One of the following operators:
==, ===, <, >, <=, >=, !=, !==, regex, !regex
- A value or job variable, such as
50
or"foo"
Examples:
["${file.meta.width}", ">", "${file.meta.height}"]
["${file.size}", "<=", "720"]
["720", ">=", "${file.size}"]
["${file.mime}", "regex", "image"]
Important If you would like to match against a null
value or a value that is not present (like an audio file does not have a video_codec property in its metadata), please match against ""
(an empty string) instead. We'll support proper matching against null
in the future, but we cannot easily right now without breaking backwards compatibility.
The following lists the supported Job Variables.
Available Job Variables
Conditions on properties that a file does not have will be ignored. For example, an image does not have
${file.meta.bitrate}
. Also, note that since ${file.width}
will be ignored, use ${file.meta.width}
instead.
-
${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 thepath
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${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. -
${file.original_name}
The name of the original file (including file extension) 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_name}
that matches the${file.name}
of the imported file. -
${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. -
${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 afile.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"
, thenfile.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 thepath
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 slugged name of the file. Any characters other thanA-Z a-z 0-9 -_.
are replaced with underscores, and spaces are replaced with dashes. This includes the file extension as well. Note that if you have two filesッッ.jpg
andチチ.jpg
they will both be called__.jpg
. So you'll want to take extra care to only use${file.url_name}
in conjunction with${unique_prefix}
or${file.md5hash}
. -
${file.basename}
The name of the file being processed, without the file extension. -
${file.url_basename}
The slugged basename of the file (the file name without the file extension). Any characters other thanA-Z a-z 0-9 -_.
are replaced with underscores, and spaces are replaced with dashes. Note that if you have two filesッッ.jpg
andチチ.jpg
they will both be called__.jpg
. So you'll want to take extra care to only use${file.url_basename}
in conjunction with${unique_prefix}
or${file.md5hash}
. -
${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 fields submitted together with the upload.
For example, in the case of a Form submission where Uppy was set to allowfields: ['myvar']
, and the form had a tag like<input type="hidden" name="myvar" value="1" />
,${fields.myvar}
would contain a value of1
.
Alternatively, fields could also be populated programmatically like so:json { "steps": { "store": { "use": "encoded", "robot": "/s3/store", "credentials": "YOUR_S3_CREDENTIALS_NAME", "path": "${assembly.id}/${fields.subdir}/356" } }, "fields": { "subdir": "bar" } }
In the case of a conflict, variables derived from form fields take precedence over those derived from thefields
key.
Available Operators for the Conditions
Operator | Description | Example |
---|---|---|
|
equals without type check |
|
|
strict equals with type check |
|
|
less than |
|
|
greater than |
|
|
less or equal |
|
|
greater or equal |
|
|
simple inequality check without type check |
|
|
strict inequality check with type check |
|
|
case-insensitive regular expression based on RE2 |
|
|
case-insensitive regular expression based on RE2 |
|
|
check if the right element is included in the array, which is represented by the left element |
|
|
check if the right element is not included in the array, which is represented by the left element |
|
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
accepts
array of arrays ⋅ default:[]
Files that match at least one requirement will be accepted, or declined otherwise. If the array is empty, all files will be accepted. Example:
[["${file.mime}", "==", "image/gif"]]
.
If thecondition_type
parameter is set to"and "
, then all requirements must match for the file to be accepted. -
declines
array of arrays ⋅ default:[]
Files that match at least one requirement will be declined, or accepted otherwise. Example:
[["${file.size}",">","1024"]]
.
If thecondition_type
parameter is set to"and "
, then all requirements must match for the file to be declined. -
condition_type
string ⋅ default:"or"
Specifies the condition type according to which the members of theaccepts
ordeclines
arrays should be evaluated. Can be"or"
or"and"
. -
error_on_decline
boolean ⋅ default:false
If this is set totrue
and one or more files are declined, the Assembly will be stopped and marked with an error. -
error_msg
string ⋅ default:"One of your files was declined"
This is the error message shown to your users (such as by Uppy) when a file is declined anderror_on_decline
is set totrue
.
Demos featuring the /file/filter Robot
- Automatically make a slideshow from recognized objects in an image
- Automatically reject files containing copyright
- Burn subtitles into a video
- Extract audio from video files
- Filter out all audio files with a bit rate lower than 64K
- Filter out all image files without a full HD resolution
- Filter out anything other than image files
- Filter out anything other than video or image files
- Filter out files that are smaller than 1KB
- Filter out portrait-oriented images
- Filter out videos that are larger than 20MB or longer than 5 minutes
- Import your Dropbox files to Transloadit for encoding
- Merge an audio file with a video file, keeping the shortest input stream duration intact
- Only resize larger images when resizing files
- Properly preserve transparency across image types
- Recognize and reject certain objects in images
- Reject videos that do not have an audio track
Blog posts
We wrote the following posts about the /file/filter Robot on our blog:
- Performance Upgrades March 4, 2015
- Kicking Transloadit Into Gear for the New Year February 1, 2015
- Two New Robots and More Features March 30, 2012
- New /file/filter Robot Released December 6, 2011
Scan files for viruses

The /file/virusscan Robot rejects millions of trojans, viruses, malware & other malicious threats before they reach your platform.
This Robot is built on top of ClamAV, the best open source antivirus engine available. We update its signatures on a daily basis.
By default, this Robot excludes all malicious files from further processing without any additional notification. This behavior can be changed by setting error_on_decline
to true
, which will stop Assemblies as soon as malicious files are found. Such Assemblies will then be marked with an error.
We allow the use of industry standard EICAR files for integration testing without needing to use potentially dangerous live virus samples.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
error_on_decline
boolean ⋅ default:false
If this is set totrue
and one or more files are declined, the Assembly will be stopped and marked with an error. -
error_msg
string ⋅ default:"One of your files was declined"
This is the error message shown to your users (such as by Uppy) when a file is declined anderror_on_decline
is set totrue
.
Demos featuring the /file/virusscan Robot
Blog posts
We wrote the following posts about the /file/virusscan Robot on our blog:
- How to filter input files using the /file/filter and /file/virusscan Robots February 6, 2019
- Happy 2016 from Transloadit December 31, 2015
- New Robot for Virus Detection July 21, 2015
Media Cataloging
Write metadata to media

The /meta/write Robot writes metadata into any file that supports it.
This Robot currently accepts images, videos and audio files.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
data_to_write
object ⋅ default:{}
A key/value map defining the metadata to write into the file.
FFmpeg Parameters
-
ffmpeg_stack
string ⋅ default:"v3.3.3"
Selects the FFmpeg stack version to use for encoding. These versions do not reflect any real FFmpeg versions, they reflect our own internal (non-semantic) versioning for our custom FFmpeg builds. The current recommendation is to use"v3.3.3"
Other valid values can be found here.
Demos featuring the /meta/write Robot
Blog posts
We wrote the following posts about the /meta/write Robot on our blog:
- Upgrading Encoding Engines July 31, 2015
- On Upgrades & Goodbyes August 8, 2014
File Compressing
Compress files

The /file/compress Robot creates archives of files or file conversion results.
Archive structure for the "advanced" file layout.
There are a few things that we kept in mind when designing the "advanced"
archive structure:
- There could be naming collisions.
- You want to know which Step a result file belongs to.
- You want to know from which originally uploaded file a result file was generated.
- ideally you want subfolders for a better structure of files.
To achieve all this, we have created the following archive file structure.
- There is a subfolder for each Step name that has result files in the archive.
- Files are named according to
[first_2_letters_of_unique_original_prefix]_[first_2_letters_of_unique_prefix]_[original_file_name]
. If you do not know what the original prefixes are, please check our available Assembly variables and look for${unique_original_prefix}
and${unique_prefix}
. - Files that belong to the
:original
Step (originally uploaded files) do not include the first two letters of theunique_original_prefix
. - If you are dealing with thumbnails from the /video/thumbs Robot, there is an additional digit representing the order in the file name.
Here is an example:
":original":
- gh_a.mov # "gh" are the first 2 letters of the unique prefix.
# "a.mov" was the file name of the uploaded file.
- ff_b.mov
"thumbed":
- gh_e8_thumb_1.jpg # "gh" is the unique original prefix, meaning it's a result of a.mov.
# "e8" is the file's unique prefix.
# The "1" shows the thumbnail order.
- gh_cv_thumb_2.jpg
- ff_9b_thumb_3.jpg
"resized":
- gh_ll_thumb.jpg
- gh_df_thumb.jpg
- ff_jk_thumb.jpg # is a child of b.mov, as it starts with "ff"
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
format
string ⋅ default:"tar"
The format of the archive to be created. Supported values are"tar"
and"zip"
. Note that"tar"
without settinggzip
totrue
results in an archive that's not compressed in any way. -
gzip
boolean ⋅ default:false
Determines if the result archive should also be gzipped. Gzip compression is only applied if you use the"tar"
format. -
password
string ⋅ default:null
This allows you to encrypt all archive contents with a password and thereby protect it against unauthorized use. To unzip the archive, the user will need to provide the password in a text input field prompt. This parameter has no effect if the format parameter is anything other than"zip"
. -
compression_level
integer ⋅ default:-6
Determines how fiercly to try to compress the archive.-0
is compressionless, which is suitable for media that is already compressed.-1
is fastest with lowest compression.-9
is slowest with the highest compression. If you are using-0
in combination with thetar
format withgzip
enabled, consider settinggzip
tofalse
instead. This results in a plain Tar archive, meaning it already has no compression. -
file_layout
string ⋅ default:"advanced"
Determines if the result archive should contain all files in one directory (value for this is"simple"
) or in subfolders according to the explanation below (value for this is"advanced"
). Files with same names are numbered in the"simple"
file layout to avoid naming collisions.
Demos featuring the /file/compress Robot
- Convert document files to PDF format
- Create a Zip file for each uploaded file
- Create a gzipped tar archive containing multiple result files
- Create a single Zip file containing all uploaded files
Blog posts
We wrote the following posts about the /file/compress Robot on our blog:
- A Happy 2014 from Transloadit! January 14, 2014
- Create Zip and Tar Archives of Encoded Files September 4, 2013
Decompress archives

The /file/decompress Robot extracts entire archives of files to be consumed by other Robots or exported as individual files.
The /file/decompress Robot reads, decompresses and extracts all files from an archive file. The following archive formats are supported:
- ZIP archives (with uncompressed or "deflate"-compressed entries)
- 7-Zip archives
- RAR archives
- GNU tar format (including GNU long filenames, long link names, and sparse files)
- Solaris 9 extended tar format (including ACLs)
- Old V7 tar archives
- POSIX ustar
- POSIX pax interchange format
- POSIX octet-oriented cpio
- SVR4 ASCII cpio
- POSIX octet-oriented cpio
- Binary cpio (big-endian or little-endian)
- ISO9660 CD-ROM images (with optional Rockridge or Joliet extensions)
- GNU and BSD "ar" archives
- "mtree" format
- Microsoft CAB format
- LHA and LZH archives
- XAR archives
This Robot also detects and handles any of the following before evaluating the archive file:
- uuencoded files
- Files with RPM wrapper
- gzip compression
- bzip2 compression
- compress/LZW compression
- lzma, lzip, and xz compression
For security reasons, archives that contain symlinks to outside the archived dir, will error out the Assembly. Decompressing password-protected archives (encrypted archives) is currently not fully supported but will not cause an Assembly to fail.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
ignore_errors
array of strings / boolean ⋅ default:[]
A possible array member is only"meta"
. There might be an error coming up when trying to extract metadata from the files inside your archive. This happens for files that are zero bytes big for example. Setting this totrue
will cause the Robot to not stop the file decompression (and the entire Assembly) when that happens. To keep backwards compatibility, setting this parameter totrue
will set it to["meta"]
internally.
Demos featuring the /file/decompress Robot
- Automatically decompress uploaded archives
- Automatically extract all files from an archive
- Extract all images from an archive and resize them
Blog posts
We wrote the following posts about the /file/decompress Robot on our blog:
- Kicking Transloadit Into Gear for the New Year February 1, 2015
- Two New Robots and More Features March 30, 2012
File Exporting
Downloading
If you do not configure an export Robot, the result URLs in the Assembly Status JSON will point to temporary locations that you can download from for 24h, before being automatically removed. This can suit some use cases, but we generally recommend using an export Robot so that files persist, and you profit from retries and atomicity (should the export fail after our retries, the Assembly fails and you'll be notified).
Export files to Microsoft Azure

The /azure/store Robot exports encoding results to Microsoft Azure.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your Azure container, account and key. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:"account"
,"key"
,"container"
. -
path
string ⋅ default:"${unique_prefix}/${file.url_name}"
The path at which the file is to be stored. This may include any available Assembly variables. -
content_type
string ⋅ default:""
The content type with which to store the file. By default this will be guessed by Azure. -
content_encoding
string ⋅ default:""
The content encoding with which to store the file. By default this will be guessed by Azure. -
content_language
string ⋅ default:""
The content language with which to store the file. By default this will be guessed by Azure. -
cache_control
string ⋅ default:""
The cache control header with which to store the file. -
metadata
string ⋅ default:{}
A JavaScript object containing a list of metadata to be set for this file on Azure, such as{ FileURL: "${file.url_name}" }
. This can also include any available Assembly variables. -
sas_expires_in
integer / null ⋅ default:null
Set this to a number to enable shared access signatures for your stored object. This reflects the number of seconds that the signature will be valid for once the object is stored. Enabling this will attach the shared access signature (SAS) to the result URL of your object. -
sas_permissions
string ⋅ default:""
Set this to a combination ofr
(read),w
(write) andd
(delete) for your shared access signatures (SAS) permissions.

url_template
parameter which is explained in the table below.
Demos featuring the /azure/store Robot
Blog posts
We wrote the following posts about the /azure/store Robot on our blog:
- The /azure/store Robot January 7, 2020
- Happy 2016 from Transloadit December 31, 2015
- Support for Windows Azure and Softlayer November 18, 2015
Export files to Backblaze

The /backblaze/store Robot exports encoding results to Backblaze.
Access
Your Backblaze buckets need to have the listBuckets
(to obtain a bucket ID from a bucket name), writeFiles
and listFiles
permissions.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your Backblaze bucket, app key id app key. To create your credential information head over to Backblaze, sign in to your account, and select Create a Bucket. Save the name of your bucket, and click on the App Keys tab, scroll to the bottom of the page then select “Add a New Application Key”. Allow access to your recently created bucket, select “Read and Write” as your type of access, and tick the “Allow List All Bucket Names:” option. Now everything is in place, create your key, and take note of the information you are given so you can add input the information into your Template Credentials.Your app key will only be viewable once so make sure you note this down. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:
"bucket"
,"app_key_id"
,"app_key"
. -
path
string ⋅ default:"${unique_prefix}/${file.url_name}"
The path at which the file is to be stored. This may include any available Assembly variables. -
headers
object ⋅ default:{}
An object containing a list of headers to be set for this file on backblaze, such as{ FileURL: "${file.url_name}" }
. This can also include any available Assembly Variables. Here you can find a list of available headers. Object Metadata can be specified usingX-Bz-Info-*
headers.

url_template
parameter which is explained in the table below.
Demos featuring the /backblaze/store Robot
Export files to Rackspace Cloud Files

The /cloudfiles/store Robot exports encoding results to Rackspace Cloud Files.
A Note About URLs
If your container is CDN-enabled, the resulting file.url
indicates the path to the file in your CDN container, or is null
otherwise.
The storage container URL for this file is always available via file.meta.storage_url
.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your Cloudfiles container, user, key, account type and data center. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:"account_type"
("us" or "uk"),"data_center"
("dfw" for Dallas or "ord" for Chicago for example),"user"
,"key"
,"container"
. -
path
string ⋅ default:"${file.id}_${file.url_name}"
The path at which to store the file. This value can also contain Assembly variables.

url_template
parameter which is explained in the table below.
Demos featuring the /cloudfiles/store Robot
- Copy files from Amazon S3 to Rackspace Cloud Files
- Store uploaded files in a Rackspace Cloud Files container
Blog posts
We wrote the following posts about the /cloudfiles/store Robot on our blog:
- Two Small Feature Updates February 11, 2012
- Support for Rackspace Cloud Files November 11, 2010
Export files to DigitalOcean Spaces

The /digitalocean/store Robot exports encoding results to DigitalOcean Spaces.
The URL to the result file in your DigitalOcean Space will be returned in the Assembly Status JSON.
Important Our result URLs use the form https://{space}.{region}.digitaloceanspaces.com/path/to/file
, which means that your Space name must be DNS-compliant. This includes that you do not use uppercase letters in your Space name.
Please note that any non alphanumeric characters in the file names will be replaced with an underscore, and spaces are replaced with dashes.
If your existing DigitalOcean Space contains uppercase letters or is otherwise not DNS-compliant, please make sure to rewrite the result URLs using the Robot's url_prefix
parameter.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your DigitalOcean space, key, secret and region. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:"space"
,"region"
(for example:"fra1"
or"nyc3"
),"key"
,"secret"
. -
path
string ⋅ default:"${unique_prefix}/${file.url_name}"
The path at which the file is to be stored. This may include any available Assembly variables. -
url_prefix
string ⋅ default:"https://{space}.{region}.digitaloceanspaces.com/"
The URL prefix used for the returned URL, such as"https://my.cdn.com/some/path"
. -
acl
string ⋅ default:"public-read"
The permissions used for this file. This can be"public-read"
or"private"
. -
headers
object ⋅ default:{ "Content-Type": file.mime }
An object containing a list of headers to be set for this file on DigitalOcean Spaces, such as{ FileURL: "${file.url_name}" }
. This can also include any available Assembly Variables. Here you can find a list of available headers. Object Metadata can be specified usingx-amz-meta-*
headers. Note that these headers do not support non-ASCII metadata values. -
sign_urls_for
integerThis parameter provides signed urls in the result JSON (in thesigned_ssl_url
property). The number that you set this parameter to is the url expiry time in seconds. If this parameter is not used, no url signing is done.

url_template
parameter which is explained in the table below.
Demos featuring the /digitalocean/store Robot
Blog posts
We wrote the following posts about the /digitalocean/store Robot on our blog:
- The /digitalocean/store Robot December 9, 2019
Export files to Dropbox

The /dropbox/store Robot exports encoding results to Dropbox.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your access token. Please create your dropbox access token here. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameter instead:"access_token"
. -
path
string ⋅ default:"${unique_prefix}/${file.url_name}"
The path at which the file is to be stored. This may include any available Assembly variables. -
create_sharing_link
boolean ⋅ default:false
Whether to create a URL to this file for sharing with other people. This will overwrite the file's"url"
property.

url_template
parameter which is explained in the table below.
Demos featuring the /dropbox/store Robot
- Copy files from Amazon S3 to Dropbox
- Import your Dropbox files to Transloadit for encoding
- Save your results to Dropbox
Blog posts
We wrote the following posts about the /dropbox/store Robot on our blog:
- Re-loadit: the /dropbox/store Robot December 12, 2018
Export files to FTP servers

The /ftp/store Robot exports encoding results to your FTP servers. This Robot relies on password access. For more security, consider our /sftp/store Robot.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your FTP host, user and password. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:"host"
,"user"
,"password"
. -
path
string ⋅ default:"${unique_prefix}/${file.url_name}"
The path at which the file is to be stored. This can contain any available Assembly variables. Please note that you might need to include your homedir at the beginning of the path. -
port
integer ⋅ default: 21The port to use for the FTP connection. -
url_template
string ⋅ default:"https://{HOST}/{PATH}"
The URL of the file in the result JSON. The following Assembly variables are supported. -
ssl_url_template
string ⋅ default:"https://{HOST}/{PATH}"
The SSL URL of the file in the result JSON. The following Assembly variables are supported.

url_template
parameter which is explained in the table below.
Things to Keep in Mind
- Your server might be unresponsive from time to time. Since (S)FTP servers are harder to scale, we see this happen a lot. As a result, if this Robot fails to store one of your files, it will retry to store the file 5 times over 15 minutes.
- This also means that when you provided the wrong credentials (when testing for example) Assemblies can take up to 15 minutes to complete.
- If an Assembly has an export Step and takes long to execute, it is almost always due to the export Step having wrong credentials or the server being unreachable.
We advise you to use our /sftp/store and /sftp/import Robots when possible, as it is much more secure. The FTP Robots should only serve as a fallback in case cloud storage or SFTP cannot be used.
Demos featuring the /ftp/store Robot
Blog posts
We wrote the following posts about the /ftp/store Robot on our blog:
- Releasing Our FTP Robot May 29, 2012
Export files to Google Storage

The /google/store Robot exports encoding results to Google Storage.
The URL to the exported file in your Google bucket will be presented in the Transloadit Assembly Status JSON. This Robot can also be used to export encoded files to Google's Firebase as demonstrated in this blogpost.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredCreate a new Google service account. Set its role to "Storage Object Creator". Choose "JSON" for the key file format and download it to your computer. You will need to upload this file when creating your Template Credentials.
Go back to your Google credentials project and enable the "Google Cloud Storage JSON API" for it. Wait around ten minutes for the action to propagate through the Google network. Grab the project id from the drop down menu in the header bar on the Google site. You will also need it later on.
Now you can set up the storage.objects.create and storage.objects.delete permissions. The latter is optional and only required if you intend to overwrite existing paths.
To do this from the Google Cloud console, locate to IAM & Admin and select Roles. From here select +CREATE ROLE, enter a name, set the role launch stage as general availability and set the permissions stated above. Next relocate to your storage browser and select the ellipsis on your bucket to edit bucket permissions. From here select ADD MEMBER, enter your service account as a new member and select your newly created role.
Then create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. -
path
string ⋅ default:"${unique_prefix}/${file.url_name}"
The path at which the file is to be stored. This may include any available Assembly Variables. -
acl
string ⋅ default:"public-read"
The permissions used for this file. This can be"public-read"
,"authenticated-read"
,"bucket-owner-full-control"
,"private"
or"project-private"
.

url_template
parameter which is explained in the table below.
Demos featuring the /google/store Robot
- Copy files from Amazon S3 to Google Storage
- Use Google Cloud Storage to store your results from Transloadit
Blog posts
We wrote the following posts about the /google/store Robot on our blog:
- Re-loadit: the /google/store Robot March 1, 2019
Export files to min.io

The /minio/store Robot exports encoding results to min.io buckets.
The URL to the result file will be returned in the Assembly Status JSON.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your minio bucket, host, key and secret. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:"bucket"
,"host"
,"key"
,"secret"
. -
path
string ⋅ default:"${unique_prefix}/${file.url_name}"
The path at which the file is to be stored. This may include any available Assembly variables. -
acl
string ⋅ default:"public-read"
The permissions used for this file. This can be"public-read"
or"private"
. -
headers
object ⋅ default:{ "Content-Type": file.mime }
An object containing a list of headers to be set for this file on minio Spaces, such as{ FileURL: "${file.url_name}" }
. This can also include any available Assembly Variables. Object Metadata can be specified usingx-amz-meta-*
headers. Note that these headers do not support non-ASCII metadata values. -
sign_urls_for
integerThis parameter provides signed urls in the result JSON (in thesigned_ssl_url
property). The number that you set this parameter to is the url expiry time in seconds. If this parameter is not used, no url signing is done.

url_template
parameter which is explained in the table below.
Demos featuring the /minio/store Robot
Export files to Amazon S3

The /s3/store Robot exports encoding results to Amazon S3.
Important Please note that the acl
parameter's default value is "public"
. AWS S3 recently introduced a bucket setting called "Block new public ACLs and uploading public objects (Recommended)". You need to set this to False in your bucket if you intend to leave the Robot's acl
parameter to "public"
, otherwise you'll keep getting permission errors returned in your Assemblies even though your S3 credentials are configured correctly.
If you are new to Amazon S3, see our tutorial on using your own S3 bucket.
The URL to the result file in your S3 bucket will be returned in the Assembly Status JSON.
Important Our result URLs use the form http://{bucket}.s3.amazonaws.com/path/to/file
, which means that your bucket name must be DNS-compliant. This includes that you do not use uppercase letters in your bucket name. For more information regarding this please see Amazon's recommendations.
Please note that any non alphanumeric characters in the file names will be replaced with an underscore, and spaces are replaced with dashes.
If your existing S3 bucket contains uppercase letters or is otherwise not DNS-compliant, please make sure to rewrite the result URLs using the Robot's url_prefix
parameter.
Limit Access
You will also need to add permissions to your bucket so that Transloadit can access it properly. Here is an example IAM policy that you can use. Following the principle of least privilege, it contains the minimum required permissions to export a file to your S3 bucket using Transloadit. You may require more permissions (especially viewing permissions) depending on your application.
Please change {BUCKET_NAME}
in the values for Sid
and Resource
accordingly. Also, this policy will grant the minimum required permissions to all your users. We advise you to create a separate Amazon IAM user, and use its User ARN (can be found in the "Summary" tab of a user here) for the Principal
value. More information about this can be found here.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowTransloaditToStoreFilesIn{BUCKET_NAME}Bucket",
"Effect": "Allow",
"Action": [
"s3:GetBucketLocation",
"s3:ListBucket",
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": [
"arn:aws:s3:::{BUCKET_NAME}",
"arn:aws:s3:::{BUCKET_NAME}/*"
]
}
]
}
The Sid
value is just an identifier for you to recognize the rule later. You can name it anything you like.
The policy needs to be separated into two parts, because the ListBucket
action requires permissions on the bucket while the other actions require permissions on the objects in the bucket. When targeting the objects there's a trailing slash and an asterisk in the Resource
parameter, whereas when the policy targets the bucket, the slash and the asterisk are omitted.
Please note that if you give the Robot's acl
parameter a value of "bucket-default"
, then you do not need the "s3:PutObjectAcl"
permission in your bucket policy.
In order to build proper result URLs we need to know the region in which your S3 bucket resides. For this we require the GetBucketLocation
permission. Figuring out your bucket's region this way will also slow down your Assemblies. To make this much faster and to also not require the GetBucketLocation
permission, we have added the bucket_region
parameter to the /s3/store and /s3/import Robots. We recommend using them at all times.
Please keep in mind that if you use bucket encryption you may also need to add "sts:*"
and "kms:*"
to the bucket policy. Please read here and here in case you run into trouble with our example bucket policy.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your S3 bucket, key, secret and bucket region. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:"bucket"
,"bucket_region"
(for example:"us-east-1"
or"eu-west-2"
),"key"
,"secret"
. -
path
string ⋅ default:"${unique_prefix}/${file.url_name}"
The path at which the file is to be stored. This may include any available Assembly variables. -
url_prefix
string ⋅ default:"http://{bucket}.s3.amazonaws.com/"
The URL prefix used for the returned URL, such as"http://my.cdn.com/some/path/"
. -
acl
string ⋅ default:"public-read"
The permissions used for this file. This can be"public-read"
,"public"
,"private"
or"bucket-default"
. Please keep in mind that the default value"public-read"
can lead to permission errors due to the"Block all public access"
checkbox that is checked by default when creating a new Amazon S3 Bucket in the AWS console. -
headers
object ⋅ default:{ "Content-Type": file.mime }
An object containing a list of headers to be set for this file on S3, such as{ FileURL: "${file.url_name}" }
. This can also include any available Assembly Variables. Here you can find a list of available headers. Object Metadata can be specified usingx-amz-meta-*
headers. Note that these headers do not support non-ASCII metadata values. -
host
string ⋅ default:"s3.amazonaws.com"
The host of the storage service used. This only needs to be set when the storage service used is not Amazon S3, but has a compatible API (such as hosteurope.de). -
no_vhost
boolean ⋅ default:false
Set totrue
if you use a custom host and run into access denied errors. -
sign_urls_for
integerThis parameter provides signed urls in the result JSON (in thesigned_url
andsigned_ssl_url
properties). The number that you set this parameter to is the url expiry time in seconds. If this parameter is not used, no url signing is done.

url_template
parameter which is explained in the table below.
Demos featuring the /s3/store Robot
- Copy files from Backblaze to Amazon S3
- Copy files from Cloud Files to Amazon S3
- Copy files from Digitalocean Storage to Amazon S3
- Copy files from Dropbox to Amazon S3
- Copy files from FTP servers to Amazon S3
- Copy files from Google Storage to Amazon S3
- Copy files from Openstack/Swift to Amazon S3
- Copy files from SFTP servers to Amazon S3
- Copy files from Wasabi to Amazon S3
- Copy files from Webservers to Amazon S3
- Copy files from azure to Amazon S3
- Copy files from cloudfiles to Amazon S3
- Copy files from min.io to Amazon S3
- Copy files from web servers to Amazon S3
- Encode a video, extract 8 thumbnails and store everything in an S3 bucket
- Store uploaded files in an Amazon S3 bucket
Blog posts
We wrote the following posts about the /s3/store Robot on our blog:
- Post Mortem: S3 Saving Incident February 17, 2015
- S3 Changes February 5, 2015
- New /s3/store Parameter May 26, 2011
- Fixing Amazon S3 Bugs May 16, 2011
- Renaming Some Robots April 7, 2010
Export files to SFTP servers

The /sftp/store Robot exports encoding results to your own SFTP server.
Exports the input file to the specified server, via SFTP.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your SFTP host, user, port and optional custom public key. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:"host"
,"port"
,"user"
and"public_key"
."public_key"
is optional. -
path
string ⋅ default:"${unique_prefix}/${file.url_name}"
The path at which the file is to be stored. This may include any available Assembly variables. -
url_template
string ⋅ default:"http://host/path"
The URL of the file in the result JSON. This may include any of the following supported Assembly variables. -
ssl_url_template
string ⋅ default:"https://{HOST}/{PATH}"
The SSL URL of the file in the result JSON. The following Assembly variables are supported. -
file_chmod
string ⋅ default: AutoThis optional parameter controls how an uploaded file's permission bits are set. You can use any string format that thechmod
command would accept, such as"755"
. If you don't specify this option, the file's permission bits aren't changed at all, meaning it's up to your server's configuration (e.g. umask).

url_template
parameter which is explained in the table below.
Things to Keep in Mind
- Your server might be unresponsive from time to time. Since (S)FTP servers are harder to scale, we see this happen a lot. As a result, if this Robot fails to store one of your files, it will retry to store the file 5 times over 15 minutes.
- This also means that when you provided the wrong credentials (when testing for example) Assemblies can take up to 15 minutes to complete.
- If an Assembly has an export Step and takes long to execute, it is almost always due to the export Step having wrong credentials or the server being unreachable.
This robot uses SSH keys, which offer more security at the trade-off of a moderate degree of complexity in setting up. If you prefer a less secure, but easier-to-setup solution, then please have a look at our /ftp/store and /ftp/import Robots.
Installation on Your Server
The method explained here is slightly more elaborate than handing out an SSH account with an authorized public key, but is more secure as the user will not be able to traverse outside their home directory. This way, even if the user account is compromised at some point, the accessible data would be recently uploaded files.
The following explains how to create a dedicated user and group for Transloadit, and restrict access as shown in this article.
First, let's create a dedicated group and user:
# Change these variables to suit your needs.
# For additional security, use a randomly picked username.
TL_USER="random873"
TL_PUBLIC_PATH="uploads"
groupadd sftponly
useradd -g sftponly -m ${TL_USER}
# This line sets a random 20-character password for the user.
# We work with keys, but this is required because some operating systems will
# consider the account locked without one.
echo "${TL_USER}:$(cat /dev/urandom | tr -dc _A-Z-a-z-0-9 | head -c20)" |chpasswd
mkdir -p /home/${TL_USER}/.ssh /home/${TL_USER}/${TL_PUBLIC_PATH}
echo "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA57GdwNLqsWz03X8MBEe4KoMSY2HOURjnUUe9zeTivASI+BLEe3cZcuJjsEBaRpISvCH04hosWUI0H4BQeB1dZZUUW1s4ttnVohCD9CfNiXJ7pwJAvgWb01dTW4YUWFKUTpTeUwQzgcNVLDtSVaQOYh4lAKvCZEcz17X9iZ7AeSEuQKe+QsrcwQoBdSpQ6FnzKwSZsggK81dPiGIW9Cw2z/EZWJpl9QBTYhw25NbNRtZj3fXVbrejnQQ985eZ6TlrvQFpUVwyk0QNHDsN+7zVISM3eXNpxof+vJyQNDLN9tb8vNPf/HXuw7MDJWMphrQevF5V26aMzszl3ZeO1779Mw== sftp@transloadit.com" >> /home/${TL_USER}/.ssh/authorized_keys
chown -R ${TL_USER}.sftponly /home/${TL_USER}
chown root.root /home/${TL_USER}
chmod -R 600 /home/${TL_USER}/.ssh /home/${TL_USER}/${TL_PUBLIC_PATH}
chmod -R u+X /home/${TL_USER}/.ssh /home/${TL_USER}/${TL_PUBLIC_PATH}
Make sure to change ${TL_USER}
and ${TL_PUBLIC_PATH}
to suit your needs. Remember to use a random username for additional security.
Please also give the subfolder where you intend to store your files sufficient permissions for your user to be able create sub-directories via mkdir
.
A combination of chown
and chmod
should achieve this.
Next, we will set up SSH to cage SFTP users in their home directory, and deny them regular shell access.
Enter ${EDITOR} /etc/ssh/sshd_config
, and then find and comment out this line:
# Subsystem sftp /usr/lib/openssh/sftp-server
At the bottom of the same file, add the following:
Subsystem sftp internal-sftp
Match group sftponly
ChrootDirectory /home/%u
X11Forwarding no
AllowTcpForwarding no
ForceCommand internal-sftp
Finally, enter /etc/init.d/ssh restart
to reflect the changes made.
Demos featuring the /sftp/store Robot
- Apply a watermark to an image and store everything over SFTP
- Copy files from Amazon S3 to SFTP servers
Blog posts
We wrote the following posts about the /sftp/store Robot on our blog:
- Kicking Transloadit Into Gear for the New Year February 1, 2015
- Introducing Our New /sftp/import Robot October 30, 2012
- Releasing Our FTP Robot May 29, 2012
- Releasing Our SFTP Robot and a New Homepage August 21, 2011
- Renaming Some Robots April 7, 2010
Export files to Openstack/Swift

The /swift/store Robot exports encoding results to Openstack Swift buckets.
The URL to the result file in your Openstack bucket will be returned in the Assembly Status JSON.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your swift bucket, key, secret and region. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:"bucket"
,"host"
,"key"
,"secret"
. -
path
string ⋅ default:"${unique_prefix}/${file.url_name}"
The path at which the file is to be stored. This may include any available Assembly variables. -
acl
string ⋅ default:"public-read"
The permissions used for this file. This can be"public-read"
or"private"
. -
headers
object ⋅ default:{ "Content-Type": file.mime }
An object containing a list of headers to be set for this file on swift Spaces, such as{ FileURL: "${file.url_name}" }
. This can also include any available Assembly Variables. Object Metadata can be specified usingx-amz-meta-*
headers. Note that these headers do not support non-ASCII metadata values. -
sign_urls_for
integerThis parameter provides signed urls in the result JSON (in thesigned_ssl_url
property). The number that you set this parameter to is the url expiry time in seconds. If this parameter is not used, no url signing is done.

url_template
parameter which is explained in the table below.
Demos featuring the /swift/store Robot
Export files to Vimeo

The /vimeo/store Robot exports encoding results to vimeo.
acl : ['string', 'notEmpty', ['anybody', 'contacts', 'disable', 'nobody', 'password', 'unlisted', 'users']], downloadable: ['boolean', 'notEmpty'], password : ['string', 'notEmpty'],
Note that this Robot only accepts videos.
Important Vimeo's API limits the number of concurrent uploads per minute by your Vimeo account plan type. To see how many videos can be uploaded at a time based on your Vimeo accounts type, click the following link.
Installation
Since vimeo works with OAuth you will need to generate Template Credentials in order to use this Robot.
To change the title
or description
per video we recommend to inject variables into your Template.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredThe authentication Template credentials used for your vimeo account. You can generate them on the Template Credentials page. You will be redirected to a Vimeo verification page. Accept the presented permissions and you will be good to go. -
title
string requiredThe title of the video to be displayed on vimeo. -
description
string requiredThe description of the video to be displayed on vimeo. -
acl
stringControls access permissions for the video. Here are the valid values:"anybody"
- Anyone can access the video."contacts"
- Only those who follow the owner on Vimeo can access the video."disable"
- The video is embeddable, but it's hidden on Vimeo and can't be played."nobody"
- No one except the owner can access the video."password"
- Only those with the password can access the video."unlisted"
- Only those with the private link can access the video."users"
- Only Vimeo members can access the video. -
password
stringThe password to access the video ifacl
is"password"
. -
showcases
arrayAn array of string IDs of showcases that you want to add the video to. The IDs can be found when browsing Vimeo. For examplehttps://vimeo.com/manage/showcases/[SHOWCASE_ID]/info
. The default is[]
. -
downloadable
booleanWhether or not the video can be downloaded from the Vimeo website. Default isfalse
. Only set this totrue
if you have unlocked this feature in your Vimeo accounting by upgrading to their "Pro" plan. If you use while on their Freemium plan, the Vimeo API will return an"Invalid parameter supplied"
error.

url_template
parameter which is explained in the table below.
Demos featuring the /vimeo/store Robot
Export files to Wasabi

The /wasabi/store Robot exports encoding results to Wasabi buckets.
The URL to the result file will be returned in the Assembly Status JSON.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredPlease create your associated Template Credentials in your Transloadit account and use the name of your Template Credentials as this parameter's value. They will contain the values for your wasabi bucket, host, key and secret. While we recommend to use Template Credentials at all times, some use cases demand dynamic credentials for which using Template Credentials with their static nature is too unwieldy. If you have this requirement, feel free to use the following parameters instead:"bucket"
,"host"
,"key"
,"secret"
. -
path
string ⋅ default:"${unique_prefix}/${file.url_name}"
The path at which the file is to be stored. This may include any available Assembly variables. -
acl
string ⋅ default:"public-read"
The permissions used for this file. This can be"public-read"
or"private"
. -
headers
object ⋅ default:{ "Content-Type": file.mime }
An object containing a list of headers to be set for this file on wasabi Spaces, such as{ FileURL: "${file.url_name}" }
. This can also include any available Assembly Variables. Object Metadata can be specified usingx-amz-meta-*
headers. Note that these headers do not support non-ASCII metadata values. -
sign_urls_for
integerThis parameter provides signed urls in the result JSON (in thesigned_ssl_url
property). The number that you set this parameter to is the url expiry time in seconds. If this parameter is not used, no url signing is done.

url_template
parameter which is explained in the table below.
Demos featuring the /wasabi/store Robot
Export files to YouTube

The /youtube/store Robot exports encoding results to YouTube.
Note that this Robot only accepts videos.
Installation
Since YouTube works with OAuth you will need to generate Template Credentials in order to use this Robot.
To change the title
, description
, category
, or keywords
per video we recommend to inject variables into your Template.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
credentials
string requiredThe authentication Template credentials used for your YouTube account. You can generate them on the Template Credentials page. Simply add the name of your YouTube channel, and you will be redirected to a Google verification page. Accept the presented permissions and you will be good to go. -
title
string requiredThe title of the video to be displayed on YouTube. Note that since the YouTube API requires titles to be within 80 characters, longer titles may be truncated. -
description
string requiredThe description of the video to be displayed on YouTube. This can be up to 5000 characters. -
category
string requiredThe category to which this video will be assigned. These are the valid values:"autos & vehicles"
,"comedy"
,"education"
,"entertainment"
,"film & animation"
,"gaming"
,"howto & style"
,"music"
,"news & politics"
,"people & blogs"
,"pets & animals"
,"science & technology"
,"sports"
,"travel & events"
, -
keywords
string requiredTags used to describe the video, separated by commas. These tags will also be displayed on YouTube. -
visibility
string requiredDefines the visibility of the uploaded video. This can be"public"
,"private"
, or"unlisted"
.

url_template
parameter which is explained in the table below.
Demos featuring the /youtube/store Robot
Blog posts
We wrote the following posts about the /youtube/store Robot on our blog:
- To Everyone Using the /youtube/store Robot July 11, 2013
- Adding Support for Storage on YouTube January 25, 2012
Content Delivery (beta)
Serve files to web browsers

The /file/serve Robot serves files to web browsers.
When you want Transloadit to tranform files on the fly, you can use this Robot to determine which Step of a Template should be served to the end-user, as well as set extra information on the served files, such as headers.
Parameters
-
use
string / array of strings / object requiredSpecifies which Step(s) to use as input.-
You can pick any names for Steps except
":original"
(reserved for user uploads handled by Transloadit) -
You can provide several Steps as input with arrays:
"use": [ ":original", "encoded", "resized" ]
That’s likely all you need to know about
use
, but you can view advanced use cases:› Advanced use cases
-
Step bundling. Some Robots can gather several Step results for a single invocation. For example, the /file/compress Robot would normally create one archive for each file passed to it. If you'd set
bundle_steps
to true, however, it will create one archive containing all the result files from all Steps you give it. To enable bundling, provide an object like the one below to theuse
parameter:
This is also a crucial parameter for the /video/adaptive Robot, otherwise you'll generate 1 playlist for each viewing quality."use": { "steps": [ ":original", "encoded", "resized" ], "bundle_steps": true }
Keep in mind that all input Steps must be present in your Template. If one of them is missing (for instance it is rejected by a filter), no result is generated because the Robot waits indefinitely for all input Steps to be finished. Here’s a demo that showcases Step bundling. -
Group by original. Sticking with the /file/compress Robot example, you can set
group_by_original
totrue
, in order to create a separate archive for each of your uploaded or imported files, instead of creating one archive containing all originals (or one per resulting file). This is important for for the /media/playlist Robot where you'd typically set:"use": { "steps": [ "segmented" ], "bundle_steps": true, "group_by_original": true }
-
Fields. You can be more discriminatory by only using files that match a field name by
setting the
fields
property. When this array is specified, the corresponding Step will only be executed for files submitted through one of the given field names, which correspond with the strings in thename
attribute of the HTML file input field tag for instance. When using a back-end SDK, it corresponds withmyFieldName1
in e.g.:$transloadit->addFile('myFieldName1', './chameleon.jpg')
. This parameter is set totrue
by default, meaning all fields are accepted. Example:"use": { "steps": [ ":original" ], "fields": [ "myFieldName1" ] }
-
Use as. Sometimes Robots take several inputs. For instance, the
/video/merge Robot can create a slideshow
from audio and images. You can map different Steps to the appropriate inputs.
Example:
Sometimes the ordering is important, for instance, with our concat Robots. In these cases, you can add an index that starts at 1. You can also optionally filter by the multipart field name. Like in this example, where all files are coming from the same source (end-user uploads), but with different"use": { "steps": [ { "name": "audio_encoded", "as": "audio" }, { "name": "images_resized", "as": "image" } ] }
<input>
names: Example:
For times when it is not apparent where we should put the file, you can use Assembly Variables to be specific. For instance, you may want to pass a text file to the /image/resize Robot to burn the text in an image, but you are burning multiple texts, so where do we put the text file? We specify it via"use": { "steps": [ { "name": ":original", "fields": "myFirstVideo", "as": "video_1" }, { "name": ":original", "fields": "mySecondVideo", "as": "video_2" }, { "name": ":original", "fields": "myThirdVideo", "as": "video_3" } ] }
${use.text_1}
, to indicate the first text file that was passed. Example:"watermarked": { "robot": "/image/resize", "use" : { "steps": [ { "name": "resized", as: "base" }, { "name": "transcribed", as: "text" }, ], }, "text": [ { "text" : "Hi there", "valign": "top", "align" : "left", }, { "text" : "From the 'transcribed' Step: ${use.text_1}", "valign" : "bottom", "align" : "right", "x_offset": 16, "y_offset": -10, } ] }
-
You can pick any names for Steps except
-
headers
object ⋅ default:{ "Access-Control-Allow-Headers": "X-Requested-With, Content-Type, Cache-Control, Accept, Content-Length, Transloadit-Client, Authorization", "Access-Control-Allow-Methods": "POST, GET, PUT, DELETE, OPTIONS", "Access-Control-Allow-Origin" : "*", "Cache-Control": "public, max-age=259200, s-max-age=86400", "Content-Type": "${file.mime}; charset=utf-8", "Transfer-Encoding": "chunked", "Transloadit-Assembly": .., "Transloadit-RequestID": .. }
An object containing a list of headers to be set for a file as we serve it to a CDN/web browser, such as{ FileURL: "${file.url_name}" }
which will be merged over the defaults, and can include any available Assembly Variable.