Remotion LabRemotion Lab
›Cloud Run›Cloud Run Node.js API

Cloud Run Node.js API

Remotion Cloud Run 的完整 Node.js API 參考，包含 renderMediaOnCloudrun()、renderStillOnCloudrun()、deployService()、selectComposition() 等函式說明。

Cloud Run Node.js API

@remotion/cloudrun 套件提供完整的 Node.js API，讓你以程式方式控制所有 Cloud Run 操作。

安裝

npm install @remotion/cloudrun

渲染相關 API

renderMediaOnCloudrun()

在 Cloud Run 上渲染影片或音訊。

import { renderMediaOnCloudrun } from "@remotion/cloudrun";
 
const result = await renderMediaOnCloudrun({
  region: "asia-east1",
  serviceName: "remotion-render-4-0-0",
  serveUrl: "https://storage.googleapis.com/my-bucket/sites/my-site/index.html",
  composition: "MyComposition",
  codec: "h264",
  inputProps: { title: "我的影片" },
  privacy: "public",
  outName: "renders/output.mp4",
  timeoutInMilliseconds: 30000,
});

參數說明：

參數必填型別說明
region是stringGCP 區域
serviceName是stringCloud Run 服務名稱
serveUrl是string站台的 Cloud Storage URL
composition是stringComposition ID
codec是string輸出編解碼器
inputProps否object傳入 Composition 的 props
privacy否"public" | "private"輸出檔案存取權限（預設 "public"）
outName否string輸出檔案名稱
timeoutInMilliseconds否number單幀逾時時間
scale否number解析度縮放比例
frameRange否[number, number]渲染幀範圍
envVariables否object渲染環境變數
chromiumOptions否objectChromium 啟動選項
forceHeight否number強制覆寫高度
forceWidth否number強制覆寫寬度

回傳值（成功）：

{
  type: "success";
  publicUrl: string;         // 公開存取 URL
  cloudStorageUri: string;   // gs:// 路徑
  size: number;              // 檔案大小（位元組）
  bucketName: string;        // Bucket 名稱
  renderId: string;          // 渲染 ID
  privacy: "public" | "private";
}

renderStillOnCloudrun()

在 Cloud Run 上渲染單一靜態圖片。

import { renderStillOnCloudrun } from "@remotion/cloudrun";
 
const result = await renderStillOnCloudrun({
  region: "asia-east1",
  serviceName: "remotion-render-4-0-0",
  serveUrl: "https://storage.googleapis.com/my-bucket/sites/my-site/index.html",
  composition: "Thumbnail",
  frame: 0,
  imageFormat: "png",
  inputProps: { title: "縮圖" },
  privacy: "public",
});
 
if (result.type === "success") {
  console.log(result.publicUrl);
}

主要參數說明：

參數必填說明
frame是要渲染的幀數（從 0 開始）
imageFormat是"png"、"jpeg" 或 "webp"
jpegQuality否JPEG 品質（1–100，預設 80）
scale否解析度縮放比例

服務管理 API

deployService()

部署新的 Cloud Run 渲染服務。

import { deployService } from "@remotion/cloudrun";
 
const result = await deployService({
  projectID: "my-remotion-project",
  region: "asia-east1",
  cpuLimit: "4",
  memoryLimit: "8Gi",
  timeoutSeconds: 3600,
  minInstances: 0,
  maxInstances: 100,
});
 
console.log("服務全名：", result.fullName);
console.log("服務 URI：", result.uri);

getServices()

列出所有已部署的 Cloud Run 服務。

import { getServices } from "@remotion/cloudrun";
 
const services = await getServices({
  region: "asia-east1",
  compatibleOnly: true, // 只列出與目前版本相容的服務
});
 
services.forEach((service) => {
  console.log(service.serviceName, service.uri);
});

deleteService()

刪除指定的 Cloud Run 服務。

import { deleteService } from "@remotion/cloudrun";
 
await deleteService({
  region: "asia-east1",
  serviceName: "remotion-render-4-0-0",
});

