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. Enable the “Deny requests that do not include a signature or a wrong one” 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: {
        use: ":original",
        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: { use: ":original", robot: "/video/encode" } } }

So, given an Auth Secret of d805593620e689465d7da6b8caf2ac7384fdb7e9, the resulting signature would be as follows:

6ec267fedfcc9e52d0467307947e31435444eb9a

And your final request would look like this:

params=%7B%22auth%22%3A%7B%22key%22%3A%222b0c45611f6440dfb64611e872ec3211%22%2C%22expires%22%3A%222010%2F10%2F19+09%3A01%3A20%2B00%3A00%22%7D%2C%22steps%22%3A%7B%22encode%22%3A%7B%22use%22%3A%22%3Aoriginal%22%2C%22robot%22%3A%22%2Fvideo%2Fencode%22%7D%7D%7D&signature=6ec267fedfcc9e52d0467307947e31435444eb9a

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:

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

To verify that the POST request actually came from Transloadit you need to calculate the signature yourself for the entire body of the transloadit field of the Assembly Notification. When the signature in the signature field matches the one you calculate, the request is valid. If not, then the request was tinkered with and should be ignored!

Here is some example Node.js code to calculate the signature yourself to see that the sent signature matches:

var crypto = require('crypto');
// This is the signature contained in the "signature" POST field.
var assemblyNotification = "{\"signature\":\"4544c846a3ac4aa99750ccafc9b62702b4c4812e\",\"transloadit\":\"theData\"}";

var decoded       = JSON.parse(assemblyNotification);
var sentSignature = decoded.signature;
var sentData      = decoded.transloadit;

// Stringify the sent data as the signature is calculated for
// a string.
var dataString = JSON.stringify(sentData);
var secret     = 'YOUR_ACCOUNT_SECRET_KEY';

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

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

2.7 Implementations

When you deal with JSON, please keep in mind that your language of choice might escape slashes. That is it might turn occurrences of / into \/. We calculate the signatures on our end with unescaped slashes! Please make sure to remove backslashes from your JSON before calculating the signature of it.

If you use PHP for example, please check the JSON_UNESCAPED_SLASHES option of the json_encode function.

2.7.1 Ruby

2.7.2 PHP

2.7.3 NodeJS

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.

If you do not know your assembly_url you can also query https://api2.transloadit.com/assemblies/[[assembly_id]]. This will also get you the Assembly status, even though it is not as up to date for Assemblies that are still uploading or executing.


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 type of Notifications to be retrieved. This can be either successful, failed or all (default), which means both successful and failed Notifications are retrieved.

assembly_id

Only finds Notifications for the Assembly identified by the given id.

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 params containing your Auth Key and auth expires value is mandatory. And so is providing a GET query field named signature (containing a signature string). 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).

Important 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

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.

assembly_ssl_url

The unique URL used to query the current status of this Assembly, but ready to be used over SSL/HTTPS. All API requests that are sent to the assembly_url can also be sent to the assembly_ssl_url.

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.

aspect_ratio

The aspect ratio of the image, which is its width divided by its height. Will be 0 if for some reason the image height ist 0.

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

creator

The creator that took the image.

author

The author that took the image. Some cameras populate this field as opposed to creator.

copyright

The copyright meta data field.

copyright_notice

The copyright notice meta data field.

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.

colorspace

The colorspace of the image. This could be "sRGB" or "Gray" for instance. In Transloadit’s first ImageMagick stack version, there’s a bug which would make the colors used in an image determine its colorspace, and a grayscale colored image would report "Gray", even if saved as "RGB".

has_clipping_path

Is 1 if the image contains a clipping path, 0 otherwise.

average_color

Requested by many, and added January 2015, the average color used in the image. Not to be confused with dominant color, that counts a single most occuring pixel color and has limited use cases. The average color is calculated by first scaling the input image to 1 pixel.

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.