1. API Basics

1.1 Available APIs

Transloadit provides a simple JSON REST API that can be used for creating new assemblies, checking the status of an assembly, or deleting assemblies.

There is also an API for managing templates.

Most API calls will require the following parameters:

Parameter Description
params This is a JSON string containing the parameters for this request. This must include an auth.key parameter to identify your account. See Authentication.
signature The signature for the given params if you have enabled signature authentication (disabled by default).
For details about how to calculate this value, see Authentication.

1.2 API Security

There are two means built into the Transloadit API to access it securely:

  1. You can access all our http URLs listed below in the Assembly API and Template API sections also via https.

  2. We offer signature authentication, which is complex enough to deserve its own section.

1.3 Rate Limiting

We enforce rate limits to guarantee that no customers are adversely affected by the usage of any given customer. Bulk imports and buggy integration code can result in too many requests being sent in a short period of time, leading to excessively large bills or increased queue times.

For now, we limit only the number of assemblies that a customer can create, to 250 per minute. This is more than enough for reasonable usage.

Customers that hit the rate limit will receive a 413 RATE_LIMIT_REACHED error. The JSON payload for this error contains an info.retryIn parameter that indicates the number of seconds remaining until another assembly can be created. We provide this information to make sure imports are throttled as little as necessary, to facilitate smooth customer integration.

We can set higher rate-limits on a per-customer basis. Please contact support if you need this.


2. Signature authentication

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

2.1 The idea in 3 simple steps

You get your Auth key and a private Auth secret, from your account page and follow these steps (with some pseudo code):

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

And then we will happily accept your assembly steps as long as you POST this before the expiration date.

Now into more detail.

2.2 Enabling signature authentication

To require that requests against your account be signed:

  1. Go to the API Credentials page under "My Account" -> "Account settings".
  2. Select the "Enable signature authentication" checkbox.
  3. Click the update button.

2.3 Basic usage

The typical params field for a Transloadit template or assembly request is usually as follows:

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

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

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

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

To calculate the signature for this request.

  1. Stringify the above JavaScript object into a JSON string.
  2. Calculate an RFC 2104-compliant HMAC hex signature on the string, with your auth secret as the key, and SHA1 as the hash algorithm.
  3. Add a signature field to your post request (or as a hidden field in your form), with the signature created in step 2.

2.4 Example

Assuming that you're using the following parameters,

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

you should sign a JSON string such as the following.

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

So, given an auth secret of d805593620e689465d7da6b8caf2ac7384fdb7e9, the resulting signature would be as follows:

fec703ccbe36b942c90d17f64b71268ed4f5f512

And your final request would look like this:

params=%7B%22auth%22%3A%7B%22expires%22%3A%222009%2F11%2F27%2016%3A53%3A14%2B00%3A00%22%2C%22key%22%3A%222b0c45611f6440dfb64611e872ec3211%22%7D%7D&signature=4e14c4b0a16d01991c0f7276d68e03ded49cc212

2.5 Calculating signatures when using templates

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

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

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

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

2.6 Signature authentication for notifications

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

Here is some example NodeJS code to calculate the signature yourself to see that the sent signature matches:

  // This is the signature contained in the "signature" POST field.
  var sentSignature = '123129120manasdnlasdjakjsdkj';

  // This is the data contained in the "transloadit" POST field.
  var sentData = { steps: {} };

  // Stringify the sent data.
  var statusString = JSON.stringify(sentData);

  var secret = 'YOUR_ACCOUNT_SECRET_KEY';
  var signature = crypto
      .createHmac('sha1', secret)
      .update(new Buffer(statusString, 'utf-8'))
      .digest('hex');

  if (signature === sentSignature) {
    console.log('IS VALID!');
  } else {
    console.log('SOMEONE IS TRYING TO HACK US!');
  }

2.7 Implementations

2.7.1 Ruby

Toggle code

require 'rubygems'
require 'openssl'
require 'json'

auth_key    = 'YOUR-AUTH-KEY'
auth_secret = 'YOUR-AUTH-SECRET'

params = JSON.generate({
  :auth => {
    :expires => Time.now.utc.strftime('%Y/%m/%d %H:%M:%S+00:00'),
    :key     => auth_key,
  },
  :template_id => 'YOUR_TEMPLATE_ID'
})
digest    = OpenSSL::Digest::Digest.new('sha1')
signature = OpenSSL::HMAC.hexdigest(digest, auth_secret, params)

2.7.2 PHP

