Skip to main content
POST
https://api.pictory.ai
/
pictoryapis
/
v1
/
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’ll 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’ll need an AWS account with access to create IAM roles. If you don’t 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:
  1. You create a special role in AWS (the “guest pass”)
  2. You tell AWS that Pictory is allowed to use this role
  3. You specify which folders/buckets Pictory can access
  4. Pictory uses this role to fetch your videos and images when creating content
1

Step 1: Log in to AWS Console

  1. Go to AWS Management Console
  2. Sign in with your AWS account credentials
  3. 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.
2

Step 2: Start Creating a New Role

  1. On the left sidebar, click Roles
  2. 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.
3

Step 3: Set Up Trust with Pictory

This step tells AWS that Pictory’s account is allowed to use this role.
  1. Under Trusted entity type, select Another AWS account
  2. In the Account ID field, enter: 701488979254 (this is Pictory’s AWS account)
  3. Click Next
  4. On the permissions page, just click Next (we’ll add permissions in the next step)
  5. Under Role name, enter exactly: PictoryCloudIntegrationRole (this exact name is required)
  6. Click Create role
4

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).
  1. In the search box, find the role you just created: PictoryCloudIntegrationRole
  2. Click on it to open the role details
  3. Click the Permissions tab
  4. Click Add permissions → Create inline policy
  5. Click the JSON tab (ignore the visual editor)
  6. 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:::*"
            ]
        }
    ]
}
  1. 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”)
  2. Click Next
  3. Name the policy: s3_access_policy
  4. 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
5

Step 5: Configure Trust Relationship (Advanced)

This step sets up the detailed trust relationship between your AWS account and Pictory.
  1. In the role details, click the Trust relationships tab
  2. Click Edit trust policy
  3. 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": {}
        }
    ]
}
  1. 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
6

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’ll 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’ll 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’re using a tool like Postman or writing code, these are the fields you’ll 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 don’t need it - it’s 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 what you’re using!
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’ve 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’s 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:
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

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
Your API key may be invalid or expired. Get your API key from the API Access page in your Pictory dashboard.
You already have a connection with this name or AWS account/region. Try a different connection name.
Check these in order:
  1. Role name must be exactly: PictoryCloudIntegrationRole
  2. Bucket name in your S3 URIs must match your IAM policy
  3. Region must match where your S3 bucket is located
  4. 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