1 Topics

We offer ready-to-use and well-maintained SDKs for most major programming languages and platforms and generally recommend to use them. However, if there is no suitable SDK for your situation, on this page we explain all the details of our bare bones REST API.

1.1 Resources

Transloadit provides a simple JSON REST API that can be used for:

Here’s a complete overview:
Method URL Description Signature Auth Documentation
Assemblies
POST /assemblies Create a New Assembly optional Documentation
GET /assemblies/{ASSEMBLY_ID} Retrieve an Assembly Status not supported Documentation
DELETE /assemblies/{ASSEMBLY_ID} Cancel a running Assembly not supported Documentation
POST /assemblies/{ASSEMBLY_ID}/replay Replay an Assembly required Documentation
GET /assemblies Retrieve List of Assemblies required Documentation
Assembly Notifications
POST /assembly_notifications/{ASSEMBLY_ID}/replay Replay Assembly Notification required Documentation
GET /assembly_notifications Retrieve List of Assembly Notifications required Documentation
Billing
GET /bill/{MONTH} Retrieve a month's bill required Documentation
Templates
POST /templates Create a New Template required Documentation
GET /templates/{TEMPLATE_ID} Retrieve a Template required Documentation
PUT /templates/{TEMPLATE_ID} Edit a Template required Documentation
DELETE /templates/{TEMPLATE_ID} Delete a Template required Documentation
GET /templates Retrieve List of Templates required Documentation

1.2 Response Codes

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

An Assembly is running if ok is either ASSEMBLY_UPLOADING or ASSEMBLY_EXECUTING. All other states mean the Assembly has completed. If it completed in error, the error property will be set. More details on ok and error codes can be found below.

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.

Error Codes

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