Toggle code
$authKey    = 'YOUR-AUTH-KEY';
$authSecret = 'YOUR-AUTH-SECRET';

$params = json_encode(array(
  'auth' => array(
    'expires' => gmdate('Y/m/d H:i:s+00:00', strtotime('+1 hour')),
    'key'     => $authKey,
  ),
  'template_id' => 'YOUR_TEMPLATE_ID'
));

// json_encode escapes slashes by default, which would result in a wrong signature
// If you run PHP 5.4, you could also use the JSON_UNESCAPED_SLASHES bitmask in
// the second argument to json_encode
$params = str_replace('\/','/', $params);

$signature = hash_hmac('sha1', $params, $authSecret);

2.7.3 NodeJS

Toggle code
var crypto = require('crypto');

utcDateString = function(time) {
  function pad(val, len) {
    val = String(val);
    len = len || 2;
    while (val.length < len) val = "0" + val;
    return val;
  }

  var now = new Date();
  now.setTime(time);

  var utc = new Date(
    Date.UTC(
      now.getFullYear(),
      now.getMonth(),
      now.getDate(),
      now.getHours(),
      now.getMinutes(),
      now.getSeconds()
    )
  );

  var cDate  = utc.getDate();
  var cMonth = utc.getMonth();
  var cYear  = utc.getFullYear();
  var cHour  = utc.getHours();
  var cMin   = utc.getMinutes();
  var cSec   = utc.getSeconds();

  var result = cYear + '/' + pad((cMonth + 1)) + '/' + pad(cDate);
  result += ' ' + pad(cHour) + ':' + pad(cMin) + ':' + pad(cSec) + '+00:00';

  return result;
};

// 3 hours from now (this must be milliseconds)
var expiresIn  = 3 * 60 * 60 * 1000;
var expires    = utcDateString((+new Date()) + expiresIn);

var authKey    = 'YOUR-AUTH-KEY';
var authSecret = 'YOUR-AUTH-SECRET';

var params = {
  'auth': {
    'expires': expires,
    'key': authKey
  },
  template_id: 'YOUR_TEMPLATE_ID'
  // your other params like template_id, notify_url, etc.
};
var paramsString = JSON.stringify(params);

var signature = crypto
    .createHmac('sha1', authSecret)
    .update(new Buffer(paramsString, 'utf-8'))
    .digest('hex');

console.log(signature);

2.8 Additional authentication options

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

Key Description
referer A regular expression to match against the HTTP referer of this upload, such as "example\.org". Specify this key to make uploads come only from your domain. Uploads without a referer will always pass (as they are disabled for some browsers). For details about regular expressions, see Mozilla's RegExp documentation.
max_size The maximum size an upload can have in bytes, such as 1048576 (1 MB). Specify this to prevent users from uploading excessively large files. When using this key, make sure that it is specified as a hidden max_size form field, as setting max_size in a template will have no effect. The file size is checked as soon as the upload is started, and if it exceeds the maximum size, the entire upload process is canceled, even if it contains files that do not exceed the max_size limitation. If you want to just ignore the files that exceed a certain size, but process all others, then please use our file filtering capabilities.

3. Assembly API

3.1 Create a new assembly

Request:

POST http://api2.transloadit.com/assemblies


Required parameters:

A POST field named params is mandatory. It contains parameters in an encoded JSON string. Possible parameters are: auth, steps, template_id and notify_url.


Optional parameters:

Supplying a POST field named signature (containing a signature string) is optional here. For more information about signatures, please check Authentication.


Description:

Creates a new assembly. Multiple files can be included as part of a multipart/form-data request.


The response:

Please refer to our separate the response page.


3.2 Retrieve the status of an assembly

Request:

GET {assembly_url}?signature={signature}


Requirement parameters:

None


Optional parameters:

Supplying the URL query field signature is optional. For more information about signatures, please check Authentication.


Description:

Queries the status of an assembly. assembly_url is the unique url returned when the assembly was created. This request can be issued by anyone who knows the assembly_url. Make sure to not share your assembly_url's or assembly_id's with anybody.


The response:

Please refer to our separate the response page.


3.3 Cancel an assembly

Request:

DELETE {assembly_url}?signature={signature}


Required parameters:

None


Optional parameters:

Supplying the URL query field signature is optional. For more information about signatures, please check Authentication.


Description:

Cancels an assembly or upload that is still in progress. assembly_url is the unique url returned when the assembly was created. This request can be issued by anyone who knows the assembly_url. Make sure to not share your assembly_url's or assembly_id's with anybody.


