Search Documentation
Search across all documentation pages
Storage Setup

Overview

Before creating transcoding jobs, you need to configure origins — storage locations where Transcodely reads input files and writes transcoded outputs. Transcodely supports Google Cloud Storage (GCS), Amazon S3, and HTTP URLs as origin providers.

Origins are scoped to your app and can have read permission (for inputs), write permission (for outputs), or both. Credentials are validated at creation time.

Google Cloud Storage

1. Create a Service Account

In the Google Cloud Console, create a dedicated service account for Transcodely. Avoid reusing existing accounts — a purpose-built account makes it easy to audit and revoke access.

gcloud iam service-accounts create transcodely-storage 
  --display-name="Transcodely Storage Access" 
  --project=your-project-id

2. Grant Bucket Permissions

Assign the minimum required roles. For an origin that both reads inputs and writes outputs, you need storage.objectViewer and storage.objectCreator:

{
  "bindings": [
    {
      "role": "roles/storage.objectViewer",
      "members": [
        "serviceAccount:transcodely-storage@your-project-id.iam.gserviceaccount.com"
      ]
    },
    {
      "role": "roles/storage.objectCreator",
      "members": [
        "serviceAccount:transcodely-storage@your-project-id.iam.gserviceaccount.com"
      ]
    }
  ]
}

Apply the policy to your bucket:

gcloud storage buckets add-iam-policy-binding gs://your-video-bucket 
  --member="serviceAccount:transcodely-storage@your-project-id.iam.gserviceaccount.com" 
  --role="roles/storage.objectViewer"

gcloud storage buckets add-iam-policy-binding gs://your-video-bucket 
  --member="serviceAccount:transcodely-storage@your-project-id.iam.gserviceaccount.com" 
  --role="roles/storage.objectCreator"

For a read-only input origin, only storage.objectViewer is needed. For a write-only output origin, only storage.objectCreator is needed.

3. Generate a Service Account Key

gcloud iam service-accounts keys create sa-key.json 
  --iam-account=transcodely-storage@your-project-id.iam.gserviceaccount.com

4. Create the Origin

curl -X POST https://api.transcodely.com/transcodely.v1.OriginService/Create 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -d '{
    "name": "Production GCS Bucket",
    "description": "Primary storage for video inputs and outputs",
    "permissions": ["read", "write"],
    "base_path": "videos/",
    "path_template": "{date}/{job_id}/{codec}_{resolution}",
    "gcs": {
      "bucket": "your-video-bucket",
      "credentials": {
        "service_account_json": "<contents of sa-key.json>"
      }
    }
  }'

The response includes a validation object confirming Transcodely was able to read from and write to the bucket:

{
  "origin": {
    "id": "ori_x9y8z7w6v5",
    "name": "Production GCS Bucket",
    "provider": "gcs",
    "status": "active",
    "permissions": ["read", "write"]
  },
  "validation": {
    "success": true,
    "can_read": true,
    "can_write": true
  }
}

Amazon S3

1. Create an IAM User

Create a dedicated IAM user for Transcodely in the AWS Console or CLI:

aws iam create-user --user-name transcodely-storage

2. Attach a Bucket Policy

Create an IAM policy with the minimum permissions. For a read/write origin:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "TranscodelyReadAccess",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::your-video-bucket",
        "arn:aws:s3:::your-video-bucket/*"
      ]
    },
    {
      "Sid": "TranscodelyWriteAccess",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl"
      ],
      "Resource": [
        "arn:aws:s3:::your-video-bucket/*"
      ]
    }
  ]
}

Attach the policy to the IAM user:

aws iam put-user-policy 
  --user-name transcodely-storage 
  --policy-name TranscodelyStorageAccess 
  --policy-document file://transcodely-policy.json

3. Generate Access Keys

aws iam create-access-key --user-name transcodely-storage

Save the AccessKeyId and SecretAccessKey from the response. The secret is shown only once.

4. Create the Origin

curl -X POST https://api.transcodely.com/transcodely.v1.OriginService/Create 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -d '{
    "name": "Production S3 Bucket",
    "description": "US East video storage",
    "permissions": ["read", "write"],
    "base_path": "videos/",
    "path_template": "{date}/{job_id}/{codec}_{resolution}",
    "s3": {
      "bucket": "your-video-bucket",
      "region": "us-east-1",
      "credentials": {
        "access_key_id": "AKIAIOSFODNN7EXAMPLE",
        "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
      }
    }
  }'

Separate Input and Output Origins

A common pattern is to use separate origins for inputs and outputs, with different buckets and permissions:

# Input origin (read-only)
curl -X POST https://api.transcodely.com/transcodely.v1.OriginService/Create 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -d '{
    "name": "Upload Bucket (Input)",
    "permissions": ["read"],
    "gcs": {
      "bucket": "my-uploads-bucket",
      "credentials": {
        "service_account_json": "<sa-key contents>"
      }
    }
  }'

# Output origin (write-only)
curl -X POST https://api.transcodely.com/transcodely.v1.OriginService/Create 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -d '{
    "name": "CDN Bucket (Output)",
    "permissions": ["write"],
    "path_template": "{date}/{job_id}/{resolution}",
    "gcs": {
      "bucket": "my-cdn-bucket",
      "credentials": {
        "service_account_json": "<sa-key contents>"
      }
    }
  }'

Then reference both origins when creating a job:

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/Create 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -d '{
    "input_origin_id": "ori_input12345",
    "input_path": "uploads/my-video.mp4",
    "output_origin_id": "ori_output6789",
    "outputs": [
      {
        "type": "mp4",
        "video": [{ "codec": "h264", "resolution": "1080p", "quality": "standard" }]
      }
    ]
  }'

Re-validating Credentials

If you rotate credentials or change bucket permissions, re-validate an existing origin:

curl -X POST https://api.transcodely.com/transcodely.v1.OriginService/Validate 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -d '{ "id": "ori_x9y8z7w6v5" }'

If validation fails, the origin status changes to failed and it cannot be used for new jobs until the issue is resolved and validation succeeds again.

Best Practices

PracticeRationale
Use dedicated service accounts/IAM usersEasy to audit, rotate, and revoke without affecting other services
Apply least-privilege permissionsInput origins only need read; output origins only need write
Set base_path for organizationKeeps Transcodely files in a predictable directory structure
Use path_template on output originsAvoids path collisions and creates a clean file hierarchy
Re-validate after credential rotationCatches permission issues before they cause job failures