站台管理 API

deploySite()

將 Remotion 專案打包並上傳至 Cloud Storage。

import { deploySite } from "@remotion/cloudrun";
 
const { serveUrl } = await deploySite({
  entryPoint: "./src/index.ts",
  bucketName: "my-remotion-bucket",
  siteName: "my-site",
  options: {
    webpackOverride: (config) => config,
  },
  onBundleProgress: (progress) => {
    console.log(`打包進度：${progress}%`);
  },
  onUploadProgress: ({ totalSize, sizeUploaded }) => {
    const percent = Math.round((sizeUploaded / totalSize) * 100);
    console.log(`上傳進度：${percent}%`);
  },
});
 
console.log("站台 URL：", serveUrl);

getSites()

列出 Cloud Storage 中所有已部署的站台。

import { getSites } from "@remotion/cloudrun";
 
const { sites } = await getSites({
  bucketName: "my-remotion-bucket",
});
 
sites.forEach((site) => {
  console.log(site.id, site.serveUrl);
});

deleteSite()

刪除 Cloud Storage 中的站台。

import { deleteSite } from "@remotion/cloudrun";
 
await deleteSite({
  bucketName: "my-remotion-bucket",
  siteName: "my-old-site",
});

輔助工具 API

getOrCreateBucket()

取得現有的 Bucket 或建立新的 Bucket。

import { getOrCreateBucket } from "@remotion/cloudrun";
 
const { bucketName } = await getOrCreateBucket({
  region: "asia-east1",
});
 
console.log("Bucket：", bucketName);

testPermissions()

驗證目前服務帳戶的 IAM 權限是否正確設定。

import { testPermissions } from "@remotion/cloudrun";
 
const results = await testPermissions({
  region: "asia-east1",
});
 
results.forEach(({ ok, permissionName, reason }) => {
  if (!ok) {
    console.error(`缺少權限：${permissionName} - ${reason}`);
  }
});

selectComposition()

在渲染前取得 Composition 的元資料（解析度、幀率、時長等）。

import { selectComposition } from "@remotion/cloudrun";
 
const composition = await selectComposition({
  region: "asia-east1",
  serviceName: "remotion-render-4-0-0",
  serveUrl: "https://storage.googleapis.com/...",
  id: "MyComposition",
  inputProps: { title: "測試" },
});
 
console.log("寬度：", composition.width);
console.log("高度：", composition.height);
console.log("幀率：", composition.fps);
console.log("總幀數：", composition.durationInFrames);

完整工作流程範例

import {
  deployService,
  deploySite,
  renderMediaOnCloudrun,
  getOrCreateBucket,
} from "@remotion/cloudrun";
 
async function setupAndRender() {
  // 1. 確保 Bucket 存在
  const { bucketName } = await getOrCreateBucket({
    region: "asia-east1",
  });
 
  // 2. 上傳站台
  const { serveUrl } = await deploySite({
    entryPoint: "./src/index.ts",
    bucketName,
    siteName: "my-site",
  });
 
  // 3. 部署服務（若尚未部署）
  const service = await deployService({
    projectID: process.env.REMOTION_GCP_PROJECT_ID!,
    region: "asia-east1",
  });
 
  // 4. 渲染影片
  const result = await renderMediaOnCloudrun({
    region: "asia-east1",
    serviceName: service.fullName,
    serveUrl,
    composition: "MyComposition",
    codec: "h264",
    inputProps: { title: "完整流程測試" },
  });
 
  if (result.type === "success") {
    return result.publicUrl;
  }
 
  throw new Error("渲染失敗");
}

小結

  • renderMediaOnCloudrun() 和 renderStillOnCloudrun() 用於觸發渲染
  • deployService() 和 getServices() 管理 Cloud Run 服務
  • deploySite() 上傳 Remotion 專案到 Cloud Storage
  • testPermissions() 用於驗證 IAM 設定
  • selectComposition() 用於在渲染前查詢 Composition 元資料

另請參閱