The response:

Either returns the latest assembly status (in JSON) or a JSON error ASSEMBLY_NOT_FOUND. Please also refer to our separate the response page.


3.4 Replay assembly

Request:

POST http://api2.transloadit.com/assemblies/{assembly_id}/replay


Required parameters:

Parameters encoded in a POST field named params JSON string, and a POST field named signature containing a signature string are mandatory. For more information about these two, please check Authentication. Possible params fields are: auth, steps, notify_url, reparse_template.


Optional parameters:

None


Description:

Replays an assembly.

Specify a new notify_url parameter in params to avoid replaying the url already specified for the assembly.

Specify 1 for the reparse_template parameter in params to reparse the template used in your assembly (useful if the template changed in the meantime). Otherwise, specify 0 (the default value) to replay the identical steps used in the assembly.

Specify the steps parameter in params to override the steps of the original assembly being replayed.


The response:

Either returns with the success code ASSEMBLY_REPLAYING or with the proper error code detailing what went wrong. Please also refer to our separate the response page for possible error codes.


3.5 Retrieve assembly list

Request:

GET http://api2.transloadit.com/assemblies?params={params}&signature={signature}

Required parameters:

Parameters url-encoded in a JSON string in a url query field named params, and a url query field named signature containing a signature string. For more information about these two, please check Authentication.

Possible params fields are: auth, page, pagesize, type, fromdate, todate, keywords. Please see descriptions for the params fields below.


Optional parameters:

None


Description:

Retrieves a list of assemblies for your account.

params can contain the following keys:

Parameter Description
page Specifies the current page, within the current pagination. The default value is 1.
pagesize Specifies how many assemblies to be received per API request, which is useful for pagination. The maximum value is 5000. The default value is 50.
type Specifies the types of assemblies to be retrieved. This can be one of uploading, executing, canceled, completed, failed or request_aborted. The default value is all.
fromdate Specifies the minimum assembly creation date/time. Only assemblies after this time will be retrieved. Use the format Y-m-d H:i:s.
todate Specifies the maximum assembly creation date/time. Only assemblies before this time will be retrieved. Use the format Y-m-d H:i:s.
keywords Specifies keywords to be matched in the assembly JSON. The assembly properties checked include the id, redirect_url, and notify_url properties, as well as error messages and files used.

The response:

Either returns with the error code ASSEMBLY_LIST_ERROR or with a JSON list of found assemblies. Please also refer to our separate the response page.


4. Notification API

4.1 Retrieve assembly notification list

Request:

GET http://api2.transloadit.com/assembly_notifications?params={params}&signature={signature}

Required parameters:

Parameters url-encoded in a JSON string in a url query field named params, and a url query field named signature containing a signature string. For more information about these two, please check Authentication.

Possible params fields are: auth, page, pagesize, type and assembly_id. Please see descriptions for the params fields below.


Optional parameters:

None


Description:

Retrieves a list of assembly notifications for your account.

params can contain the following keys:

Parameter Description
page Specifies the current page, within the current pagination. The default value is 1.
pagesize Specifies how many notifications to be received per API request, which is useful for pagination. The maximum value is 5000. The default value is 50.
type Specifies the types of assemblies to be retrieved. This can be one of all (default), successful and failed.
assembly_id Only finds notifications of the assembly whose id is this value.

The response:

Either returns with the error code ASSEMBLY_NOTIFICATION_LIST_ERROR or with a JSON list of found notifications. Please also refer to our separate the response page.


4.2 Replay assembly notification

Request:

POST http://api2.transloadit.com/assembly_notifications/{assembly_id}/replay

The old request URL is now deprecated:
POST http://api2.transloadit.com/assemblies/{assembly_id}/replay_notification


Required parameters:

Parameters encoded in a POST field named params JSON string, and a POST field named signature containing a signature string. For more information about these two, please check Authentication. Possible params fields are: auth, notify_url.


Optional parameters:

Supplying a new notify_url in the params field is optional. You can use this to send the notification to a new URL. If this parameter is not provided, the notification is sent to the notify_url that was specified when the assembly was created.


Description:

Replays an assembly notification, sending the POST request containing the assembly result JSON again to the notify_url that was specified when the assembly was created.


The response:

Either returns with the success code ASSEMBLY_NOTIFICATION_REPLAYED or with the proper error code detailing what went wrong. Please also refer to our separate the response page for possible error codes.


5. Template API

5.1 Create a new template

Request:

POST http://api2.transloadit.com/templates


Required parameters:

A POST field named params is mandatory. It contains parameters in an encoded JSON string. The required parameters are: auth, name (the template name) and template (the template JSON string).

Supplying a POST field named signature (containing a signature string) is also mandatory. For more information about signatures, please check Authentication.


Optional parameters:

None


Description:

Creates a new template.


The response:

On success this request returns a JSON response with the success code TEMPLATE_CREATED, the template id, name and content.

Example:

{
  ok: "TEMPLATE_CREATED",
  template_id: "{the_template_id_string}",
  template_content: "{the_template_content}",
  template_name: "{the_template_name}"
}

On error it contains a JSON response including an error field that contains an error status code and a reason field that contains details on what went wrong.


5.2 Retrieve a template

Request:

GET http://api2.transloadit.com/templates/{template_id}


Requirement parameters:

Supplying a GET query field named signature (containing a signature string) is mandatory. For more information about signatures, please check Authentication.


Optional parameters:

None


Description:

Retrieves the template JSON content for a given template_id.


The response:

On success this request returns a JSON response with the success code TEMPLATE_FOUND and the template id.

Example:

{
  ok: "TEMPLATE_CREATED",
  template_id: "{the_template_id_string}",
  template_content: "{the_template_content}",
  template_name: "{the_template_name}"
}

On error it contains a JSON response including an error field that contains an error status code and a reason field that contains details on what went wrong.


5.3 Edit a template

Request:

PUT http://api2.transloadit.com/templates/{template_id}


Required parameters:

A POST field named params is mandatory. It contains parameters in an encoded JSON string. The required parameters are: auth, name (the new template name) and template (the new template JSON string).

Note If you do not wish to change the name of the template, then please provide the old name of the template as the new name.

Supplying a POST field named signature (containing a signature string) is also mandatory. For more information about signatures, please check Authentication.


Optional parameters:

None


Description:

Updates the template represented by template_id with the new template name and template json.


The response:

Returns a JSON string with { ok: "TEMPLATE_UPDATED" } upon success. Upon error, the error key will contain the corresponding error status code.


5.4 Delete a template

Request:

DELETE http://api2.transloadit.com/templates/{template_id}


Required parameters:

Supplying a POST field named signature (containing a signature string) is mandatory. For more information about signatures, please check Authentication.


Optional parameters:

None


Description:

Deletes a template. Assemblies that make use of this template will no longer work.


The response:

Returns a JSON string with { ok: "TEMPLATE_DELETED" } upon success. Upon error, the error key will contain the corresponding error status code.


5.5 Retrieve template list

Request:

GET http://api2.transloadit.com/templates?params={params}&signature={signature}

Required parameters:

Parameters url-encoded in a JSON string in a url query field named params, and a url query field named signature containing a signature string. For more information about these two, please check Authentication.

Possible params fields are: auth, page, pagesize, sort, order, fromdate, todate, fields. Please see descriptions for the params fields below.


Optional parameters:

None


Description:

Retrieves a list of assemblies for your account.

params can contain the following keys:

Parameter Description
page Specifies the current page, within the current pagination. The default value is 1.
pagesize Specifies how many templates to be received per API request, which is useful for pagination. The maximum value is 5000.
sort The field to sort by. Default value is "created". Valid values are any available fields listed in the fields parameter description below.
order The sort direction. Can be "desc" for descending (default) or "asc" for ascending.
fields An array of fields to retrieve for each template. The default values is ["id", "account_id", "name", "json", "created", "modified", "deleted"] which are all available fields. Valid values here are arrays that contain one or more of these field names.
fromdate Specifies the minimum template creation date/time. Only templates after this time will be retrieved. Use the format Y-m-d H:i:s.
todate Specifies the maximum template creation date/time. Only templates before this time will be retrieved. Use the format Y-m-d H:i:s.

The response:

Either returns with the error code TEMPLATE_LIST_ERROR or with a JSON list of found templates.


6. API responses

6.1 Transloadit response format

Transloadit uses a single response format for creating and querying assemblies, appending responses to upload forms, and sending notifications.

The following is a full example of a Transloadit response. Since files are processed in parallel, the ordering for results does not necessarily follow the same order as uploads. To match a result with an upload, such as for multi-upload enabled forms, match the original_id field of the result with the original_id field of the uploads part of the response.

6.2 Example response

