Amazon S3 delivery#

JSON2Video can upload every rendered video to a bucket in your own Amazon S3 account. You create an IAM user that may only upload to your bucket, save its access key once in the dashboard, and reference that saved destination from your movies. Each finished video then lands in your bucket, with no download and re-upload on your side.

Only Amazon S3 is supported for now. S3-compatible services that use their own endpoint (Cloudflare R2, Wasabi, DigitalOcean Spaces, Backblaze B2, MinIO) are not.

Set it up#

You need access to the AWS console with permission to create IAM users.

1. Pick a bucket and note its region#

Use an existing bucket or create one in the S3 console. The default settings of a new bucket are fine: keep Block all public access on. JSON2Video does not need a public bucket.

Write down:

• the bucket's name, for example my-videos — only the name: no s3://, no URL, no folder;
• its region, for example eu-west-1. You find it in the bucket list (AWS Region column) or in the bucket → Properties → AWS Region.

Choose a folder for the videos too, for example videos/. In S3 a folder is just the start of the file's name, so there is nothing to create.

2. Create an IAM user#

In the IAM console, open Users → Create user. Name it, for example json2video-uploader. It does not need access to the AWS console, and it needs no permissions yet: you add them in the next step.

Create a user for JSON2Video only — not your own user, and not one shared with other tools. Its key is stored by JSON2Video, so it should be able to do nothing but upload.

3. Attach the minimal policy#

Open the user → Permissions → Add permissions → Create inline policy → JSON, and paste:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["s3:PutObject", "s3:AbortMultipartUpload"],
    "Resource": "arn:aws:s3:::BUCKET/FOLDER/*"
  }]
}

Replace BUCKET with the bucket name and FOLDER with your folder, without a slash at the end: arn:aws:s3:::my-videos/videos/*. To allow the whole bucket, leave the folder out: arn:aws:s3:::my-videos/*. Give the policy a name (for example json2video-upload) and create it.

• Scope it to the folder before any macro. If your folder uses macros, put in the policy only the part before the first macro. For the folder videos/__yyyy__/__mm__/, use arn:aws:s3:::my-videos/videos/*. A policy on videos/2026/* would let this year's videos through, but the test would fail, and deliveries would stop in January.
• s3:PutObject writes the videos. s3:AbortMultipartUpload lets JSON2Video cancel an upload that cannot finish, so no unfinished parts stay in your bucket (videos larger than 8 MB are uploaded in parts).
• JSON2Video never lists, reads or deletes anything in your bucket, so the policy needs no s3:ListBucket, s3:GetObject or s3:DeleteObject.

The dashboard shows this policy, filled in with the bucket and folder you type, under Minimal IAM policy, with a copy button.

If the bucket is encrypted with an AWS KMS key that you manage, the user also needs permission to use that key: see Encrypted buckets (SSE-KMS).

4. Create an access key#

Open the user → Security credentials → Access keys → Create access key. As the use case, choose Third-party service (or Application running outside AWS), confirm, and create the key.

AWS shows two values:

• the Access key ID: 20 characters, starting with AKIA;
• the Secret access key: 40 characters. AWS shows it only once. Copy it now or download the .csv file. If you lose it, create a new access key.

Use a long-term access key of an IAM user (it starts with AKIA). Temporary keys (they start with ASIA, for example from AWS IAM Identity Center, an assumed role or aws sts) are refused: they stop working within hours.

5. Add the destination in the dashboard#

In Dashboard → Connections → Output destinations, click Add destination → Amazon S3 and fill in:

6. Test it#

Click Test destination in the form, or Test in the row menu once it is saved. JSON2Video writes a small text file, json2video-test.txt, to your folder and shows the result. See The test file.

7. Use it in a movie#

Reference the destination by its ID in exports[].destinations. Copy JSON in the row menu copies this snippet:

{
  "resolution": "full-hd",
  "scenes": [ /* ... */ ],
  "exports": [{
    "destinations": [
      { "type": "aws-s3", "id": "my-s3" }
    ]
  }]
}

A movie may change the folder and the file name for one render:

{
  "exports": [{
    "destinations": [{
      "type": "aws-s3",
      "id": "my-s3",
      "remote-path": "customers/acme/__yyyy__/",
      "file": "acme-promo-__random__.mp4"
    }]
  }]
}

Nothing else can be set in the movie. The bucket, the region and the keys always come from the saved destination:

• Never put AWS keys in the movie JSON. POST /v2/movies refuses a movie whose destinations carry AWS keys (access-key-id, secret-access-key or a similar field, or an access key ID anywhere in an aws-s3 destination): HTTP 400, code aws_keys_in_movie. Nothing is rendered. If those keys were real, rotate them in AWS: they were sent in a request.
• Any other field next to id (for example bucket or region) makes the delivery fail with In an aws-s3 destination the movie can only set remote-path and file. …. Nothing is uploaded.
• There is no inline form: an aws-s3 destination without id fails with An aws-s3 destination needs the ID of a saved connection ….
• "type": "aws-s3" is optional next to id. If you write it, it must match the saved destination's type.

Properties#

The object's name in S3 (its key) is the folder and the file name joined with /. A leading / or ./ and double slashes are ignored, so /videos//2026/ becomes videos/2026/. A .. folder is refused, and the whole key can be at most 1,024 bytes.

File names and folders#

remote-path and file accept the same macros as FTP and SFTP: __yyyy__, __mm__, __dd__, __hh__, __nn__, __ss__, __random__, __filename__ and more. See Filename macros.