Code Description
ADMIN_PERMISSIONS_REQUIRED You require admin permissions to do this.
You are not allowed to access this Assembly because it is not yours.
ASSEMBLY_CANNOT_BE_REPLAYED The Assembly cannot be replayed.
ASSEMBLY_CRASHED The process managing this Assembly crashed and could not be restored.
ASSEMBLY_EMPTY_STEPS Your Assembly {steps: …} parameter is empty.
ASSEMBLY_EXPIRED The Assembly expired.
ASSEMBLY_FILE_ACCEPTED The Assembly accepted the added file.
ASSEMBLY_FILE_NOT_RESERVED A place for this file must be reserved before adding it.
ASSEMBLY_FILE_RESERVED The Assembly reserved a space for this file.
ASSEMBLY_INFINITE Your Assembly appears to be infinite, at least one input file went through the same step twice.
ASSEMBLY_INVALID_NOTIFY_URL The Assembly had a malformed notify_url. They must be strings.
ASSEMBLY_INVALID_NUM_EXPECTED_UPLOAD_FILES_PARAM Your 'num_expected_upload_files' parameter value is invalid. It must be a number greater than or equal zero.
ASSEMBLY_INVALID_STEPS Your Assembly {steps: …} is a non-object value.
ASSEMBLY_LIST_ERROR Bad parameters
ASSEMBLY_MEMORY_LIMIT_EXCEEDED The Assembly memory limit of 8MB was exceeded. Please try to import less files and/or upload a zip file with less files.
ASSEMBLY_NOTIFICATION_LIST_ERROR Bad parameters
ASSEMBLY_NOT_CAPABLE This Assembly is not capable of handling the requested endpoint.
ASSEMBLY_NOT_FINISHED The Assembly is not finished yet and thus cannot be replayed yet.
ASSEMBLY_NOT_FOUND The Assembly you requested crashed or does not exist.
ASSEMBLY_NO_NOTIFY_URL The Assembly had not configured any notify_url.
ASSEMBLY_NO_STEPS Your Assembly does not include a {steps: …} parameter.
ASSEMBLY_PROGRESS_UPDATED The Assembly's upload progress has been updated.
ASSEMBLY_REPLAYING The Assembly is now in the process of being replayed.
ASSEMBLY_SATURATED This Assembly has already received all expected file uploads.
ASSEMBLY_STATUS_NOT_FOUND The status for the Assembly you requested could not be found.
ASSEMBLY_STATUS_PARSE_ERROR There was a problem parsing the status json of the Assembly.
ASSEMBLY_STEP_INVALID One of your {steps: …} parameters is a non-object value.
ASSEMBLY_STEP_INVALID_ROBOT One of your step parameters includes an non-string {robot: …} value.
ASSEMBLY_STEP_INVALID_USE One of your step parameters either includes a non-array {use: …} value or the members of the "use" array are not strings or objects. If they are objects, they must contain a "name" property.
ASSEMBLY_STEP_NO_ROBOT One of your step parameters did not include a {robot: …} key.
ASSEMBLY_STEP_UNKNOWN_ROBOT One of your step parameters is referencing an unknown {robot: …}.
ASSEMBLY_STEP_UNKNOWN_USE One of your step parameters references an unknown {use: …} value.
AUDIO_CONCAT_INVALID_INPUT You provided invalid input to the audio concatenation robot.
AUDIO_CONCAT_INVALID_STACK Audio concatenation is not supported for ffmpeg_stack 1.0.0. Please use 2.0.0 or newer.
AUDIO_LOOP_INVALID_STACK Audio looping is not supported for ffmpeg_stack 1.0.0. Please use 2.0.0 or newer.
AUDIO_MERGE_INVALID_STACK Audio merging is not supported for ffmpeg_stack 1.0.0. Please use 2.0.0 or newer.
AUDIO_WAVEFORM_VALIDATION Transloadit was unable to generate a waveform image.
AUTH_EXPIRED The given auth expires parameter is in the past.
AZURE_STORE_ACCESS_DENIED Microsoft Azure did not accept the account / key pair you provided.
BAD_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.
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.
DOCUMENT_CONVERT_UNSUPPORTED_CONVERSION The conversion from the input file's format to the desired output format are not supported.
DOCUMENT_THUMBS_INVALID_COLORSPACE_VALUE Transloadit detected an invalid colorspace value.
DROPBOX_STORE_COULD_NOT_PARSE_URL Transloadit could not parse the response from Dropbox.
FILE_COMPRESS_INVALID_FORMAT_VALUE Invalid format value for /file/compress robot provided.
FILE_DOWNLOAD_ERROR Transloadit was unable to download an external file.
FILE_FILTER_DECLINED_FILE One of your files was declined
FILE_FILTER_INVALID_OPERATOR Transloadit was unable to parse your accepts or declines array
There was a problem extracting meta data information from your file.
FILE_VIRUSSCAN_DECLINED_FILE One of your files is malicious and was declined
FTP_IMPORT_FILE_ERROR Transloadit was unable to import a file over ftp.
GET_ACCCOUNT_DB_ERROR Could not get account, there was a database error.
Could not get account, this is an unknown Auth Key.
IMAGE_RESIZE_INVALID_ALPHA_VALUE Transloadit detected an invalid alpha value.
IMAGE_RESIZE_INVALID_BLUR_VALUE Transloadit detected an invalid blur value.
IMAGE_RESIZE_INVALID_CLIP_VALUE Transloadit detected an invalid clip value.
IMAGE_RESIZE_INVALID_COLORSPACE_VALUE Transloadit detected an invalid colorspace value.
IMAGE_RESIZE_INVALID_COMPRESSION_VALUE Transloadit detected an invalid compress value.
IMAGE_RESIZE_INVALID_TEXT_OBJECT_VALUE Transloadit detected an invalid text object key.
IMAGE_RESIZE_INVALID_TEXT_VALUE Transloadit detected an invalid value for the "text" parameter. Its value must either be an object or an array of objects.
IMAGE_RESIZE_INVALID_TYPE_VALUE Transloadit detected an invalid type value.
IMAGE_RESIZE_INVALID_WATERMARK_POSITION Transloadit detected an invalid watermark_position array member.
IMPORT_FILE_ERROR Transloadit was unable to import a file.
INCOMPLETE_PRICING Something is wrong with the pricing record attached to your account, please contact support.
INTERNAL_COMMAND_ERROR One of our commands reported an error.
INVALID_ASSEMBLY_STATUS This is an invalid Assembly status.
INVALID_AUTH_EXPIRES_PARAMETER Invalid auth expires parameter provided - we could not parse it.
INVALID_AUTH_KEY_PARAMETER Invalid Auth Key parameter provided - the value is not a string.
INVALID_AUTH_MAX_SIZE_PARAMETER Invalid auth referer parameter provided, could not parse it.
INVALID_AUTH_REFERER_PARAMETER Invalid auth referer parameter given, could not parse it.
We could not parse the meta data for the file #file#.
INVALID_FORM_DATA The form contained bad data, which cannot be parsed.
INVALID_PARAMS_FIELD Bad params field provided, it contains invalid json.
INVALID_S3_IMPORT_KEY_PARAMETER Invalid /s3/import key parameter given, not a string
INVALID_S3_IMPORT_PATH_PARAMETER Invalid /s3/import path parameter given, not a string
INVALID_S3_IMPORT_SECRET_PARAMETER Invalid /s3/import secret parameter given, not a string
INVALID_S3_STORE_KEY_PARAMETER Invalid /s3/store key parameter given, not a string
INVALID_S3_STORE_PATH_PARAMETER Invalid /s3/store path parameter given, not a string
INVALID_S3_STORE_SECRET_PARAMETER Invalid /s3/store secret parameter given, not a string
INVALID_SIGNATURE The given signature does not match ours.
INVALID_TEMPLATE_FIELD Bad Template field provided, it contains invalid json.
INVALID_UPLOAD_HANDLE_STEP_NAME When using the /upload/handle robot, its step name must be ":original".
MAX_SIZE_EXCEEDED The uploaded file exceeded the file size limit.
NO_AUTH_EXPIRES_PARAMETER No auth expires parameter was provided.
NO_AUTH_KEY_PARAMETER No Auth Key parameter provided.
NO_AUTH_PARAMETER No auth parameter provided.
NO_COUNTRY Your account has no country record attached to it, please contact support or update your account information.
NO_OBJECT_AUTH_PARAMETER Bad auth parameter provided, it is not an object.
NO_OBJECT_PARAMS_FIELD Bad params field provided, it is not an object.
NO_PARAMS_FIELD No params field provided.
NO_PRICING Your account has no pricing record attached to it, please contact support.
NO_S3_IMPORT_BUCKET_PARAMETER No /s3/import bucket parameter given
NO_S3_IMPORT_KEY_PARAMETER No /s3/import key parameter given
NO_S3_IMPORT_SECRET_PARAMETER No /s3/import secret parameter given
NO_S3_STORE_KEY_PARAMETER No /s3/store key parameter given
NO_S3_STORE_SECRET_PARAMETER No /s3/store secret parameter given
NO_SIGNATURE_FIELD No signature field was provided.
NO_STRING_S3_IMPORT_BUCKET_PARAMETER Invalid /s3/import bucket parameter given, not a string
NO_STRING_S3_STORE_BUCKET_PARAMETER Invalid /s3/store bucket parameter given, not a string
NO_TEMPLATE_ID This account demands that a Template id provided. None was provided, though.
PLAN_LIMIT_EXCEEDED You have exceeded the usage limit of the sandbox plan. Please upgrade your plan on https://transloadit.com to make this error message go away.
QUEUES_LIST_ERROR There was an error fetching the queue stats
RATE_LIMIT_REACHED Request limit reached
REFERER_MISMATCH This request comes from a location that is not allowed.
S3_ACCESS_DENIED S3 did not accept the key / secret pair you provided or the provided user does not have sufficient permissions.
S3_IMPORT_ACCESS_DENIED S3 did not accept the key / secret pair you provided.
S3_IMPORT_FAILURE One of our internal tools failed to import your file, please try again.
S3_IMPORT_NOT_FOUND S3 did not find the object that you asked for.
S3_STORE_ACCESS_DENIED S3 did not accept the key / secret pair you provided.
S3_STORE_CONFIRMATION_FAILURE The stored file did not show up in the S3 bucket, even so multiple attempts have been made to store it. Amazon has a bad day : /
S3_STORE_FAILURE One of our internal tools failed to store your file, please try again.
S3_STORE_WRONG_REGION S3 could not store the file as the wrong bucket region was provided.
SERVER_401 Authorization required
SERVER_403 Forbidden
SERVER_404 Unknown method / url
SERVER_500 Unexpected error
SFTP_IMPORT_FILE_ERROR Transloadit was unable to import a file over sftp.
SOFTLAYER_STORE_ACCESS_DENIED Softlayer did not accept the account / key pair you provided.
TEMPLATE_CREATED Your Template was successfully created.
TEMPLATE_CREDENTIALS_CREATED Your Template Credentials were successfully created.
TEMPLATE_CREDENTIALS_DELETED Your Template Credentials were successfully deleted.
TEMPLATE_CREDENTIALS_FOUND Your Template Credentials were successfully found.
TEMPLATE_CREDENTIALS_INJECTION_ERROR Your Template Credentials could not be injected.
TEMPLATE_CREDENTIALS_NOT_CREATED Your Template Credentials could not be created.
TEMPLATE_CREDENTIALS_NOT_DELETED Your Template Credentials could not be deleted.
TEMPLATE_CREDENTIALS_NOT_FOUND Your Template Credentials could not be found.
TEMPLATE_CREDENTIALS_NOT_UPDATED Your Template Credentials could not be updated.
TEMPLATE_CREDENTIALS_TYPES_FOUND The Template Credentials types were successfully found.
TEMPLATE_CREDENTIALS_TYPES_NOT_FOUND The Template Credentials types could not be found.
TEMPLATE_CREDENTIALS_UPDATED Your Template Credentials were successfully updated.
TEMPLATE_DB_ERROR The Template for this request could not be fetched due to a db error.
TEMPLATE_DELETED Your Template was successfully deleted.
TEMPLATE_DENIES_STEPS_OVERRIDE This Template had the allow_steps_override option set to true, so clients are not allowed to temper with its steps.
TEMPLATE_FOUND Your Template was successfully found.
TEMPLATE_INVALID_JSON Your Template contained invalid JSON.
TEMPLATE_LIST_ERROR Bad parameters
TEMPLATE_NOT_FOUND There was no Template found for the given template_id and account.
TEMPLATE_UPDATED Your Template was successfully updated.
TMP_FILE_DOWNLOAD_ERROR Transloadit was unable to download a file from our temporary bucket.
VIDEO_CONCAT_INVALID_INPUT You provided invalid input to the video concatenation robot.
VIDEO_CONCAT_INVALID_STACK Video concatenation is not supported for ffmpeg_stack 1.0.0. Please use 2.0.0 or newer.
VIDEO_CONCAT_UNMATCHING_DIMENSIONS You provided invalid input to the video concatenation robot. The dimensions (width and height) of the input videos need to match.
VIDEO_ENCODE_INVALID_WATERMARK_POSITION Transloadit detected an invalid watermark_position array member.
VIDEO_MERGE_INVALID_STACK Video merging is not supported for ffmpeg_stack v1.0.0. Please use v2.0.0 or newer.
VIDEO_MERGE_NO_BASE_VIDEO_SET When merging videos, at least one step must be declared to be the "base" video.
VIDEO_MERGE_NO_IMAGE_FOUND No image was found in your video merge step.
VIDEO_SUBTITLE_INVALID_STACK Video subtitle is only supported for ffmpeg_stack v3.3.3 and newer.
VIDEO_THUMBS_INVALID_COUNT_VALUE Invalid count value for /video/thumbs robot provided. It needs to be a number below 1000.
WORKER_JOB_ERROR Transloadit was unable to process this Assembly.
YOUTUBE_STORE_ACCESS_DENIED Youtube did not accept the username / password pair you provided.
YOUTUBE_STORE_INVALID_VISIBILITY_VALUE Transloadit detected an invalid visibility value.
YOUTUBE_STORE_PROBLEM_FETCHING_TOKEN Youtube had a problem fetching a security token for your account.
YOUTUBE_STORE_PROBLEM_SENDING_FILE Youtube had a problem accepting the file.

