Saving result files

Example Assembly Status JSON

After the image resizing from My first App, the crop_thumbed Step produces a 1500x500 image. This illustrative Assembly Status JSON excerpt shows the fields needed to identify and save that result. Other status fields are omitted; IDs and example URLs will differ in your actual response.

{
  "assembly_id": "7828446e5acd4aa996dce3455ec914e9",
  "ok": "ASSEMBLY_COMPLETED",
  "uploads": [
    {
      "id": "a30bd0776e7f4ac3817b056d102e8219",
      "name": "joe-gardner-149699.jpg",
      "ssl_url": "https://temporary-files.example/upload.jpg"
    }
  ],
  "results": {
    "crop_thumbed": [
      {
        "id": "b8d12f6c517541ca86bf50c537cedb27",
        "original_id": "a30bd0776e7f4ac3817b056d102e8219",
        "name": "joe-gardner-149699.jpg",
        "ssl_url": "https://temporary-files.example/resized.jpg",
        "meta": {
          "width": 1500,
          "height": 500
        }
      }
    ]
  }
}

As you can see, Transloadit provides the final locations and metadata for:

all the uploaded files - in the uploads key
all produced result files - in the results key

Each file object contains metadata as well as an ssl_url that points to the result. If you used one of our export Robots, these locations will reflect your specified storage, such as your S3 bucket. Otherwise, the location is a temporary URL that will be removed after 24 hours.

Warning

Temporary URLs are for downloading files once to your own storage only. Never share these URLs with end users or use them in production. See temporary storage restrictions for important usage limitations.

Depending on your integration, you can either:

Process the results locally where you issue the request,
Have the results added to a form and posted to your backend, or
(With Async Mode) Let Transloadit post the Assembly Status JSON to your notify_url, which you can then use to save entries in your database.

There's an example for this on the Webhooks page.

Displaying result files to your end-users

After saving the files to persistent storage, and saving any metadata that is useful for your app to your database, you can serve them to your users. Replace the placeholder URL below with the URL in your own storage to show the cropped image:

<img
  alt="Resized uploaded image"
  src="https://your-storage.example/resized.jpg"
/>

If you were dealing with video, you could look into players such as HLS.js, Plyr or indigo-player, which also support HTTP live streaming and MPEG-DASH.

When saving file processing results, do not rely on their order

When your encoding results are finished and Transloadit POSTs to your result URL or Assembly Notification URL, please do not rely on the proper order of results.

Imagine you have two 🤖/image/resize Steps in your Template that use the :original step. Like so:

{
  "steps": {
    "high": {
      "use": ":original",
      "robot": "/image/resize",
      "width": 500,
      "height": 500
    },
    "low": {
      "use": ":original",
      "robot": "/image/resize",
      "width": 200,
      "height": 200
    }
  }
}

When you upload 30 photos with this Template, the resulting Assembly JSON contains two result arrays: "results" -> "high" and "results" -> "low". The order of images within these arrays is not the same, though! The first "high" result could be a derivative of the 15th uploaded photo, whereas the first result in the "low" array might be a derivative of the 10th uploaded photo.

If you need to match encoding results to their corresponding uploads (you likely need to), please match them by the id property from the "uploads" array entries and the original_id property of the entries in your various result arrays.

Store the originally uploaded files

Storing not only the encoded result files, but also the files that your users originally uploaded gives you the chance to re-encode them later on into different formats as your requirements change. If you do not store them, they are lost forever, because asking your users to upload them again is likely not an option.

Store any metadata

In addition to the above, keep in mind that Assemblies are ephemeral. Transloadit purges records after 90 days, so if you want to hang on to any metadata inside of them, you should import it to your datastore.