Shotstack integrates with AWS S3

We’re excited to announce the AWS S3 destination is now available. The AWS S3 destination enables users to easily integrate their one or more S3 buckets to send rendered videos in just a few steps.

This integration makes it easy to send rendered videos to your S3 bucket. The S3 destination has options to configure custom settings like region, access, and setting up multiple buckets.

Configuring basic S3 destination

To configure your AWS S3 destination, go to your Shotstack dashboard. Under the Integrations tab, click the configure button.

You can configure it for either the Sandbox or the Production Shotstack environment. You can use an exisiting AWS access key or create a new key.

We recommend creating a new user with IAM permissions that only allows access to the buckets needed. Do not use a user with root or global permissions.

Basic setup

To send files to your S3 buckets, add the following JSON to the output parameter of your render requests JSON payload:

"destinations": [{
    "provider": "s3",
    "options": {
        "region": "ap-southeast-2",
        "bucket": "my-s3-bucket"
    }
}]

This will send the rendered files to the my-s3-bucket in the ap-southeast-2 region. The filename will be the render id plus extension, i.e. edc47d30-a504-4f16-8439-24c863a7a782.mp4, and will be saved to the root level of the bucket. Thumbnail and poster images will also be transferred.

Custom setup

You can also optionally set a prefix (path), custom file name, and set an acl (the default is private):

"destinations": [{
    "provider": "s3",
    "options": {
        "region": "ap-southeast-2",
        "bucket": "my-s3-bucket",
        "prefix": "testing",
        "filename": "video",
        "acl": "public-read"
    }
}]

This will send the rendered files to the my-s3-bucket in the ap-southeast-2 region. If the rendered file is an mp4, the filename will be video.mp4 and will be saved with a prefix testing (virtual path in the console). The acl will also be set to public-read, which is suitable for public hosting.

When using a custom filename omit the file extension, i.e. .mp4 or .jpg. This will be added based on the rendered file type. If a poster or thumbnail is created these will have -poster.jpg and -thumbnail.jpg appended.

Multiple buckets

It is also possible to send files to multiple buckets:

"destinations": [{
    "provider": "s3",
    "options": {
        "region": "ap-southeast-2",
        "bucket": "my-s3-bucket"
    }
},{
    "provider": "s3",
    "options": {
        "region": "us-east-1",
        "bucket": "my-us-s3-bucket"
    }
}]

This will send the rendered files to the my-s3-bucket in the ap-southeast-2 region to the my-us-s3-bucket in the us-east-1 region. Buckets must be in the same AWS account and use the same IAM access credentials.

Opting out from the Shotstack destination

By default, all generated files are sent to your Shotstack hosting account. If you are using S3 you may wish to opt out from hosting your videos with Shotstack. Visit Docs to learn more.

"destinations": [{
    "provider": "s3",
    "options": {
        "region": "ap-southeast-2",
        "bucket": "my-s3-bucket"
    }
},{
    "provider": "shotstack",
    "exclude": true
}]

This will send a generated video to S3 but not to your Shotstack hosting account.

Destination response examples

Let’s use a simple Hello World JSON template shown below to demonstrate saving a file to our own S3 bucket. You can see the custom S3 destination JSON below.

{
    "timeline": {
        "tracks": [
            {
              "clips": [
                  {
                    "asset": {
                        "type": "html",
                        "html": "<p data-html-type=\"text\">H E L L O  W O R L D</p>",
                        "css": "p { color: #ffffff; font-size: 22px; font-family: Work Sans Light; text-align: center }",
                        "width": 362,
                        "height": 60
                    },
                    "start": 0,
                    "length": 11
                  }
              ]
          }
        ]
    },
    "output": {
      "format": "mp4",
      "resolution": "sd",
      "destinations": [
              {
                  "provider": "s3",
                  "options": {
                      "region": "ap-southeast-2",
                      "bucket": "my-s3-bucket",
                      "prefix": "testing",
                      "filename": "video",
                      "acl": "public-read"
                  }
              }
          ]
    }
  }

The next step is sending a POST request to render the JSON using the render endpoint. I’ll use curl to send render a request but you can use any programming language or API management tool like Postman.

Make sure you replace YOUR_API_KEY with your actual stage API key. I have named my JSON file as hello.json.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d @hello.json \
  https://api.shotstack.io/stage/render

You should see a response similar to:

{
  "success": true,
  "message": "Created",
  "response": {
    "message": "Render Successfully Queued",
    "id": "d2b46ed6-998a-4d6b-9d91-b8cf0193a655"
  }
}

Now let’s use the serve API to check if the files have been transferred to my S3 bucket. You should see similar response if the render and S3 destination was successful.

{
  "data": [
      {
          "type": "assets",
          "attributes": {
              "id": "IGTRoiUvdu6fgFXDgdEhY6UZ8YN5uaYd1bYNaS01",
              "owner": "lu8ta6o0i8",
              "provider": "s3",
              "renderId": "7bad5314-0c18-4f51-a6cb-2aebc324f1eb",
              "providerId": "testing/hello.mp4",
              "filename": "7bad5314-0c18-4f51-a6cb-2aebc324f1eb.mp4",
              "url": "https://shotstack-s3-integration-au.s3.us-west-2.amazonaws.com/testing/hello.mp4",
              "status": "ready",
              "created": "2022-09-29T00:15:11.884Z",
              "updated": "2022-09-29T00:15:12.486Z"
          }
      }
  ]
}

The above response shows providerId, filename created in the bucket, url, and status. If you get a 404 response, then the video is still rendering. If the keys are not configured correctly, then you will get an error response No S3 credentials found. Add credentials via the dashboard.

You can click on the URL to see the transferred file. You can see the transferred videos in the AWS Console as shown below.

We are looking at adding more destinations to other 3rd party services over the coming months. If there is a hosting provider, social network, or storage provider you want us to add, reach out to us via the Shotstack community forum.