1.3 Meta Data

Many files contain interesting information about their contents, called "metadata". Transloadit automatically extracts this metadata for all uploaded, imported, and 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", "audio", 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 An object containing additional metadata extracted from the file, as shown below.

Image Meta Data

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 is 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/thumbs Robot.
thumbnail_offset The offset for the current thumbnail, in seconds. This key is only present for results of the /video/thumbs Robot.
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 occurring pixel color and has limited use cases. The average color is calculated by first scaling the input image to 1 pixel.
has_transparency Returns true for images that have transparent areas. This key is only returned if you set output_meta.has_transparency to true.
dominant_colors Returns an array of the 20 most used colors for images. This key is only returned if you set output_meta.dominant_colors to true.

Video Metadata

Although it depends on the file at hand, files whose mime type is video typically 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.

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

1.4 API Security

There is an extensive amount of measures deployed at Transloadit to ensure security, but for the purpose of communicating with the REST API, it is important to note that:

  1. All of our endpoints listed below are accessible via HTTPS with A+ grading on SSL Labs to ensure encryption in transit.
  2. With Signature Authentication you can ensure no one else is sending requests on your behalf, or tampering with them. You can make Templates require valid Signatures.
  3. We hold on to the least amount of data possible, more on that in our /legal/privacy.
  4. You can make Templates reject unrecognized HTTP Referer values (although some browsers do not send these, in which case you are better off rolling out Signature Authentication).
  5. You can set a bill limit, after which Transloadit stops processing anything. We're happy to scale up with your usage, but bill limits are a good way to prevent cases of undetected abuse or "infinite loop"-type bugs from making you (and/or us) go bankrupt. : )

