Create AWS Connection for Private S3 Assets

curl --request POST \
  --url https://api.pictory.ai/pictoryapis/v1/awsconnections \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "awsAccountId": "<string>",
  "awsRegion": "<string>",
  "enabled": true
}
'

{
  "enabled": true,
  "name": "PictoryPrivateVideosConnection",
  "description": "Pictory Private Videos Connection",
  "awsAccountId": "123456789012",
  "awsRegion": "us-east-2",
  "connectionId": "20241207042423053xmex5z9ag9ivmp21",
  "version": 1
}

POST

pictoryapis

awsconnections

Create AWS Connection for Private S3 Assets

curl --request POST \
  --url https://api.pictory.ai/pictoryapis/v1/awsconnections \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "awsAccountId": "<string>",
  "awsRegion": "<string>",
  "enabled": true
}
'

{
  "enabled": true,
  "name": "PictoryPrivateVideosConnection",
  "description": "Pictory Private Videos Connection",
  "awsAccountId": "123456789012",
  "awsRegion": "us-east-2",
  "connectionId": "20241207042423053xmex5z9ag9ivmp21",
  "version": 1
}

Overview

This guide shows you how to connect your private AWS S3 storage to Pictory, so you can use your own videos and images stored in Amazon S3 buckets to create Pictory videos. What you will accomplish:

Connect Pictory to your private AWS S3 storage
Use your private videos and images in Pictory without making them public
Keep your assets secure with AWS IAM role-based access

Prerequisites: You will need an AWS account with access to create IAM roles. If you do not have AWS experience, consider asking your IT team for help with the AWS setup steps below.

Prerequisites: AWS IAM Role Setup

This creates a secure “key” (called an IAM role) that lets Pictory access your private S3 files without making them public.

How It Works

Think of this like giving Pictory a guest pass to your storage:

You create a special role in AWS (the “guest pass”)
You tell AWS that Pictory is allowed to use this role
You specify which folders/buckets Pictory can access
Pictory uses this role to fetch your videos and images when creating content

Step 1: Log in to AWS Console

Go to AWS Management Console
Sign in with your AWS account credentials
In the search bar at the top, type “IAM” and click on the IAM service

What is IAM? IAM (Identity and Access Management) is AWS’s security system that controls who can access what in your AWS account.

Step 2: Start Creating a New Role

On the left sidebar, click Roles
Click the orange Create role button

What is a Role? A role is like a job title with specific permissions. You’re creating a “Pictory Access” role that can only read your S3 files.

Step 3: Set Up Trust with Pictory

This step tells AWS that Pictory’s account is allowed to use this role.

Under Trusted entity type, select Another AWS account
In the Account ID field, enter: 701488979254 (this is Pictory’s AWS account)
Click Next
On the permissions page, click Next (we will add permissions in the next step)
Under Role name, enter exactly: PictoryCloudIntegrationRole (this exact name is required)
Click Create role

Step 4: Give Permission to Access Your S3 Bucket

This step specifies which S3 bucket Pictory can access and what it can do (read files and list files).

In the search box, find the role you just created: PictoryCloudIntegrationRole
Click on it to open the role details
Click the Permissions tab
Click Add permissions → Create inline policy
Click the JSON tab (ignore the visual editor)
Delete everything in the box and paste this:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetObject"
            ],
            "Resource": [
                "arn:aws:s3:::{YOUR_S3_BUCKET}",
                "arn:aws:s3:::{YOUR_S3_BUCKET}/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListAllMyBuckets"
            ],
            "Resource": [
                "arn:aws:s3:::*"
            ]
        }
    ]
}

Important: Replace {YOUR_S3_BUCKET} with your actual bucket name (for example, if your bucket is named “my-company-videos”, replace both instances with “my-company-videos”)
Click Next
Name the policy: s3_access_policy
Click Create policy

What this does:

s3:ListBucket - Lets Pictory see what files are in your bucket
s3:GetObject - Lets Pictory read/download the files
Pictory can only READ files, it cannot modify or delete them

