Search Documentation
Search across all documentation pages
SDKs & Libraries

SDKs

Transcodely provides official SDKs for the most popular server-side languages. Each SDK is a thin, type-safe wrapper around the Connect-RPC API — no code generation required on your end.

Available SDKs

LanguagePackageStatus
JavaScript / TypeScript@transcodely/sdkStable
PythontranscodelyStable
Gogithub.com/transcodely/go-sdkStable

All SDKs are auto-generated from the same Protocol Buffer definitions that power the API, so they stay in sync with every release.

JavaScript / TypeScript

Install with your preferred package manager:

npm install @transcodely/sdk

Initialize the client and create a job:

import { TranscodelyClient } from "@transcodely/sdk";

const client = new TranscodelyClient({
  apiKey: process.env.TRANSCODELY_API_KEY,
});

const { job } = await client.jobs.create({
  input_url: "https://storage.example.com/video.mp4",
  output_origin_id: "ori_x9y8z7w6v5",
  outputs: [
    {
      type: "mp4",
      video: [{ codec: "h264", resolution: "1080p", quality: "standard" }],
    },
  ],
  priority: "standard",
});

console.log(`Job created: ${job.id}`);

The TypeScript SDK provides full type definitions for all request and response objects, including autocompletion for enum values like codec, resolution, and quality.

Python

Install from PyPI:

pip install transcodely

Create a job:

from transcodely import TranscodelyClient

client = TranscodelyClient(api_key="{{API_KEY}}")

job = client.jobs.create(
    input_url="https://storage.example.com/video.mp4",
    output_origin_id="ori_x9y8z7w6v5",
    outputs=[
        {
            "type": "mp4",
            "video": [{"codec": "h264", "resolution": "1080p", "quality": "standard"}],
        }
    ],
    priority="standard",
)

print(f"Job created: {job.id}")

The Python SDK supports both synchronous and async usage. For async, use AsyncTranscodelyClient:

from transcodely import AsyncTranscodelyClient

client = AsyncTranscodelyClient(api_key="{{API_KEY}}")
job = await client.jobs.create(...)

Go

Install the Go module:

go get github.com/transcodely/go-sdk

Create a job:

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    transcodely "github.com/transcodely/go-sdk"
)

func main() {
    client := transcodely.NewClient(
        transcodely.WithAPIKey(os.Getenv("TRANSCODELY_API_KEY")),
    )

    job, err := client.Jobs.Create(context.Background(), &transcodely.CreateJobRequest{
        InputURL:       "https://storage.example.com/video.mp4",
        OutputOriginID: "ori_x9y8z7w6v5",
        Outputs: []transcodely.OutputSpec{
            {
                Type: transcodely.OutputFormatMP4,
                Video: []transcodely.VideoVariant{
                    {
                        Codec:      transcodely.VideoCodecH264,
                        Resolution: transcodely.Resolution1080P,
                        Quality:    transcodely.QualityStandard,
                    },
                },
            },
        },
        Priority: transcodely.PriorityStandard,
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Job created: %s\n", job.ID)
}

Common Patterns

Error Handling

All SDKs surface Connect-RPC error codes consistently:

import { TranscodelyClient, TranscodelyError, ErrorCode } from "@transcodely/sdk";

try {
  await client.jobs.get({ id: "job_invalid" });
} catch (err) {
  if (err instanceof TranscodelyError) {
    switch (err.code) {
      case ErrorCode.NotFound:
        console.error("Job not found");
        break;
      case ErrorCode.Unauthenticated:
        console.error("Invalid API key");
        break;
      case ErrorCode.InvalidArgument:
        console.error("Validation error:", err.details);
        break;
    }
  }
}

Pagination

List endpoints return paginated results. Use the next_cursor from the response to fetch subsequent pages:

let cursor = "";
const allJobs = [];

do {
  const response = await client.jobs.list({
    pagination: { limit: 50, cursor },
  });
  allJobs.push(...response.jobs);
  cursor = response.pagination.next_cursor;
} while (cursor);

Watch Stream

The SDKs provide a convenient iterator for the Watch RPC:

for await (const event of client.jobs.watch({ id: "job_a1b2c3d4e5f6" })) {
  console.log(`Status: ${event.job.status}, Progress: ${event.job.progress}%`);

  if (event.event === "completed") {
    console.log("Job finished!");
    break;
  }
}

Direct HTTP Access

If you prefer not to use an SDK, you can call the API directly over HTTP. All endpoints accept JSON via POST:

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "Content-Type: application/json" 
  -d '{"input_url": "...", "outputs": [...]}'

See the API Reference for complete endpoint documentation.