1.5 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 high bills or increased queue times.

We have two hard Assembly limits in place:

  1. A limit of the number of Assemblies that a customer can create to 250 per minute
  2. A limit of 250 concurrent Assemblies per customer

In our experience, this satisfies even enterprise-level usage, but enterprise accounts are free to contact us if they require higher limits.

The limits are in place mostly to shield customers from other customer's "infinite loop"-type of programming bugs.

Customers that hit a rate limit will receive a 413 RATE_LIMIT_REACHED error. The JSON payload for this error contains an info.retryIn property 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. If you use one of our official SDKs, proper back-offs and retries are already included.

The following is an example of what the JSON payload may look like:

{
  "error": "RATE_LIMIT_REACHED",
  "message": "Request limit reached",
  "info": {
    "retryIn": 41
  }
}

1.6 Queues

Encoding is hard work and it's quicker to request an encode than to execute it. Any customers can flood our systems with requests in just a second, and these could be very valid requests. We always have 300% spare capacity on standby to deal with peaks, but sometimes that does not suffice and we have to scale up. We have virtually infinate scaling capacity and this can complete in just a few minutes, but during these minutes, jobs can queue up. To make sure jobs that require a realtime feel are impacted the least, we have made a separation between high priority, and low priority jobs.

  • If you use direct file uploads, your Assembly's Encoding Jobs are put into our Live Queue scheduled for immediate processing. If you have many concurrent Jobs, however, they may trickle down into our Batch Queue as to not affect other customers' performance, and so that we can accept both huge library conversions as well as "avatar resizes" without the former blocking the latter. You can think of the Live Queue as our fast lane, while the Batch Queue is for trucks only.
  • If you use our import Robots with more than one file import per Robot, your Assemblies are considered to be a "batch import" and are thrown into our Batch Queue right away. If there are "many trucks" in traffic, this drastically worsen execution times.
  • If you send us many Live Jobs, they can trickle down into the Batch Queue
  • If you set queue: 'batch' in your Steps, you can downgrade to a lower priority Queue yourself (but not upgrade). You would do this when you want your large backlog of media library transcoding to not steal capacity away from your high priority Jobs - or just to be a good citizen :)

