Create a new Assembly
https://api2.transloadit.com/assemblies
An Assembly can process and export files. Assembly Instructions determine how we should process them. Instructions can be passed in directly (inside a steps
parameter), or be saved in a Template (referred to in a template_id
parameter). Templates allow you to re-use instructions, evolve them without deploying your app, and to not expose any secrets to where your app is deployed.
We accept multipart/form-data
POST requests to accommodate regular <form>
uploads to our service (as well as XHR / SDK usage).
Multiple files can be included as part of this request.
POST fields
-
Passing
signature
is optional. For more information please check Signature Authentication. -
Passing
params
is required. It should contain a JSON encoded object with the keys as shown in the table below.
params
or signature
) here. They can be used as variables to make your Assembly Instructions dynamic.
Supported keys inside the params
field
-
auth
ObjectrequiredContains at least your Transloadit Auth Key in the
key
property.If you enable Signature Authentication, you'll also set an expiry date for the request in the
expires
property like so:{ "key": "23c96d084c744219a2ce156772ec3211", "expires": "2023/01/01 16:53:14+00:00" }
The
referer
property is a regular expression to match against the HTTP referer of this upload, such as"example\.org"
. Specify this key to make sure that uploads only come from your domain.Uploads without a referer will always pass (as they are turned off for some browsers) making this useful in just a handful of use cases. For details about regular expressions, see Mozilla's RegExp documentation.
The
max_size
property can be used to set a maximum size that an upload can have in bytes, such as1048576
(1 MB). Specify this to prevent users from uploading excessively large files.When using this key, make sure that it is specified as a hidden
max_size
form field, since settingmax_size
in a Template will have no effect.The file size is checked as soon as the upload is started and if it exceeds the maximum size, the entire upload process is canceled and the Assembly will error out, even if it contains files that do not exceed the
max_size
limitation.If you want to just ignore the files that exceed a certain size, but process all others, then please use 🤖/file/filter.
-
steps
Object ⋅ default:{}
Contains Assembly Instructions. Example:
"encoded": { "use": ":original", "robot": "/video/encode", "preset": "iphone-high" }, "thumbed": { "use": "encoded", "robot": "/video/thumbs", "count": 8 }
Note: By default you may use the
steps
parameter to overrule Template Steps at runtime. If you setallow_steps_override
tofalse
thensteps
andtemplate_id
will be mutually exclusive and you may only supply one of these parameters. See Overruling Templates at Runtime. -
template_id
String ⋅ default:""
The ID of the Template that contains your Assembly Instructions. If you set
allow_steps_override
tofalse
thensteps
andtemplate_id
will be mutually exclusive and you may only supply one of these parameters. -
notify_url
String ⋅ default:""
Transloadit can send a Pingback to your server when the Assembly is completed. We'll send the Assembly status in a form url-encoded JSON string inside of a
transloadit
field in a multipart POST request to the URL supplied here. -
fields
Object ⋅ default:{}
An object of string to string pairs (name -> value) that can be used as Assembly Variables, just like additional form fields can. For example, to dynamically have us resize images based on an end-user provided width, you could use
${fields.user_width}
in your Assembly Instructions, and either post an<input name="user_width" value="800" />
or supply thisfields
param with the following object:{ "user_width": 800 }
-
allow_steps_override
Boolean ⋅ default: trueSet this to
false
to disallow Overruling Templates at Runtime. If you set this tofalse
thentemplate_id
andsteps
will be mutually exclusive and you may only supply one of those parameters. Recommended when deploying Transloadit in untrusted environments. This makes sense to set as part of a Template, rather than on the Assembly itself when creating it.
Response
Here’s an example response body:
For more information about the response, please refer to our documentation for the Assembly Status response.