Developer guide

Convertrilo SDK quickstart for automated video encoding

Install the Convertrilo TypeScript SDK, create an API key, submit a retry-safe encoding job, and wait for a completed output.

Use the SDK when your product already owns uploads, users, storage, and permissions, but needs a background video encoding worker that can be called from your backend.

Create API keyAPI docsIntegration overview
Create and wait for a jobguide
import { Convertrilo } from "@convertrilo/sdk";

const client = new Convertrilo({
  apiKey: process.env.CONVERTRILO_API_KEY
});

const job = await client.onDemandEncode({
  sourceUrl: "https://example.com/input.mov",
  externalId: "asset_123",
  metadata: { tenantId: "team_a" },
  codec: "h264",
  resolution: "1080p",
  quality: "better"
}, {
  idempotencyKey: "asset_123:h264:1080p"
});

const completed = await client.jobs.wait(job.id);

Create a scoped API key from Developer Settings.

Install @convertrilo/sdk in a backend service, worker, or script.

Choose a source URL or storage object the encoder can read.

Decide where completed files should be written.

Recipe

Build the workflow with stable API primitives

These guides focus on primitives that can be reused by dashboards, queue workers, scripts, CLIs, MCP tools, and agent runtimes.

  1. Step 1

    Create the SDK client with an API key stored in your secret manager.

  2. Step 2

    Submit an on-demand encode request with codec, resolution, quality, externalId, and metadata.

  3. Step 3

    Send an idempotency key so retries return the original job instead of creating duplicate paid work.

  4. Step 4

    Poll, wait, or receive a webhook when the job reaches a terminal state.

Backend-owned automation

Keep Convertrilo API keys on your server and let your app decide which users, plans, and uploads are allowed to create encoding jobs.

Stable reconciliation

Use externalId and metadata to connect Convertrilo jobs back to assets, tenants, lessons, campaigns, or uploads in your own database.

One API contract

The SDK wraps the same API primitives exposed to dashboards, scripts, agents, queues, CLI commands, and MCP tools.

Developer questions

Can I run the SDK from the browser?

No. Keep Convertrilo API keys in backend code, server jobs, CI secrets, or agent runtime secrets.

Do I need to use webhooks?

No. Polling and wait helpers are fine for scripts. Webhooks are better for production products that need event-driven updates.

Can SDK jobs use VMAF, two-pass, priority, and S3 output?

Yes. SDK calls can send the same job fields that the API and dashboard use for advanced encoding options.

Related developer paths

Queue automationConnect Convertrilo to your own queues, cron jobs, imports, and backfills without duplicating jobs when retries happen.Webhook receiverReceive signed Convertrilo job events, verify the HMAC signature, and update your own product when outputs are ready.S3 output workflowsRoute completed video encodes to S3-compatible buckets so your product keeps ownership of storage, CDN, lifecycle rules, and access control.MCP setupInstall @convertrilo/sdk, save an API key with the CLI, configure convertrilo-mcp in an MCP client, and verify the available video encoding tools.Agent workflowsDesign agent-friendly video encoding workflows with the Convertrilo MCP server, scoped API keys, deterministic job payloads, idempotency, polling, and signed webhooks.Video encoding APICreate video encoding jobs from your backend with API keys, idempotency, metadata, priority queues, webhooks, and storage destinations you control.Video encoding CLIAutomate video compression from terminals, deployment jobs, content pipelines, and scheduled scripts with a Convertrilo CLI workflow.VMAF video encodingUse VMAF-guided sample encoding to choose a better quality target before the final video encode, without manually testing bitrate settings.Two-pass video encodingUse classic two-pass H.264 and H.265 encoding when predictable bitrate allocation matters more than raw hardware speed.

Start with a real estimate

Choose your codec, resolution, FPS, bitrate, quality, and optimization settings. Convertrilo shows the NEU estimate before credits are reserved, and failed jobs release reserved credits back to your balance.

Start FreeCalculate Pricing