The value that controls at what point Jobs trickle down into the Batch Queue, is called the Job Slot Limit. It is configurable per plan, and per account, and there is a safety value per IP to avoid single bad actors of filling up our Live Queue.

By default, the Job Slot Limit is

  • 40 Job Slots per client IP and
  • 120 Job Slots per customer

Encoding Jobs take up a varying number of Job Slots. A /video/encode Job takes up 6 Slots, whereas an /image/resize Job may only take up 1 Slot. So by default you could have 120 concurrent image resizes, and a single customer of yours could do 40 of those before jobs their single IP sends are given a lower priority.

To avoid being impacted by degraded performance due to this you can do two things:

1. Get higher Job Slot Limit by upgrading your plan. Higher plans have higher throughput, and you can also contact us if you're interested in custom values.

2. Set wait to false (available in e.g. the Uppy integration). Setting wait to false makes sure media processing is handled in an asynchronous way, so 2 minutes queue-time won't block the end-user experience. As soon as the files are uploaded to us, the user is on their way. We ping your notify_url when the files are ready, and you notify your user. More on this in Assembly Notifications. This is the recommended way of integrating Transloadit and you should use it whenever you allow uploading files from a client. It is not only the best experience for your users, but it also offers the most reliability, because it allows you enable Assemblies Replays in case there was a problem, because you already have a way to notify your user/systems in an indirect way.

You can see our current queue times for both Live Queues and Batch Queues on our Status Page, and programmatically access them via our Queues API Endpoint (the values are in seconds).

2 Assemblies

2.1 Create a New Assembly

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

An Assembly can process and export files. Assembly Instructions determine how we should process them. Instructions can be passed in directly (inside a steps parameter), or be saved in a Template (refered to in a template_id parameter). Templates allow you to re-use instructions, evolve them without deploying your app, and to not expose any secrets to where your app is deployed.

We accept multipart/form-data POST requests to accomodate regular <form> uploads to our service (as well as XHR / SDK usage).

Multiple files can be included as part of this request.

POST Fields

  • Passing signature is optional. For more information please check Signature Authentication.
  • Passing params is required. It should contain a JSON encoded object with keys as shown in the table below.

You can also supply other POST fields (that are not named params or signature) here. They can be used as variables to make your Assembly Instructions dynamic.

Supported keys inside the params field

Name Type Default Description
auth (required) Object Contains your Transloadit Auth Key in key, and if you enable Signature Authentication, an expiry date for the request in expires. Example:
{
  "key": "2b0c45611f6440dfb64611e872ec3211",
  "expires": "2009/11/27 16:53:14+00:00"
}
steps Object {} Contains Assembly Instructions. Example:
"encoded": {
  "use": ":original",
  "robot": "/video/encode",
  "preset": "iphone-high"
},
"thumbed": {
  "use": "encoded",
  "robot": "/video/thumbs",
  "count": 8
}
template_id String "" The ID of the Template that contains your Assembly Instructions. steps and template_id are mutually exclusive, and supplying one of these is required.
notify_url String "" Transloadit can send a Pingback to your server when the Assembly is completed. We'll send the Assembly Status in JSON encoded string inside a transloadit field in a multipart POST request to the URL supplied here.
fields Object {} An object of string to string pairs (name -> value) that can be used as Assembly Variables, just like additional form fields can. For example, to dynamically have us resize images based on an end-user provided width, you could use ${fields.user_width} in your Assembly Instructions, and either post an <input name="user_width" value="800" /> or supply this fields param with the follow object:
{
  "user_width": 800
}

