Convertrilo

Convertrilo TypeScript SDK

Convertrilo API 用の型安全なクライアントです。

VMAF とエンコードパス

optimize: "vmaf" を指定すると、Convertrilo は VMAF サンプリングと最適化された最終エンコードを実行します。後方互換性のため、指定された passes: 2 の値は引き続き受け付けますが、API で使用され、課金対象となる実効パス数は 1 です。

料金のレスポンスには requestedPasses と effectivePasses が含まれます。新しいインテグレーションでは、VMAF と併用する場合は passes: 1 を使用してください。

インストール

pnpm add @convertrilo/sdk

このパッケージは現在、グローバルな fetch を備えた最新の Node.js ランタイムを対象としています。ランタイムに fetch がない場合は、クライアントに fetchImpl を渡してください。

CLI と MCP による自動化

このパッケージには、実行可能な自動化ツールが 2 つ含まれています。

export CONVERTRILO_API_KEY="cvr_..."

convertrilo encode https://example.com/input.mp4 \
  --codec h264 \
  --resolution 1080p \
  --audio-policy transcode-aac \
  --frame-rate-policy cap \
  --scale-policy no-upscale \
  --quality better \
  --wait \
  --json

convertrilo-mcp

スクリプト、CI、cron、ローカルでの操作には convertrilo を使用してください。エージェントやワークフローとのインテグレーションには、stdio MCP サーバーとして convertrilo-mcp を使用してください。

convertrilo login または convertrilo init を実行して API キーをローカルに保存するか、引数なしで convertrilo を実行して、対話形式のエンコードウィザードを開始してください。待機中のコマンドはデフォルトでターミナルに進行状況を表示し、スクリプトで使用する --json の出力には進行状況を含めません。

シェル補完のスニペットは、次のコマンドで利用できます。

convertrilo completion zsh

コマンド、MCP クライアントの設定、S3 出力の例、VMAF、2 パス、ステータス、キャンセル、残高のワークフローについては、docs/CLI-AND-MCP.md を参照してください。

ターミナルで最も簡単に使い始めるには、docs/CLI-QUICKSTART.md から始めてください。

エージェント／クライアントのセットアップには、docs/MCP-QUICKSTART.md を使用してください。

MCP レジストリのメタデータは server.json にあります。

クライアントの作成

import { ConvertriloClient } from "@convertrilo/sdk";

const client = new ConvertriloClient({
  baseUrl: "https://api.convertrilo.com",
  apiKey: process.env.CONVERTRILO_API_KEY,
});

サーバー間のインテグレーションには API キーを使用してください。ブラウザーアプリからは独自のバックエンドを呼び出し、そのバックエンドから Convertrilo を呼び出してください。

例

examples/ ディレクトリには、主なインテグレーション方法を示すスクリプトが用意されています。

• node-url-to-cdn.ts - 公開 URL をエンコードし、署名付き CDN ダウンロード URL を取得します
• node-url-to-s3.ts - 公開 URL をエンコードし、結果を S3／S3 互換ストレージにアップロードします
• google-drive-byo-token.ts - 顧客所有のサービスアカウントを使用して、出力を Google Drive にアップロードします
• folder-ingest-s3.ts - S3 プレフィックス内の動画ごとにエンコードジョブを 1 件ずつキューに登録します
• idempotency.ts - createJob と createJobsBulk を安全に再試行します
• webhook-receiver-hmac.ts - Node のレシーバーで、管理対象ウェブフックの HMAC 署名を検証します

ローカル SDK のスモークテストでは .env を使用しますが、公開 SDK を利用する場合は、各自のサーバー環境を通じて認証情報を渡してください。Convertrilo API キーや顧客のストレージトークンをフロントエンドのコードに含めないでください。

URL、S3、フォルダー取り込み、Google Drive サービスアカウント、ポーリング、ウェブフックを網羅したサーバー間インテグレーションの完全な手順については、docs/API-INTEGRATION-GUIDE.md を参照してください。

冪等なジョブの作成