Toggle code
{
  ok: "ASSEMBLY_COMPLETED",
  message: "The assembly was successfully completed.",
  assembly_id: "ed70803b0ee2351e1e5660ebd600bfe9",
  assembly_url: "http://api2.jane.transloadit.com/assemblies/ed70803b0ee2351e1e5660ebd600bfe9",
  bytes_received: 1455195,
  bytes_expected: 1455195,
  client_agent: "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.5; en-US; rv:1.9.2.13) Gecko/20101203 Firefox/3.6.13",
  client_ip: "91.64.59.17",
  client_referer: "http://localtransloadit.com/demos/video-thumbs/extract-from-encoding",
  start_date: "2011/02/07 12:54:07 GMT",
  upload_duration: 6.89,
  execution_duration: 2.653,
  fields: {},
  uploads: [{
      id: "f2a65e2da71babd9dc5778a7a49af992",
      path: "/mnt/tmp/upload/2bc96b5ee89854d3523618b0159f7d26.flv",
      name: "shortest_video.flv",
      basename: "shortest_video",
      ext: "flv",
      size: 1454296,
      mime: "video/x-flv",
      type: "video",
      field: "test_file",
      original_id: "f2a65e2da71babd9dc5778a7a49af992",
      url: "http://tmp.jane.transloadit.com/upload/2bc96b5ee89854d3523618b0159f7d26.flv",
      meta: {
        duration: 7.99,
        width: 854,
        height: 480,
        framerate: 25,
        video_bitrate: 2929688,
        video_codec: "ffflv",
        audio_bitrate: 64000,
        audio_samplerate: 44100,
        audio_channels: 2,
        audio_codec: "mp3",
        "seekable":true,
        "date_recorded": null,
        "date_file_created": null,
        date_file_modified: "2011/02/07 12:54:13 GMT",
        "device_vendor": null,
        "device_name": null,
        "device_software": null,
        "latitude": null,
        "longitude": null,
        "rotation": null
      },
      _: {
        exiftool: {
          SourceFile: "/mnt/tmp/upload/2bc96b5ee89854d3523618b0159f7d26.flv",
          ExifToolVersion: 7.89,
          FileName: "2bc96b5ee89854d3523618b0159f7d26.flv",
          Directory: "/mnt/tmp/upload",
          FileSize: "1420 kB",
          FileModifyDate: "2011:02:07 12:54:13+00:00",
          FileType: "FLV",
          MIMEType: "video/x-flv",
          Duration: "7.99 s",
          ImageWidth: 854,
          ImageHeight: 480,
          VideoBitrate: 2929688,
          FrameRate: 25,
          VideoCodecID: 2,
          AudioBitrate: 62500,
          AudioSampleSize: 16,
          Stereo: "Yes",
          AudioCodecID: 2,
          FileSizeBytes: 1454296,
          AudioEncoding: "MP3",
          AudioSampleRate: 44100,
          AudioSampleBits: 16,
          AudioChannels: "2 (stereo)",
          VideoEncoding: "Sorensen H.263",
          ImageSize: "854x480"
        },
        iphoneStrings: [],
        identify: {
          "frame_count": null
        },
        midentify: {
          video_id: "0",
          audio_id: "0",
          clip_info_name0: "duration",
          clip_info_value0: "8",
          clip_info_name1: "width",
          clip_info_value1: "854",
          clip_info_name2: "height",
          clip_info_value2: "480",
          clip_info_name3: "videodatarate",
          clip_info_value3: "2930",
          clip_info_name4: "framerate",
          clip_info_value4: "25",
          clip_info_name5: "videocodecid",
          clip_info_value5: "2",
          clip_info_name6: "audiodatarate",
          clip_info_value6: "62",
          clip_info_name7: "audiosamplerate",
          clip_info_value7: "44100",
          clip_info_name8: "audiosamplesize",
          clip_info_value8: "16",
          clip_info_name9: "stereo",
          clip_info_value9: "true",
          clip_info_name10: "audiocodecid",
          clip_info_value10: "2",
          clip_info_name11: "filesize",
          clip_info_value11: "1454296",
          clip_info_n: "12",
          filename: "/mnt/tmp/upload/2bc96b5ee89854d3523618b0159f7d26.flv",
          demuxer: "lavfpref",
          video_format: "FLV1",
          video_bitrate: "3000000",
          video_width: "854",
          video_height: "480",
          video_fps: "25.000",
          video_aspect: "0.0000",
          audio_format: "85",
          audio_bitrate: "64000",
          audio_rate: "44100",
          audio_nch: "2",
          start_time: "0.00",
          length: "7.99",
          seekable: "1",
          chapters: "0",
          video_codec: "ffflv",
          audio_codec: "mp3",
          exit: "EOF"
        }
      }
    }
  ],
  last_seq: 9,
  results: {
    extracted_thumbs: [{
        id: "9c197c9985b96ed3cb72a7a03468adb5",
        name: "shortest_video.jpg",
        basename: "shortest_video",
        ext: "jpg",
        size: 12253,
        mime: "image/jpeg",
        type: "image",
        field: "test_file",
        original_id: "f2a65e2da71babd9dc5778a7a49af992",
        url: "http://tmp.jane.transloadit.com/scratch/3c3d0212bc9055327a1150015b0ca5f8",
        meta: {
          duration: 8.05,
          width: 640,
          height: 480,
          framerate: 25,
          video_bitrate: 500000,
          video_codec: "ffflv",
          audio_bitrate: 64000,
          audio_samplerate: 44100,
          audio_channels: 2,
          audio_codec: "mp3",
          "seekable":true,
          "date_recorded": null,
          "date_file_created": null,
          date_file_modified: "2011/02/07 12:54:16 GMT",
          "device_vendor": null,
          "device_name": null,
          "device_software": null,
          "latitude": null,
          "longitude": null,
          "rotation": null,
          thumb_index: 6,
          thumb_offset: 6.2611111111111,
          "title": null,
          "description": null,
          "location": null,
          "city": null,
          "state": null,
          "country": null,
          "country_code": null,
          "keywords": null,
          "aperture": null,
          "exposure_compensation": null,
          "exposure_mode": null,
          "exposure_time": null,
          "flash": null,
          "focal_length": null,
          "f_number": null,
          "iso": null,
          "light_value": null,
          "metering_mode": null,
          "shutter_speed": null,
          "white_balance": null,
          "frame_count": null
        }
      }
      ...
}

6.3 Description of the response

Key Description
ok Indicates a successful status. If the assembly encountered an error, the error key below is used instead of this key.
error Indicates an error status. This key is only present if the assembly failed.
message A human-readable message explaining the state of this assembly. This is not always present.
assembly_id The unique ID of this assembly. You can store this in a database when an assembly is created, and use it to match incoming notifications.
assembly_url The unique url used to query the current status of this assembly.
bytes_received The number of bytes that have been uploaded to this assembly so far. This is primarily used by the jQuery plugin to display upload progress.
bytes_expected The number of bytes that this assembly expects to be uploaded.
client_agent The user agent (browser) used by the uploader.
client_ip The IP address of the uploader.
client_referer The referrer url of the uploader.
start_date The date and time at which upload started for this assembly.
upload_duration The time taken by the uploader to upload files, in seconds.
execution_duration The time taken by Transloadit to execute this assembly, in seconds.
fields A key/value map of any additional fields present in your form, for integrations that do not use the jQuery plugin.
uploads An array of files uploaded for this assembly. For more information, see the metadata documentation.
results The result files that Transloadit has produced so far. Each key of this object is the name of the step that produced a particular file. As storage robots do not produce files, their step names are not included here.

6.4 Status codes

The following lists the status codes returned by Transloadit, which you can use to handle errors.

6.4.1 OK codes

OK codes are always returned via ok key, like this: {ok: ok_code}.

Code Description
REQUEST_ABORTED The upload connection was closed or timed out before receiving all data.
ASSEMBLY_UPLOADING The assembly is still in the process of being uploaded.
ASSEMBLY_EXECUTING The assembly is currently being executed.
ASSEMBLY_CANCELED The assembly was canceled.
ASSEMBLY_COMPLETED The assembly was completed successfully.

6.4.2 Error codes

Error codes are always returned via the error key, like this: { error: error_code }.

Code Description
INVALID_FORM_DATA The form data is invalid and cannot be parsed.
INVALID_FILE_META_DATA The file is bad and its metadata cannot be parsed
NO_PARAMS_FIELD No params field was given.
INVALID_PARAMS_FIELD The params field or JSON is invalid.
NO_OBJECT_PARAMS_FIELD The params field is not an object.
NO_AUTH_PARAMETER No auth parameter was given.
NO_OBJECT_AUTH_PARAMETER The auth parameter is not an object.
NO_AUTH_KEY_PARAMETER No auth key parameter was given.
INVALID_AUTH_KEY_PARAMETER The given auth key parameter is not a string.
NO_AUTH_EXPIRES_PARAMETER No auth expires parameter was given.
INVALID_AUTH_MAX_SIZE_PARAMETER The auth referer parameter could not be parsed.
MAX_SIZE_EXCEEDED The uploaded file exceeded the maximum file size.
INVALID_AUTH_REFERER_PARAMETER The auth referer parameter could not be parsed.
REFERER_MISMATCH The request came from a disallowed location.
INVALID_AUTH_EXPIRES_PARAMETER The auth expires parameter given could not be parsed.
AUTH_EXPIRED The given auth expires parameter is in the past.
NO_SIGNATURE_FIELD No signature field was given.
INVALID_SIGNATURE The given signature does not match that calculated by Transloadit.
GET_ACCCOUNT_DB_ERROR The account could not be found due to a database error.
GET_ACCOUNT_UNKNOWN_AUTH_KEY The account could not be found due to an unknown auth key.
NO_COUNTRY The account has no country record. Contact support, or update your account information.
NO_PRICING The account has no pricing record. Contact support.
BAD_PRICING The pricing record of the account is invalid. Contact support.
INCOMPLETE_PRICING The pricing record of the account is incomplete. Contact support.
BILL_LIMIT_EXCEEDED The billing limit set for the account has been exceeded this month.
CREDIT_EXCEEDED The account credits have been exceeded. Add a credit card to the profile to resume service.
TEMPLATE_DB_ERROR The template for this request could not be fetched, due to a database error.
TEMPLATE_NOT_FOUND No template was found for the given template_id and account.
TEMPLATE_INVALID_JSON The template contains invalid JSON.
SERVER_404 The method or url is not recognized.
FILE_META_DATA_ERROR A problem occurred extracting metadata from the file.
ASSEMBLY_NOT_FOUND The requested assembly does not exist.
ASSEMBLY_NO_STEPS The assembly does not include a steps parameter.
ASSEMBLY_INVALID_STEPS The assembly steps parameter is not an object.
ASSEMBLY_EMPTY_STEPS The assembly steps parameter is empty.
ASSEMBLY_STEP_INVALID One the assembly steps parameters is not an object.
ASSEMBLY_STEP_INVALID_USE One of the step parameters contains a use value that is not an array.
ASSEMBLY_STEP_UNKNOWN_USE One of the step parameters is set to an unknown use value.
ASSEMBLY_INFINITE The assembly does not appear to end, as the same step was performed twice for one or more input files.
ASSEMBLY_STEP_NO_ROBOT One of the step parameters did not include a robot key.
ASSEMBLY_STEP_INVALID_ROBOT One of the step parameters includes robot value that is not a string.
ASSEMBLY_STEP_UNKNOWN_ROBOT One of the step parameters is set to an unknown robot.
ASSEMBLY_CRASHED The process managing this assembly crashed, and could not be restored.
INTERNAL_TOOL_ERROR One of our internal tools reported an error.
INTERNAL_COMMAND_ERROR One of our commands reported an error.
VIDEO_ENCODE_INVALID_WATERMARK_POSITION An invalid watermark_position array member was detected.
IMPORT_FILE_ERROR A file was unable to be imported.
CLOUDFILES_STORE_ACCESS_DENIED The given credentials could not be used to obtain an auth token from CloudFiles.
CLOUDFILES_STORE_ERROR The given file could not be stored in the container.
FILE_FILTER_INVALID_OPERATOR The accepts or declines array could not be parsed.
FILE_FILTER_DECLINED_FILE One of the files was declined.
IMAGE_RESIZE_INVALID_WATERMARK_POSITION An invalid watermark_position array member was detected.
WORKER_JOB_ERROR This assembly could not be processed.
QUEUE_DOWNLOAD_FILE_ERROR This assembly could not be processed.

7. File metadata

Many files contain interesting information about their contents, called "metadata". Transloadit automatically extracts this metadata for all uploaded or processed files.

At the very minimum, each file will have the information such as the following:

{
  id: 'ae52b7f8c1b3426e8c29ea0a9daf8306',
  name: 'straw-apple.jpg',
  basename: 'straw-apple',
  ext: 'jpg',
  size: 92230,
  mime: 'image/jpeg',
  type: 'image',
  field: 'test_file',
  url: 'http://tmp.maynard.transloadit.com/upload/1324a798a99fce7f5f8289a95a74f02b.jpg',
  original_id: "4af24fb2595f44809f3adc2f77bc9bfa",
  meta: { ... }
}

The information we can extract from depends on the media file, its type, but also who produced it. If it was an iPhone there's probably latitude in there for geo-positioning. More common keys include height, and duration.

To see what information we can extract from files that you will throw at us, you could try on of our demos and inspect our response after uploading a file there.

Key Description
id A random and unique ID used internally by Transloadit to track the file.
name The name of the file. Transloadit will change the extension used for this field if the file undergoes processing into a different format.
basename The name of the file without the extension.
ext The extension of the file.
size The size of the file, in bytes.
mime The determined MIME type for this file.
type An abstract type describing the file, which can currently be "image", "video", or null.
field The name of the form field used to submit this file.
url The url at which this file can be accessed. This is either a url in your S3 bucket, or a temporary url on our servers. Since temporary urls expire after a few hours, you should make sure to move your files elsewhere unless you are using a storage robot.
original_id The unique ID of the original upload file from which this file was generated. This is useful to determine which file of a multi-file upload was used to generate a given file, after several steps of processing.
meta Additional metadata extracted from the file, as shown below.

7.1 Image metadata

In addition to the information above, we try to extract the following information from files whose type is "image".

Key Description
width The width of the input image, in pixels.
height The height of the input image, in pixels.
date_recorded The date and time at which this image was taken, in the format YYYY/MM/DD HH:MM:SS TZ, such as "2010/06/30 22:16:06 GMT".
date_file_created The creation time for the file system.
date_file_modified The modification time for the file system.
title The title of this image, such as "Tree".
keywords An array of keywords for this image, such as ["tree", "nature"].
description A description of this image, such as "This tree is very old.".
location The location at which this image was taken, which is usually the street, such as "Zingster Str. 32".
city The city in which this image was taken, such as "Berlin".
state The state in which this image was taken, such as "Berlin".
country The country in which this image was taken, such as "Germany".
country_code The country code of the country in which this image was taken, such as "de".
aperture The aperture setting for this image, such as 5.7.
exposure_compensation The exposure compensation for this image, such as "+4/3".
exposure_mode The exposure mode for this image, such as "Auto".
exposure_time The exposure time for this image, such as "1/30".
flash The flash settings for this image, such as "Off, Did not fire".
focal_length The focal length for this image, such as "55.0 mm".
f_number The f-number for this image, such as 5.6.
iso The ISO value for this image, such as 800.
light_value The light value for this image, such as 6.9.
metering_mode The metering mode for this image, such as "Multi-segment".
shutter_speed The shutter speed for this image, such as "1/32".
white_balance The white balance setting for this image, such as "Manual".
device_name The device name of the camera, such as "iPhone 3GS".
device_vendor The camera manufacturer, such as "Apple".
device_software The version of the device software for the camera, such as "3.1.2".
latitude The latitude at which this image was taken, such as 52.5374.
longitude The longitude at which this image was taken, such as 13.4034.
thumbnail_index The index of the current thumbnail starting at 0. This key is only present for results of the /video/thumbnails robot.
thumbnail_offset The offset for the current thumbnail, in seconds. This key is only present for results of the /video/thumbnails.
frame_count The number of frames in an animated GIF file. This is 1 by default for all other image types.

7.2 Video metadata

Files whose type is "video" contain the following metadata:

Key Description
width The width of the video, in pixels. If the video was meant to be displayed with a different display ratio than the pixel ratio, this indicates the width at which the video is to be displayed.
height The height of the video, in pixels.
framerate The frame rate of the video, such as 29.5.
video_bitrate The video bit rate of the video, such as 500000.
video_codec The video codec of the video, such as "ffh264".
audio_bitrate The audio bit rate of the video, such as 128000.
audio_samplerate The audio sample rate of the video, such as 44100.
audio_channels The number of audio channels in the video, such as 2.
audio_codec The audio codec of the video, such as "faad".
seekable Whether the format of the video supports seeking, such as true.
date_recorded For details, see the description for image metadata.
date_file_created For details, see the description for image metadata.
date_file_modified For details, see the description for image metadata.
device_name For details, see the description for image metadata.
device_vendor For details, see the description for image metadata.
device_software For details, see the description for image metadata.
latitude For details, see the description for image metadata.
longitude For details, see the description for image metadata.

7.3 Audio metadata

Although it depends on the file at hand, files whose mime type is "audio" typically contain the following metadata:

Key Description
duration The duration of the audio file in seconds.
audio_bitrate Bits per second (for all channels combined).
audio_samplerate The audio sample rate in herz, such as 44100, for a CD.
audio_channels Number of channels. Typically 2, for stereo.
audio_codec The Audio codec used. Here's a list of all audio codecs that Transloadit supports.
artist Many applications that produce audio write additional information into the audio file such as artist, year, , album, genre.