Response

Here’s an example response body:

For more information about the response, please refer to our documentation for the Assembly Status response.

2.2 Retrieve an Assembly Status

GET {ASSEMBLY_URL}?signature={SIGNATURE}

In the response after creating an Assembly you will find a field: assembly_ssl_url. You can poll this URL every few seconds (or what is a sensible interval for your usecase) to get the latest Assembly Status.

The assembly_ssl_url will contain the machine name responsible for managing the Assembly. It knows in realtime how many bytes have been uploaded. An example URL would be: https://api2-jane.transloadit.com/assemblies/{ASSEMBLY_ID}.

Due to scaling algorthms we cycle though machines quickly, so you can also fall back to removing the machine name and using: https://api2.transloadit.com/assemblies/{ASSEMBLY_ID}. This will also get you the Assembly Status, but it might be outdated a little, due to eventual consistency reasons.

This request can be issued by anyone who knows the assembly_ssl_url. Hence, make sure to not share your assembly_ssl_urls or assembly_ids with anybody. More on this in our FAQ under: Are the UUIDs that Transloadit uses for files and Assembly IDs secure?

GET Query Components

No request query components needed.

Response

Here’s an example response body:

For more information about the response, please refer to our documentation for the Assembly Status response.

2.3 Cancel a running Assembly

DELETE {ASSEMBLY_URL}

Cancels an Assembly (and upload if that is still in progress). The assembly_ssl_url field contains the unique URL returned when the Assembly was created.

This request can be issued by anyone who knows the assembly_ssl_url. Hence, make sure to not share your assembly_ssl_urls or assembly_ids with anybody. More on this in our FAQ under: Are the UUIDs that Transloadit uses for files and Assembly IDs secure?

DELETE Fields

No request fields needed.

Response

Here’s an example response body:

Either returns the latest Assembly Status (in JSON) or a JSON error ASSEMBLY_NOT_FOUND. Please refer to our documentation for the Assembly Status response.

2.4 Replay an Assembly

POST {ASSEMBLY_URL}/replay

If an Assembly crashed, and if we can recover the input files, Transloadit can retry its execution.

You can specify a new notify_url parameter in params to avoid replaying the URL already specified for the Assembly.

Specify the steps parameter to override the Steps of the original Assembly being replayed.

The newly created Assembly will have a parent_assembly_status in its Status, pointing to the URL of the original crashed Assembly that it is a Replay of.

POST Fields

  • Passing signature is required. For more information please check Signature Authentication.
  • Passing params is required. It should contain a JSON encoded object with keys as shown in the table below.

Supported keys inside the params field

Name Type Default Description
auth (required) Object Contains your Transloadit Auth Key in key, and if you enable Signature Authentication, an expiry date for the request in expires. Example:
{
  "key": "2b0c45611f6440dfb64611e872ec3211",
  "expires": "2009/11/27 16:53:14+00:00"
}
steps Object {} Contains Assembly Instructions. Example:
"encoded": {
  "use": ":original",
  "robot": "/video/encode",
  "preset": "iphone-high"
},
"thumbed": {
  "use": "encoded",
  "robot": "/video/thumbs",
  "count": 8
}
template_id String "" The ID of the Template that contains your Assembly Instructions. steps and template_id are mutually exclusive, and supplying one of these is required.
notify_url String "" Transloadit can send a Pingback to your server when the Assembly is completed. We'll send the Assembly Status in JSON encoded string inside a transloadit field in a multipart POST request to the URL supplied here.
fields Object {} An object of string to string pairs (name -> value) that can be used as Assembly Variables, just like additional form fields can. For example, to dynamically have us resize images based on an end-user provided width, you could use ${fields.user_width} in your Assembly Instructions, and either post an <input name="user_width" value="800" /> or supply this fields param with the follow object:
{
  "user_width": 800
}
reparse_template Integer 0 Specify 1 to reparse the Template used in your Assembly (useful if the Template changed in the meantime). Alternatively, 0 replays the identical Steps used in the Assembly.

Response

Here’s an example response body:

We either return the success code ASSEMBLY_REPLAYING or an error response code detailing what went wrong.