バックエンドから作成リクエストを再試行する場合は、冪等性キーを使用してください。同じキーを同じ本文で再利用すると、重複したジョブを作成せずに元のレスポンスが返されます。

const job = await client.createJob({
  externalId: "upload-123",
  metadata: { customerId: "cus_123" },
  codec: "h264",
  resolution: "1080p",
  fps: 30,
}, {
  idempotencyKey: "job-upload-123",
});

const batch = await client.createJobsBulk({
  jobs: [
    {
      externalId: "batch-42:clip-1",
      codec: "h264",
      resolution: "1080p",
      fps: 30,
      sourceS3: { bucket: "source", key: "clip-1.mp4" },
    },
  ],
  settings: { confirm: true },
}, {
  idempotencyKey: "bulk-batch-42",
});

ジョブファイルのクリーンアップ

ジョブが終了状態になった後に、管理対象のアップロードオブジェクトと出力オブジェクトを削除します。

await client.cancelJob(jobId); // required first for created, queued, or running jobs

const result = await client.deleteJobFiles(jobId);
console.log(result.objectsDeleted, result.jobRetained);

監査用に、ジョブレコードと課金履歴は引き続き利用できます。実行中のジョブは、キャンセルされるまで安定した job_active エラーを返します。

保存済みエンコードプリセット

ソース URL、ストレージ認証情報、出力シークレットを保存せずに、再利用可能なエンコード設定を保存します。

const preset = await client.createEncodePreset({
  name: "Default 1080p web MP4",
  settings: {
    codec: "h264",
    resolution: "1080p",
    fps: 30,
    preset: "standard",
    bitrateTier: "medium",
    passes: 1,
    policy: "fastest",
    container: "mp4",
    quality: "better",
    optimize: "none",
    vmafTarget: 93,
    audioPolicy: "transcode-aac",
    frameRatePolicy: "cap",
    scalePolicy: "no-upscale",
  },
});

const { presets } = await client.getEncodePresets();

保存済み出力先

出力先自体にストレージの生のシークレットを保存せずに、再利用可能な配信先を保存します。S3 出力先は、暗号化された保存済み S3 認証情報を参照します。

const destination = await client.createOutputDestination({
  name: "Customer uploads bucket",
  config: {
    type: "s3",
    credentialId: "0f5a7f2b-4ff2-45d4-b76f-1f7b6e98d4d1",
    keyPrefix: "processed/",
  },
});

const { destinations } = await client.getOutputDestinations();

URL ソースから CDN への出力

const job = await client.onDemandEncode({
  sourceUrl: "https://example.com/input.mp4",
  externalId: "customer-video-123",
  metadata: {
    customerId: "cus_123",
    workflow: "daily-compression",
  },
  codec: "h264",
  resolution: "1080p",
  quality: "better",
  audioPolicy: "transcode-aac",
  frameRatePolicy: "cap",
  scalePolicy: "no-upscale",
}, {
  idempotencyKey: "encode-customer-video-123",
});

let finalStatus;
while (true) {
  finalStatus = await client.onDemandStatus(job.jobId);

  if (finalStatus.status === "success") break;
  if (finalStatus.status === "failed") {
    throw new Error(finalStatus.failureMessage || "Encoding failed");
  }

  await new Promise((resolve) => setTimeout(resolve, 5000));
}

console.log(finalStatus.downloadUrl);
console.log(finalStatus.requestedExecution);
console.log(finalStatus.effectiveExecution);
console.log(finalStatus.sourceProbe?.color);
console.log(finalStatus.outputProbe);

ターミナルでは、次のコマンドで同じレポートを確認できます。

convertrilo status JOB_ID --json
convertrilo wait JOB_ID --json

URL ソースから S3 への出力

const job = await client.onDemandEncode({
  sourceUrl: "https://example.com/input.mp4",
  codec: "h264",
  resolution: "1080p",
  outputS3: {
    bucket: "customer-output-bucket",
    key: "encoded/input-1080p.mp4",
    region: "us-east-1",
    accessKeyId: process.env.CUSTOMER_S3_ACCESS_KEY_ID,
    secretAccessKey: process.env.CUSTOMER_S3_SECRET_ACCESS_KEY,
  },
});

