Origins

Origins are storage locations where your source videos live and where transcoded outputs are written. Transcodely supports three storage providers: Google Cloud Storage (GCS), Amazon S3, and HTTP/HTTPS endpoints.

Overview

Every transcoding job needs at least one origin — an input origin to read the source video, and an output origin to write the transcoded files. Origins store the credentials and configuration needed to access your storage buckets.

Job Request
  ├── Input Origin (read) — where the source video is
  └── Output Origin (write) — where outputs are written

Providers

Provider	Protocol	Permissions	Use Case
GCS	`gs://`	Read + Write	Google Cloud users
S3	`s3://`	Read + Write	AWS or S3-compatible storage
HTTP	`https://`	Read only	CDNs, public URLs, third-party APIs

Creating a GCS Origin

curl -X POST https://api.transcodely.com/transcodely.v1.OriginService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: org_a1b2c3d4e5" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "Production GCS Bucket",
    "description": "Main storage for video assets",
    "permissions": ["read", "write"],
    "base_path": "videos/",
    "path_template": "{date}/{job_id}/{codec}_{resolution}",
    "gcs": {
      "bucket": "acme-video-assets",
      "credentials": {
        "service_account_json": "{...service account key JSON...}"
      }
    }
  }'

Credentials are validated at creation time. If validation fails, the origin is created with a failed status and the validation error is returned.

Creating an S3 Origin

curl -X POST https://api.transcodely.com/transcodely.v1.OriginService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: org_a1b2c3d4e5" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "AWS S3 Output",
    "permissions": ["read", "write"],
    "s3": {
      "bucket": "acme-transcoded-outputs",
      "region": "us-east-1",
      "credentials": {
        "access_key_id": "AKIAIOSFODNN7EXAMPLE",
        "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
      }
    }
  }'

Creating an HTTP Origin

HTTP origins are read-only and are typically used for fetching source videos from CDNs or public URLs:

curl -X POST https://api.transcodely.com/transcodely.v1.OriginService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: org_a1b2c3d4e5" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "CDN Source",
    "permissions": ["read"],
    "http": {
      "base_url": "https://cdn.example.com/videos/",
      "credentials": {
        "headers": {
          "Authorization": "Bearer cdn_token_abc123"
        }
      }
    }
  }'

Origin Status

Status	Description
`active`	Credentials validated, origin is ready to use
`failed`	Credential validation failed — check `validation_error` for details
`archived`	Soft-deleted, cannot be used for new jobs

Permissions

When creating an origin, you declare what permissions the credentials should have:

Permission	Description	Required For
`read`	List and download objects	Input origins
`write`	Upload objects	Output origins

An origin used for both input and output should have both read and write permissions. HTTP origins only support read.

Path Templates

Origins can define a path_template that controls where output files are written. Templates support variables that are resolved at job creation time:

Variable	Example Value	Description
`{job_id}`	`job_a1b2c3d4e5f6`	Job identifier
`{output_id}`	`out_xyz789`	Output identifier
`{date}`	`2026-01-15`	Date in YYYY-MM-DD format
`{timestamp}`	`2026-01-15T10-30-00Z`	ISO timestamp (file-safe)
`{codec}`	`h264`	Video codec
`{resolution}`	`1080p`	Resolution preset
`{format}`	`mp4`	Output container format
`{quality}`	`standard`	Quality tier

Example: a path template of {date}/{job_id}/{codec}_{resolution} produces paths like 2026-01-15/job_a1b2c3/h264_1080p.mp4.

The base_path is prepended to all resolved paths. If base_path is videos/ and the resolved template is 2026-01-15/job_a1b2c3/output.mp4, the final path becomes videos/2026-01-15/job_a1b2c3/output.mp4.

Validation

Credentials are automatically validated when an origin is created or when credentials are updated. You can also re-validate at any time to check for permission drift:

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

{
  "origin": { "id": "ori_x9y8z7w6v5", "status": "active", "..." : "..." },
  "validation": {
    "success": true,
    "can_read": true,
    "can_write": true,
    "validated_at": "2026-01-15T10:30:00Z"
  }
}

Credential Security

Credentials are encrypted at rest and never returned in API responses. After creation, you can only see that credentials exist — not their values. To update credentials, provide new ones through the Update endpoint.

Archiving Origins

Archived origins cannot be used for new jobs, but existing job data stored in the origin remains accessible:

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

#Origins

#Overview

#Providers

#Creating a GCS Origin

#Creating an S3 Origin

#Creating an HTTP Origin

#Origin Status

#Permissions

#Path Templates

#Validation

#Credential Security

#Archiving Origins