Step 5: Configure Trust Relationship (Advanced)

This step sets up the detailed trust relationship between your AWS account and Pictory.

In the role details, click the Trust relationships tab
Click Edit trust policy
Delete everything and paste this:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::701488979254:role/CloudIntegrationRole"
            },
            "Action": "sts:AssumeRole",
            "Condition": {}
        },
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::701488979254:role/ecsTaskExecutionRole"
            },
            "Action": "sts:AssumeRole",
            "Condition": {}
        },
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::701488979254:root"
            },
            "Action": "sts:AssumeRole",
            "Condition": {}
        }
    ]
}

Click Update policy

What this does: This lists three Pictory systems that are allowed to use this role:

CloudIntegrationRole - Handles the API connection
ecsTaskExecutionRole - Processes your videos
root - Backup access for Pictory’s account

Step 6: Gather Information for API Call

You’ll need these two pieces of information to make the API call:Your AWS Account ID:

In the AWS Console, click your account name in the top-right corner
Your 12-digit Account ID is shown there (for example: 123456789012)

Your S3 Bucket’s Region:

Go to the S3 service in AWS Console
Find your bucket in the list
The region is shown next to the bucket name (for example: us-east-1, us-west-2, etc.)

Write these down - you will use them in the next section when making the API call!

Making the API Call

Now that your AWS role is set up, you can make a simple API call to connect it to Pictory. What you will need:

Your API key (starts with pictai_ - get this from the API Access page)
Your 12-digit AWS Account ID (from Step 6 above)
Your S3 bucket’s region (from Step 6 above)

API Endpoint

POST https://api.pictory.ai/pictoryapis/v1/awsconnections

Request Parameters

For non-technical users: The sections below show what information you need to include in your API request. If you are using a tool like Postman or writing code, these are the fields you will fill in.

Headers

Authorization

string

required

API key for authentication (starts with pictai_)

Authorization: YOUR_API_KEY

Get your API key from the API Access page in your Pictory dashboard.

Content-Type

string

required

Must be set to application/json

Body Parameters

name

string

required

A unique name for the AWS connectionExample: "PictoryPrivateVideosConnection"

description

string

Optional description of the AWS connectionExample: "Pictory Private Videos Connection"

awsAccountId

string

required

Your 12-digit AWS account IDFormat: 12-digit numeric stringExample: "123456789012"

awsRegion

string

required

The AWS region where your S3 bucket is locatedCommon Regions:

us-east-1 - US East (N. Virginia)
us-east-2 - US East (Ohio)
us-west-1 - US West (N. California)
us-west-2 - US West (Oregon)
eu-west-1 - Europe (Ireland)
eu-central-1 - Europe (Frankfurt)
ap-southeast-1 - Asia Pacific (Singapore)
ap-northeast-1 - Asia Pacific (Tokyo)

Example: "us-east-2"

enabled

boolean

required

Whether the AWS connection is enabled (should be true to activate the connection)Default: true

Request Body Example

Here’s what the complete request looks like. Replace the example values with your actual AWS details:

{
  "name": "PictoryPrivateVideosConnection",
  "description": "Pictory Private Videos Connection",
  "awsAccountId": "123456789012",        ← Replace with your 12-digit AWS Account ID
  "awsRegion": "us-east-2",              ← Replace with your S3 bucket's region
  "enabled": true
}

Quick tip: You can leave out the description field if you do not need it - it is optional!

Response

When the connection is successful, Pictory will send back a response confirming the details.

Save your connectionId! You’ll use this ID when making video API calls to tell Pictory which S3 connection to use. When using it in video creation requests, the field name becomes awsConnectionId (not just connectionId).

Response Examples

{
  "enabled": true,
  "name": "PictoryPrivateVideosConnection",
  "description": "Pictory Private Videos Connection",
  "awsAccountId": "123456789012",
  "awsRegion": "us-east-2",
  "connectionId": "20241207042423053xmex5z9ag9ivmp21",
  "version": 1
}

Code Examples

Here are complete working examples in different programming languages. Pick the one that matches your programming language.

