The response
The response format
Transloadit uses a single response format for creating and querying assemblies, appending responses to your upload form and sending notifications.
Here is a full example of a Transloadit response. Please note that since we process files in parallel, the order of the results does not necessarily reflect the same order of the uploads. If you want to match results with uploads - in case your form is multiupload enabled for example - please use the result's original_id field to match with an original_id field from the uploads part of the response.
{
"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
}
}
...
}
| Key | Description |
|---|---|
| ok |
A success status code. If the assembly
had an error, this key is not present, but the error key below
is.
|
| error | An error status code. This key is only present if the assembly failed. |
| message | A human readable explanation for the state this assembly is in. Not always present. |
| assembly_id | A unique id for this assembly. You can store this in the database when creating an assembly, and match it when a notification for it comes in. |
| assembly_url | A unique url where you can query the current status of this assembly. |
| bytes_received | The amount of bytes uploaded in this assembly so far. This is mainly used by the jQuery plugin to provide the upload progress. |
| bytes_expected | The amount of bytes expected to be uploaded for this assembly. |
| client_agent | The user agent (browser) used by the uploader. |
| client_ip | The IP of the uploader. |
| client_referer | The referer url of the uploader. |
| start_date | The date / time when this assembly started uploading. |
| upload_duration | The time it took for the uploader to upload his files. In seconds. |
| execution_duration | The time it took Transloadit to execute this assembly. In seconds. |
| fields | If your form contained additional input fields, and you are integrating without the jQuery plugin, this contains a key value map of your fields. |
| uploads | An array of files uploaded for this assembly. Check the meta data docs for more information. |
| results | The result files Transloadit produced so far. The keys for this object are the names of the step that produced this particular file. Storage robots do not produce files, so you will never see their step names in here. |
Meta data
Lots of files contain interesting information about their contents. Transloadit automatically extracts this meta information for any uploaded or processed files.
At the very minimum, each file will have the following information:
{ 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: {...}
}
| Key | Description |
|---|---|
| id | A unique random id we created to track this file internally. |
| name | The name of the file. We will change the extension used in this field if the file undergoes processing into a different format. |
| basename | The name of the file without the extensions. |
| ext | The extension for the file. |
| size | The size of this file in bytes. |
| mime | The mime type we determined for this file. |
| type |
The abstract type this file is. Currently this can either be:
"image", "video", or null
|
| field | The name of the form field that was used to submit this file. |
| url | The url where you can access this file. This is either a url to your S3 bucket, or a temporary url on one of our servers. Temporary urls will expire after a few hours, so you need to make sure to move your files elsewhere if you aren't using a storage robot. |
| original_id | The unique id of the original upload file this file is a result of. This is useful if you have to the results of a multiple file upload with several steps back to the files they are made of. |
| meta | Additional meta information we were able to extract for this file. See below. |
Image meta data
In addition to the information above, we try to extract the following
information from type = "image" files.
| Key | Description |
|---|---|
| width | The width of this image in pixel. |
| height | The height of this image in pixel. |
| date_recorded |
The date/time this image was taken. Format is:
YYYY/MM/DD HH:MM:SS TZ. For example:
"2010/06/30 22:16:06 GMT"
|
| date_file_created | The file system create time. |
| date_file_modified | The file system modified time. |
| title |
The title of this image: For example "Tree".
|
| keywords |
An array of keywords for this image. For example: ["tree", "nature"].
|
| description |
The description of this image: "This tree is very old.".
|
| location |
The location where this image was taken (usually the street). For example: "Zingster Str. 32".
|
| city |
The city where this image was taken. For example: "Berlin".
|
| state |
The state where this image was taken. For example: "Berlin".
|
| country |
The country where this image was taken. For example: "Germany".
|
| country_code |
The country code of the country where this image was taken. For example: : "de".
|
| aperture |
The aperture of this image. For example: 5.7.
|
| exposure_compensation |
The exposure compensation of this image. For example: "+4/3".
|
| exposure_mode |
The exposure mode of this image. For example: "Auto".
|
| exposure_time |
The exposure time of this image. For example: "1/30".
|
| flash |
The flash settings for this image. For example: "Off, Did not fire".
|
| focal_length |
The focal length of this image. For example: "55.0 mm".
|
| f_number |
The f-number of this image. For example: 5.6.
|
| iso |
The iso value of this image. For example: 800.
|
| light_value |
The light value of this image. For example: 6.9.
|
| metering_mode |
The metering mode of this image. For example: "Multi-segment".
|
| shutter_speed |
The shutter speed of this image. For example: "1/32".
|
| white_balance |
The white balance setting of this image. For example: "Manual".
|
| device_name |
The device name of the camera. For example: "iPhone 3GS".
|
| device_vendor |
The device vendor of the camera. For example: "Apple".
|
| device_software |
The device software version of the camera. For example: "3.1.2".
|
| latitude |
The latitude where this image was taken. For example: 52.5374.
|
| longitude |
The longitude where this image was taken. For example: 13.4034.
|
| thumbnail_index |
This key is only present for results of the /video/thumbnails robot and holds the index / number of the current thumbnail. Indexing starts with 0.
|
| thumbnail_offset |
This key is only present for results of the /video/thumbnails robot and holds the offset (in seconds) for the current thumbnail.
|
| frame_count |
The number of frames in an animated gif file. Defaults to null for all other image types.
|
Video meta data
Files of type = "video" contain the following meta information:
| Key | Description |
|---|---|
| width | The width of this video in pixel. In case this video is meant to be displayed with a different display ratio than pixel ratio, this indicates the width you want to display the video at. |
| height | The height of this video in pixel. |
| framerate |
The framerate of this video. For example: 29.5.
|
| video_bitrate |
The video bitrate of this video. For example: 500000.
|
| video_codec |
The video codec of video. For example: "ffh264".
|
| audio_bitrate |
The audio bitrate of this video. For example: 128000.
|
| audio_samplerate |
The audio samplerate of this video. For example: 44100.
|
| audio_channels |
The number of audio channels in this video. For example: 2.
|
| audio_codec |
The audio codec of video. For example: "faad".
|
| seekable |
Whether or not this video format supports seeking. For example: true.
|
| date_recorded | See image meta data. |
| date_file_created | See image meta data. |
| date_file_modified | See image meta data. |
| device_name | See image meta data. |
| device_vendor | See image meta data. |
| device_software | See image meta data. |
| latitude | See image meta data. |
| longitude | See image meta data. |
Status codes
Here is a list of status codes returned by transloadit. You can use these for your own error handling.
Ok codes
Ok codes are always returned via the {ok: <code>} key.
| 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 successfully completed. |
Error codes
Error codes are always returned via the {error: <code>} key.
| Code | Description |
|---|---|
| INVALID_FORM_DATA | bad form data, cannot parse |
| INVALID_FILE_META_DATA | bad file, could not parse meta data |
| NO_PARAMS_FIELD | no params field given |
| INVALID_PARAMS_FIELD | bad params field, invalid json |
| NO_OBJECT_PARAMS_FIELD | bad params field, not an object |
| NO_AUTH_PARAMETER | no auth parameter given |
| NO_OBJECT_AUTH_PARAMETER | bad auth parameter given, not an object |
| NO_AUTH_KEY_PARAMETER | no auth key parameter given |
| INVALID_AUTH_KEY_PARAMETER | invalid auth key parameter given, not a string |
| NO_AUTH_EXPIRES_PARAMETER | no auth expires parameter given |
| INVALID_AUTH_MAX_SIZE_PARAMETER | invalid auth referer parameter given, could not parse it |
| MAX_SIZE_EXCEEDED | the uploaded file exceeded the file size limit |
| INVALID_AUTH_REFERER_PARAMETER | invalid auth referer parameter given, could not parse it |
| REFERER_MISMATCH | this request comes from a location that is not allowed |
| INVALID_AUTH_EXPIRES_PARAMETER | invalid auth expires parameter given, could not parse it |
| 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 ours |
| GET_ACCCOUNT_DB_ERROR | could not get account, db error |
| GET_ACCOUNT_UNKNOWN_AUTH_KEY | could not get account, unknown auth key |
| NO_COUNTRY | Your account has no country record attached to it, please contact support or update your account information. |
| NO_PRICING | Your account has no pricing record attached to it, please contact support. |
| BAD_PRICING | Something is wrong with the pricing record attached to your account, please contact support. |
| INCOMPLETE_PRICING | Something is wrong with the pricing record attached to your account, please contact support. |
| BILL_LIMIT_EXCEEDED | The bill limit that was configured for this account is exceeded this month. |
| CREDIT_EXCEEDED | You need to add a credit card to your profile to continue your service usage. |
| TEMPLATE_DB_ERROR | The template for this request could not be fetched due to a db error. |
| TEMPLATE_NOT_FOUND | There was no template found for the given template_id and account. |
| TEMPLATE_INVALID_JSON | Your template contained invalid JSON. |
| SERVER_404 | unknown method / url |
| FILE_META_DATA_ERROR | There was a problem extracting meta data information from your file. |
| ASSEMBLY_NOT_FOUND | The assembly you requested does not exist. |
| ASSEMBLY_NO_STEPS | Your assembly does not include a {steps: ...} parameter. |
| ASSEMBLY_INVALID_STEPS | Your assembly {steps: ...} is a non-object value. |
| ASSEMBLY_EMPTY_STEPS | Your assembly {steps: ...} parameter is empty. |
| ASSEMBLY_STEP_INVALID | One of your {steps: ...} parameters is a non-object value. |
| ASSEMBLY_STEP_INVALID_USE | One of your step parameters includes an non-array {use: ...} value. |
| ASSEMBLY_STEP_UNKNOWN_USE | One of your step parameters references an unknown {use: ...} value. |
| ASSEMBLY_INFINITE | Your assembly appears to be infinite, at least one input file went through the same step twice. |
| ASSEMBLY_STEP_NO_ROBOT | One of your step parameters did not include a {robot: ...} key. |
| ASSEMBLY_STEP_INVALID_ROBOT | One of your step parameters includes an non-string {robot: ...} value. |
| ASSEMBLY_STEP_UNKNOWN_ROBOT | One of your step parameters is referencing 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 | Transloadit detected an invalid watermark_position array member. |
| IMPORT_FILE_ERROR | Transloadit was unable to import a file. |
| CLOUDFILES_STORE_ACCESS_DENIED | Transloadit was unable to get an auth token from cloudfiles using the given credentials. |
| CLOUDFILES_STORE_ERROR | Transloadit was unable to store the given file in the container. |
| FILE_FILTER_INVALID_OPERATOR | Transloadit was unable to parse your accepts or declines array |
| FILE_FILTER_DECLINED_FILE | One of your files was declined |
| IMAGE_RESIZE_INVALID_WATERMARK_POSITION | Transloadit detected an invalid watermark_position array member. |
| WORKER_JOB_ERROR | Transloadit was unable to process this assembly. |
| QUEUE_DOWNLOAD_FILE_ERROR | Transloadit was unable to process this assembly. |