2.5 Retrieve List of Assemblies

GET https://api2.transloadit.com/assemblies?signature={SIGNATURE}&params={PARAMS}

Retrieves a list of Assemblies for your account. They are sorted by creation date descending.

GET Query Components

  • Passing signature is required. For more information please check Signature Authentication.
  • Passing params is required. It should contain a JSON encoded (and URL-encoded) object with keys as shown in the table below.

Supported keys inside the params query component

Name Type Default Description
auth (required) Object Contains your Transloadit Auth Key in key, and if you enable Signature Authentication, an expiry date for the request in expires. Example:
{
  "key": "2b0c45611f6440dfb64611e872ec3211",
  "expires": "2009/11/27 16:53:14+00:00"
}
page Integer 1 Specifies the current page, within the current pagination
pagesize Integer(1-5000) 50 Specifies how many Assemblies to be received per API request, which is useful for pagination.
assembly_id String "all" Specifies the types of Assemblies to be retrieved. This can be one of all, uploading, executing, canceled, completed, failed or request_aborted.
type String "all" Specifies the types of Assemblies to be retrieved. This can be one of all, uploading, executing, canceled, completed, failed or request_aborted.
fromdate (required) String Specifies the minimum Assembly UTC creation date/time. Only Assemblies after this time will be retrieved. Use the format Y-m-d H:i:s.
todate String NOW() Specifies the maximum Assembly UTC creation date/time. Only Assemblies before this time will be retrieved. Use the format Y-m-d H:i:s.
keywords Array of Strings [] Specifies keywords to be matched in the Assembly Status. The Assembly fields checked include the id, redirect_url, fields, and notify_url, as well as error messages and files used.

Response

We either return the error code ASSEMBLY_LIST_ERROR or a JSON list of found Assemblies.

2.6 Assembly Status Response

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.

Example Response

Explanation of fields

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 SDK to display upload progress.
bytes_expected The number of bytes that this Assembly expects to be uploaded.
bytes_usage The total number of bytes that this Assembly processed that count towards your usage bill. The sum of bytes_usage of all of your Assemblies equal your total monthly usage.
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 can not use <form> encapsulation (like Uppy, or the jQuery SDK).
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.

3 Assembly Notifications

3.1 Replay Assembly Notification

POST https://api2.transloadit.com/assembly_notifications/{ASSEMBLY_ID}/replay

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.

POST Fields

  • Passing signature is required. For more information please check Signature Authentication.
  • Passing params is required. It should contain a JSON encoded object with keys as shown in the table below.

Supported keys inside the params field

Name Type Default Description
auth (required) Object Contains your Transloadit Auth Key in key, and if you enable Signature Authentication, an expiry date for the request in expires. Example:
{
  "key": "2b0c45611f6440dfb64611e872ec3211",
  "expires": "2009/11/27 16:53:14+00:00"
}
notify_url String 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.
wait Boolean true If it is provided with the value false, then the API request will return immediately even though the Notification is still in progress. This can be useful if your server takes some time to respond, but you do not want to the replay API request to hang.

Response

Here’s an example response body:

Either returns with the success code ASSEMBLY_NOTIFICATION_REPLAYED or with the proper error code detailing what went wrong.

If wait was set to false, the success code will be ASSEMBLY_NOTIFICATION_REPLAYING.

3.2 Retrieve List of Assembly Notifications

GET https://api2.transloadit.com/assembly_notifications?signature={SIGNATURE}&params={PARAMS}

GET Query Components

  • Passing signature is required. For more information please check Signature Authentication.
  • Passing params is required. It should contain a JSON encoded (and URL-encoded) object with keys as shown in the table below.

Supported keys inside the params query component

Name Type Default Description
auth (required) Object Contains your Transloadit Auth Key in key, and if you enable Signature Authentication, an expiry date for the request in expires. Example:
{
  "key": "2b0c45611f6440dfb64611e872ec3211",
  "expires": "2009/11/27 16:53:14+00:00"
}
page Integer 1 Specifies the current page, within the current pagination
pagesize Integer(1-5000) 50 Specifies how many Assemblies to be received per API request, which is useful for pagination.
type String "all" 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 String "" Only finds Notifications for the Assembly identified by the given ID.

Response

Either returns with the error code ASSEMBLY_NOTIFICATION_LIST_ERROR or with a JSON list of found Notifications.

4 Billing

4.1 Retrieve a month's bill

GET https://api2.transloadit.com/bill/{MONTH}?signature={SIGNATURE}

Retrieves the billing data for the given MONTH.

The MONTH query component in the URL must have the format Y-m, so for example 2014-03 for March in 2014.