{
  "remote-path": "customers/acme/__yyyy__/__mm__/",
  "file": "acme-promo-__yyyy__-__mm__-__dd__-__random__.mp4"
}

Keep the .mp4 extension in file: it sets the file's content type (see below).

How the upload works#

• Only the video is uploaded, not its thumbnail.
• Existing files are overwritten. A key that already exists is replaced, without an error. On a bucket with versioning, S3 keeps the previous version. Use __random__ or the date and time macros for unique names.
• Private by default. JSON2Video sends no ACL, no storage class and no encryption setting: the file gets your bucket's own settings (default encryption, Object Ownership, Block Public Access). It stays private unless your bucket makes it public.
• Content type: video/mp4 when the file name ends in .mp4, otherwise application/octet-stream.
• Large videos are streamed to your bucket in parts of 8 MB.
• Failed renders: there is no video, so Amazon S3 destinations are skipped (Nothing to upload: the render did not produce a video.).
• Wrong region: if the bucket is not in the region you saved, AWS tells JSON2Video the right one and the video is still delivered, but the result adds a warning, for example The bucket is in eu-west-1, not us-east-1: edit the connection. Correct the region to remove it.
• Temporary errors from AWS or the network are retried automatically within the same delivery. The result counts it as 1 attempt.
• Timeout: all destinations of a render share a budget of about 5 minutes. A very large video, or slow destinations before it in the list, can use it up. The upload is then stopped and cancelled (Stopped: the delivery ran out of time.).
• Order and failures: destinations run one after another, in the order of the array. A failed upload does not stop the destinations after it, and the movie's status stays done. The result is recorded in the movie's destinations_result, under Render logs → the render → Deliveries, and in the Last delivery column of the saved destination.

The test file#

Test checks the bucket, the region, the access key and the policy with one real upload:

• It writes json2video-test.txt to the part of the Folder before its first macro. For the folder videos/__yyyy__/, that is videos/json2video-test.txt. With an empty folder, or one that starts with a macro, the file goes to the root of the bucket.
• The file holds one line: JSON2Video wrote this file to test the destination "my-s3" on <date and time>. You can delete it.
• JSON2Video never deletes it — the minimal policy does not allow deleting. Delete it yourself, or leave it: the next test overwrites it without an error.
• It never lists, reads or deletes anything in your bucket.
• It uses the values in the form, saved or not. An empty Secret access key field uses the stored one.
• It waits up to 10 seconds for AWS.
• It counts towards the limit of 20 tests per hour.

When it works, the result reads like Wrote json2video-test.txt to bucket my-videos, folder videos (the part of the remote path before its first macro). JSON2Video does not delete it: you can. Otherwise it shows one of the messages in Troubleshooting.

If the region you chose is not the bucket's, the test still works but its result is shown as a warning, Destination works, but the region is wrong, ending with The bucket is in eu-west-1, not us-east-1: edit the connection. In the form, click Use eu-west-1 to switch the Region field to the bucket's region, then save.

The test fails, but deliveries work? The test writes to the folder before the first macro, which is above the folders your deliveries use. A policy narrower than that folder — for example videos/2026/* for the folder videos/__yyyy__/ — lets deliveries through and denies the test. Scope the policy to the part before the first macro (videos/*), as the dashboard's Minimal IAM policy does.

Recommended bucket settings#

Delete incomplete multipart uploads#

Videos larger than 8 MB are uploaded in parts. When an upload is stopped (for example because the time budget ran out), JSON2Video cancels it. If the cancellation does not reach AWS, the parts already uploaded stay in the bucket: you don't see them in the file list, but AWS bills them as storage. A lifecycle rule removes them:

1. In the S3 console, open the bucket → Management → Create lifecycle rule.
2. Name it, for example delete-incomplete-uploads, and apply it to all objects in the bucket.
3. Under Lifecycle rule actions, tick Delete expired object delete markers or incomplete multipart uploads.
4. Tick Delete incomplete multipart uploads and set Number of days to 1.
5. Create the rule.

Encrypted buckets (SSE-KMS)#

Buckets encrypted with Amazon S3 managed keys (SSE-S3, the default) need nothing more. If the bucket's default encryption uses an AWS KMS key that you manage, the IAM user also needs kms:GenerateDataKey and kms:Decrypt on that key (kms:Decrypt is needed for uploads in parts). Add a second statement to the user's policy:

{
  "Effect": "Allow",
  "Action": ["kms:GenerateDataKey", "kms:Decrypt"],
  "Resource": "arn:aws:kms:REGION:ACCOUNT_ID:key/KEY_ID"
}

The key's own policy must not deny the user either. Without these permissions, deliveries fail with Bucket my-videos encrypts objects with an AWS KMS key this access key may not use. ….

Why AWS denies the upload (AccessDenied)#

The access key may not write to bucket … means AWS denied the upload. The IAM user's policy is the usual cause, but not the only one:

• the policy allows another folder than the one the video goes to — check the remote-path of the destination and of your movies;
• a bucket policy with a Deny that matches the upload, for example one that only allows some IP addresses or VPC endpoints (JSON2Video does not upload from a fixed IP address), or one that requires an encryption or ACL header (JSON2Video sends neither);
• a service control policy (SCP) or resource control policy of your AWS Organization;
• a permissions boundary on the IAM user.

Troubleshooting#

Messages shown by Test and in the delivery results (destinations_result, Deliveries). my-videos, videos, my-s3 and the regions stand for your own values.

Messages shown when you save a destination (bucket name, region, key format) are listed in the errors reference.

See also#

• Dashboard connections guide
• FTP / SFTP delivery
• Webhooks
• Errors reference