New to APIs? If these code examples look confusing, consider using a tool like Postman or Insomnia - they provide a visual interface where you can just fill in fields instead of writing code.

# This is for terminal/command line use
# Replace YOUR_API_KEY with your actual API key
# Replace 123456789012 with your AWS Account ID
# Replace us-east-2 with your S3 bucket's region

curl --request POST \
  --url https://api.pictory.ai/pictoryapis/v1/awsconnections \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "name": "PictoryPrivateVideosConnection",
    "description": "Pictory Private Videos Connection",
    "awsAccountId": "123456789012",
    "awsRegion": "us-east-2",
    "enabled": true
  }' | python -m json.tool

Using Your S3 Assets in Videos

Now that you have created the connection, you can use your private S3 files in Pictory videos by including the awsConnectionId and referencing files with the s3:// format.

Example Video Request

Here is a simple example of creating a video using your private S3 files:

{
  "awsConnectionId": "20241207042423053xmex5z9ag9ivmp21",  ← Use your connectionId here
  "videoName": "My Marketing Video",
  "videoDescription": "Company intro video",
  "language": "en",
  "scenes": [
    {
      "text": "Welcome to our company!",
      "backgroundUri": "s3://my-private-bucket/intro.mp4",  ← Your private S3 file
      "backgroundType": "video",
      "minimumDuration": 5
    },
    {
      "text": "We're excited to have you here!",
      "backgroundUri": "s3://my-private-bucket/office.jpg",  ← Private S3 image
      "backgroundType": "image",
      "minimumDuration": 5
    }
  ]
}

How to Reference Your S3 Files

You can use either of these two formats to point to your S3 files:

S3 Protocol (Recommended)
HTTPS URL

s3://your-bucket-name/path/to/file.mp4

Example:

s3://my-company-videos/marketing/intro.mp4

https://your-bucket-name.s3.region-name.amazonaws.com/path/to/file.mp4

Example:

https://my-company-videos.s3.us-east-2.amazonaws.com/marketing/intro.mp4

Remember to use awsConnectionId in your video requests, not connectionId. The API response gives you connectionId, but you need to rename it to awsConnectionId when making video requests.

Troubleshooting

Invalid AWS Account ID

Make sure your Account ID is exactly 12 digits (example: 123456789012) with no spaces or dashes.Where to find it: In AWS Console, click your account name in the top-right corner

Unauthorized Error

Your API key may be invalid or expired. Get your API key from the API Access page in your Pictory dashboard.

Duplicate Connection Error

You already have a connection with this name or AWS account/region. Try a different connection name.

Videos Can't Access S3 Files

Check these in order:

Role name must be exactly: PictoryCloudIntegrationRole
Bucket name in your S3 URIs must match your IAM policy
Region must match where your S3 bucket is located
Trust policy includes all three Pictory roles (from Step 5)

Get API Key

Access your API key from your Pictory dashboard

Video Storyboard API

Create videos using your private S3 assets

Get AWS Connections

Retrieve all your configured AWS connections

Update AWS Connection

Modify or disable an existing connection

Delete AWS Connection

Remove an AWS connection

AWS IAM Documentation

Official AWS IAM documentation

Delete Vimeo Connection Get AWS Private Connections

⌘I

Documentation Index

​Overview

​Prerequisites: AWS IAM Role Setup

​How It Works

​Making the API Call

​API Endpoint

​Request Parameters

​Headers

​Body Parameters

​Request Body Example

​Response

​Response Examples

​Code Examples

​Using Your S3 Assets in Videos

​Example Video Request

​How to Reference Your S3 Files

​Troubleshooting

Get API Key

Video Storyboard API

Get AWS Connections

Update AWS Connection

Delete AWS Connection

AWS IAM Documentation

Overview

Prerequisites: AWS IAM Role Setup

How It Works

Making the API Call

API Endpoint

Request Parameters

Headers

Body Parameters

Request Body Example

Response

Response Examples

Code Examples

Using Your S3 Assets in Videos

Example Video Request

How to Reference Your S3 Files

Troubleshooting