console.log(job.jobId);

S3 互換サービスでは、endpoint と、通常は forcePathStyle: true を渡してください。

URL ソースから Google Drive への出力

ヘッドレス API 統合では、お客様所有の Google サービスアカウントを一度保存します。 出力先には Google Shared Drive を使用し、返されたサービスアカウントのメールアドレスを ファイル作成権限を持つメンバーとして追加します。

const credential = await client.createGoogleDriveCredential({
  name: "Production Drive",
  serviceAccount: JSON.parse(process.env.GOOGLE_SERVICE_ACCOUNT_JSON!),
});

const job = await client.onDemandEncode({
  sourceUrl: "https://example.com/input.mp4",
  codec: "h264",
  resolution: "1080p",
  outputGoogleDrive: {
    folderId: "GOOGLE_DRIVE_FOLDER_ID",
    fileName: "input-1080p.mp4",
    credentialId: credential.id,
  },
});

console.log(job.jobId);

ダッシュボードの Google Picker 認証は、SDK による自動化とは別です。

フォルダーの取り込み

S3 プレフィックス内の動画ごとにジョブを 1 つキューに追加します。

const batch = await client.onDemandIngestFolder({
  externalIdPrefix: "batch-2026-06-09",
  metadata: {
    customerId: "cus_123",
    workflow: "folder-compression",
  },
  sourceS3: {
    bucket: "customer-source-bucket",
    prefix: "incoming/",
    region: "us-east-1",
    accessKeyId: process.env.CUSTOMER_S3_ACCESS_KEY_ID,
    secretAccessKey: process.env.CUSTOMER_S3_SECRET_ACCESS_KEY,
  },
  outputDestination: "s3",
  outputS3: {
    bucket: "customer-output-bucket",
    prefix: "encoded/",
    region: "us-east-1",
    accessKeyId: process.env.CUSTOMER_S3_ACCESS_KEY_ID,
    secretAccessKey: process.env.CUSTOMER_S3_SECRET_ACCESS_KEY,
  },
  codec: "h264",
  maxFiles: 25,
  resolution: "1080p",
}, {
  idempotencyKey: "folder-batch-2026-06-09",
});

for (const job of batch.jobs || []) {
  console.log(job.jobId, job.externalId, job.fileName);
}

maxFiles を使用すると、フォルダー内で検出した動画のうち、キューに追加する数を制限できます。

Google Drive フォルダー内の動画ごとにジョブを 1 つキューに追加します。

const batch = await client.onDemandIngestFolder({
  sourceGoogleDrive: {
    folderId: "SOURCE_FOLDER_ID",
    credentialId: credential.id,
  },
  outputDestination: "google-drive",
  outputGoogleDrive: {
    folderId: "OUTPUT_FOLDER_ID",
    credentialId: credential.id,
  },
  codec: "h264",
  maxFiles: 25,
  resolution: "1080p",
});

for (const job of batch.jobs || []) {
  console.log(job.jobId, job.fileName);
}

Convertrilo は、各ワーカーの起動時に、暗号化されたサービスアカウントの認証情報から有効期間の短い Google トークンを発行します。

返された各 jobId の状態を client.onDemandStatus(jobId) で確認します。

Webhook 配信履歴

管理対象の Webhook は HMAC で署名されます。Webhook をテストし、最近の配信試行を確認できます。

await client.testWebhook(webhookId);

const history = await client.getWebhookDeliveries(webhookId);
for (const delivery of history.deliveries || []) {
  console.log(delivery.status, delivery.statusCode, delivery.event);
}

型の再生成

SDK の型は openapi.yaml から生成されます。

pnpm run generate
pnpm run build

生成スクリプトでは --default-non-nullable false を使用するため、OpenAPI のデフォルト値は TypeScript のリクエストボディで任意のままになります。