Saving result files

Example Assembly Status JSON

Let's take a look at the full Assembly Status JSON that you would receive after we processed the image resizing from My first App:

{
  "assembly_id": "7828446e5acd4aa996dce3455ec914e9",
  "ok": "ASSEMBLY_COMPLETED",
  "message": "The Assembly was successfully completed.",
  "warnings": [],
  "account_id": "4ce4fb3d9d1842b6ba5d6f3ccee4b066",
  "assembly_ssl_url": "https://api2-jenks.transloadit.com/assemblies/7828446e5acd4aa996dce3455ec914e9",
  "assembly_url": "http://api2.jenks.transloadit.com/assemblies/7828446e5acd4aa996dce3455ec914e9",
  "build_id": "339",
  "bytes_expected": 486608,
  "bytes_received": 486608,
  "bytes_usage": 1097155,
  "client_agent": null,
  "client_ip": null,
  "client_referer": null,
  "companion_url": "https://api2-jenks.transloadit.com/companion/",
  "executing_jobs": [],
  "execution_duration": 5.281,
  "execution_start": "2020/01/09 12:02:08 GMT",
  "expected_tus_uploads": 1,
  "fields": {},
  "finished_tus_uploads": 1,
  "has_dupe_jobs": false,
  "instance": "jenks.transloadit.com",
  "is_infinite": false,
  "jobs_queue_duration": 0.01,
  "last_job_completed": "2020/01/09 12:02:14 GMT",
  "merged_params": "{\"steps\":{\":original\":{\"robot\":\"/upload/handle\"},\"faces_detected\":{\"use\":\":original\",\"robot\":\"/image/facedetect\",\"crop\":true,\"faces\":\"max-confidence\",\"format\":\"preserve\",\"crop_padding\":\"10%\"},\"exported\":{\"use\":[\"faces_detected\",\":original\"],\"robot\":\"/s3/store\",\"credentials\":\"demo_s3_credentials\"}},\"auth\":{\"key\":\"****\",\"expires\":\"2020-01-10T12:02:05.826Z\"}}",
  "notify_duration": null,
  "notify_response_code": null,
  "notify_start": null,
  "notify_status": null,
  "notify_url": null,
  "params": "{\"steps\":{\":original\":{\"robot\":\"/upload/handle\"},\"faces_detected\":{\"use\":\":original\",\"robot\":\"/image/facedetect\",\"crop\":true,\"faces\":\"max-confidence\",\"format\":\"preserve\",\"crop_padding\":\"10%\"},\"exported\":{\"use\":[\"faces_detected\",\":original\"],\"robot\":\"/s3/store\",\"credentials\":\"demo_s3_credentials\"}},\"auth\":{\"key\":\"****\",\"expires\":\"2020-01-10T12:02:05.826Z\"}}",
  "parent_assembly_status": null,
  "parent_id": null,
  "queue_duration": 0.184,
  "running_jobs": [],
  "start_date": "2020/01/09 12:02:06 GMT",
  "started_jobs": [
    ":original:::original",
    "faces_detected:::original",
    "exported:::original",
    "exported::faces_detected"
  ],
  "started_tus_uploads": 1,
  "template": null,
  "template_id": null,
  "transloadit_client": "node-sdk:2.0.8",
  "tus_url": "https://api2-jenks.transloadit.com/resumable/files/",
  "upload_duration": 2.814,
  "upload_meta_data_extracted": true,
  "uppyserver_url": "https://api2-jenks.transloadit.com/companion/",
  "websocket_url": "https://api2-jenks.transloadit.com/ws20074",
  "uploads": [
    {
      "id": "a30bd0776e7f4ac3817b056d102e8219",
      "basename": "joe-gardner-149699",
      "ext": "jpg",
      "field": "file",
      "from_batch_import": false,
      "is_tus_file": true,
      "md5hash": "fb205cb04b6998fe7ba364f70227cfa1",
      "mime": "image/jpeg",
      "name": "joe-gardner-149699.jpg",
      "original_basename": "joe-gardner-149699",
      "original_id": "a30bd0776e7f4ac3817b056d102e8219",
      "original_md5hash": "fb205cb04b6998fe7ba364f70227cfa1",
      "original_name": "joe-gardner-149699.jpg",
      "original_path": "/",
      "size": 485784,
      "ssl_url": "https://s3.amazonaws.com/demos.transloadit.com/a3/0bd0776e7f4ac3817b056d102e8219/joe-gardner-149699.jpg",
      "tus_upload_url": "https://api2-jenks.transloadit.com/resumable/files/f95ba7eebf22e0ebadcf9b09a3a91c65+DRCJv78IeFDneTwnYb3pagc8Bqg7IwlRAFpW8e3i.f4RSPIZXEeaxdheZiTBBvJ0pAyjxL3.U5TvUqWytvkObgz6Bh55biPZwLqzIK_mwRbjGl0UREMrju1zfy8.OgTg",
      "type": "image",
      "url": "http://demos.transloadit.com.s3.amazonaws.com/a3/0bd0776e7f4ac3817b056d102e8219/joe-gardner-149699.jpg",
      "meta": {
        "aspect_ratio": "1.500",
        "average_color": "#b09d96",
        "colorspace": "RGB",
        "date_file_modified": "2020/01/09 12:02:08 GMT",
        "frame_count": 1,
        "has_clipping_path": false,
        "has_transparency": false,
        "height": 1667,
        "width": 2500
      }
    }
  ],
  "results": {
    ":original": [
      {
        "id": "a30bd0776e7f4ac3817b056d102e8219",
        "basename": "joe-gardner-149699",
        "cost": 97157,
        "execTime": 0.81,
        "ext": "jpg",
        "field": "file",
        "from_batch_import": false,
        "is_tus_file": false,
        "md5hash": "fb205cb04b6998fe7ba364f70227cfa1",
        "mime": "image/jpeg",
        "name": "joe-gardner-149699.jpg",
        "original_basename": "joe-gardner-149699",
        "original_id": "a30bd0776e7f4ac3817b056d102e8219",
        "original_md5hash": "fb205cb04b6998fe7ba364f70227cfa1",
        "original_name": "joe-gardner-149699.jpg",
        "original_path": "/",
        "queue": "live",
        "queueTime": 0.01,
        "size": 485784,
        "ssl_url": "https://s3.amazonaws.com/demos.transloadit.com/a3/0bd0776e7f4ac3817b056d102e8219/joe-gardner-149699.jpg",
        "tus_upload_url": null,
        "type": "image",
        "url": "http://demos.transloadit.com.s3.amazonaws.com/a3/0bd0776e7f4ac3817b056d102e8219/joe-gardner-149699.jpg",
        "meta": {
          "aspect_ratio": "1.500",
          "average_color": "#b09d96",
          "colorspace": "RGB",
          "date_file_modified": "2020/01/09 12:02:08 GMT",
          "frame_count": 1,
          "has_clipping_path": false,
          "has_transparency": false,
          "height": 1667,
          "width": 2500
        }
      }
    ],
    "faces_detected": [
      {
        "id": "b8d12f6c517541ca86bf50c537cedb27",
        "basename": "joe-gardner-149699",
        "cost": 627606,
        "execTime": 0.83,
        "ext": "jpg",
        "field": "file",
        "from_batch_import": false,
        "is_tus_file": false,
        "md5hash": "2a5cd917f4281b9438956e489c63dfd2",
        "mime": "image/jpeg",
        "name": "joe-gardner-149699.jpg",
        "original_basename": "joe-gardner-149699",
        "original_id": "a30bd0776e7f4ac3817b056d102e8219",
        "original_md5hash": "fb205cb04b6998fe7ba364f70227cfa1",
        "original_name": "joe-gardner-149699.jpg",
        "original_path": "/",
        "queue": "live",
        "queueTime": 0,
        "size": 141822,
        "ssl_url": "https://s3.amazonaws.com/demos.transloadit.com/b8/d12f6c517541ca86bf50c537cedb27/joe-gardner-149699.jpg",
        "tus_upload_url": null,
        "type": "image",
        "url": "http://demos.transloadit.com.s3.amazonaws.com/b8/d12f6c517541ca86bf50c537cedb27/joe-gardner-149699.jpg",
        "meta": {
          "aspect_ratio": "0.739",
          "average_color": "#8d654d",
          "colorspace": "RGB",
          "date_file_created": "2020/01/09 12:02:09 GMT",
          "date_file_modified": "2020/01/09 12:02:12 GMT",
          "faces": [
            {
              "confidence": 99.99,
              "height": 840,
              "width": 621,
              "x1": 981,
              "x2": 1550,
              "y1": 121,
              "y2": 891
            }
          ],
          "frame_count": 1,
          "has_clipping_path": false,
          "has_transparency": false,
          "height": 840,
          "width": 621
        }
      }
    ]
  }
}

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

all the uploaded files - all the way at the bottom, 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. In our case, we'll show the cropped image like this:

<img
  alt="avatar"
  src="https://s3.amazonaws.com/demos.transloadit.com/7b/22df50590d11e8be51b7c2c7cc7e22/joe-gardner-149699.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.