GET Query Components

Response

Here’s an example response body:

On success this request returns a JSON response with the success code BILL_FOUND and the corresponding bill data. The invoice_id in the response will be null for the bill of the current month. 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 Templates

5.1 Create a New Template

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

POST Fields

  • Passing signature is required. For more information please check Signature Authentication.
  • Passing params is required. It should contain a JSON encoded object with keys as shown in the table below.

Supported keys inside the params field

Name Type Default Description
auth (required) Object Contains your Transloadit Auth Key in key, and if you enable Signature Authentication, an expiry date for the request in expires. Example:
{
  "key": "2b0c45611f6440dfb64611e872ec3211",
  "expires": "2009/11/27 16:53:14+00:00"
}
name (required) String The human-readable name of this Template
template (required) String All the Assembly Instructions as a JSON encoded string.

Response

Here’s an example response body:

On success this request returns a JSON response with the success code TEMPLATE_CREATED, the Template ID, name and content. 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

GET {TEMPLATE_URL}?signature={SIGNATURE}&params={PARAMS}

GET Query Components

  • Passing signature is required. For more information please check Signature Authentication.
  • Passing params is required. It should contain a JSON encoded (and URL-encoded) object with keys as shown in the table below.

Supported keys inside the params query component

Name Type Default Description
auth (required) Object Contains your Transloadit Auth Key in key, and if you enable Signature Authentication, an expiry date for the request in expires. Example:
{
  "key": "2b0c45611f6440dfb64611e872ec3211",
  "expires": "2009/11/27 16:53:14+00:00"
}

Response

Here’s an example response body:

On success this request returns a JSON response with the success code TEMPLATE_FOUND and the Template ID. 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

PUT {TEMPLATE_URL}

Updates the Template represented by TEMPLATE_ID with the new Template name and Template JSON.

PUT Fields

  • Passing signature is required. For more information please check Signature Authentication.
  • Passing params is required. It should contain a JSON encoded object with keys as shown in the table below.

Supported keys inside the params field

Name Type Default Description
auth (required) Object Contains your Transloadit Auth Key in key, and if you enable Signature Authentication, an expiry date for the request in expires. Example:
{
  "key": "2b0c45611f6440dfb64611e872ec3211",
  "expires": "2009/11/27 16:53:14+00:00"
}
name (required) String The new human-readable name of this Template. 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.
template String Existing template All the new Assembly Instructions as a JSON encoded string.

Response

Here’s an example response body:

Upon error, the error key will contain the corresponding error status code.

5.4 Delete a Template

DELETE {TEMPLATE_URL}

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

DELETE Fields

  • Passing signature is required. For more information please check Signature Authentication.
  • Passing params is required. It should contain a JSON encoded object with keys as shown in the table below.

Supported keys inside the params field

Name Type Default Description
auth (required) Object Contains your Transloadit Auth Key in key, and if you enable Signature Authentication, an expiry date for the request in expires. Example:
{
  "key": "2b0c45611f6440dfb64611e872ec3211",
  "expires": "2009/11/27 16:53:14+00:00"
}

Response

Here’s an example response body:

Upon error, the error key will contain the corresponding error status code.

5.5 Retrieve List of Templates

GET https://api2.transloadit.com/templates?signature={SIGNATURE}&params={PARAMS}

GET Query Components

  • Passing signature is required. For more information please check Signature Authentication.
  • Passing params is required. It should contain a JSON encoded (and URL-encoded) object with keys as shown in the table below.

Supported keys inside the params query component

Name Type Default Description
auth (required) Object Contains your Transloadit Auth Key in key, and if you enable Signature Authentication, an expiry date for the request in expires. Example:
{
  "key": "2b0c45611f6440dfb64611e872ec3211",
  "expires": "2009/11/27 16:53:14+00:00"
}
page Integer 1 Specifies the current page, within the current pagination
pagesize Integer(1-5000) 50 Specifies how many Templates to be received per API request, which is useful for pagination.
sort String The field to sort by. Default value is "created". Valid values are ["id", "name", "created", "modified"].
order String The sort direction. Can be "desc" for descending (default) or "asc" for ascending.
fromdate (required) String Specifies the minimum Assembly UTC creation date/time. Only Templates after this time will be retrieved. Use the format Y-m-d H:i:s.
todate String NOW() Specifies the maximum Assembly UTC creation date/time. Only Templates before this time will be retrieved. Use the format Y-m-d H:i:s.
keywords Array of Strings [] Specifies keywords to be matched in the Assembly Status. The Assembly fields checked include the id, redirect_url, fields, and notify_url, as well as error messages and files used.

Response

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