MASSRENDER DOCUMENTATION

把视频项目接入生产系统

MassRender 为不同视频代码项目提供统一的项目管理、鉴权和异步任务 API。可以从内置模板快速生成首个视频，也可以接入已有项目并继续二创；渲染运行时的部署、扩缩容与结果存储由平台处理。

支持的项目

三类项目通过同一套 MassRender API 对外提供服务，平台根据项目类型选择对应的构建与渲染适配器。

计费方式

托管云渲染以最终输出的视频分钟数为用量单位。月消费达到更高档位后，当月全部渲染分钟使用对应单价，不采用累进分段计算。以下价格作为方案参考，实际开放档位以合同为准。

系统架构

服务层统一处理 API Key、项目和版本解析、参数校验、租户配额与任务状态；运行时层根据项目类型执行实际渲染。

快速开始

1. 1

   创建项目与版本

   选择 Remotion、hyperframes 或 html-video，并上传对应的构建产物。每次发布生成不可变的项目版本。

2. 2

   创建 API Key

   API Key 只应保存在服务端环境变量或密钥管理服务中，不要暴露在浏览器代码里。

3. 3

   提交渲染任务

   指定项目、版本、渲染入口和业务参数。接口异步返回 renderTaskId。

4. 4

   查询或接收结果

   通过 renderTaskId 查询进度，完成后获得最终视频 URL；生产场景可以配置 Webhook。

渲染 API

外部服务使用控制台生成的账号级 API Key，通过X-API-KEY请求头访问。任务归属于该账号所在租户，创建任务会从该租户结算费用；请勿在浏览器前端暴露密钥。

POST/api/v1/render-tasks

curl -X POST /api/v1/render-tasks \
  -H "X-API-KEY: $MASSRENDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectVersionId": "pv_01J...",
    "compositionId": "DataReport",
    "inputProps": { "headline": "2026 年度增长", "metricValue": 1280 }
  }'

GET/api/v1/render-tasks/:renderTaskId

curl /api/v1/render-tasks/rt_01J... \
  -H "X-API-KEY: $MASSRENDER_API_KEY"

{
  "renderTaskId": "rt_01J...",
  "status": "rendering",
  "progress": { "percent": 72, "completedChunks": 13, "totalChunks": 18 },
  "output": null
}

CLI 快速开始

MassRender CLI 让你从终端管理模板、上传 bundle 和发起渲染，自动处理鉴权和轮询。

npx @massrender/cli

npx @massrender/cli login  # 打开浏览器完成授权

npx @massrender/cli template list

npx @massrender/cli render run \
  --template data-report \
  --props '{"headline":"2026 年度增长","metricValue":1280}'

任务生命周期

任务失败时返回 failed 和结构化错误信息。客户端应使用指数退避轮询，并以 renderTaskId 作为幂等与问题排查标识。

Remotion FC 实现

Remotion 项目使用阿里云函数计算 custom-container 运行时。编排器读取 composition metadata，并根据帧数动态拆分 chunk；多个 Worker 分片渲染，Combiner 使用 FFmpeg 合并最终 MP4。

企业级 FC 自部署

对于要求数据不离开企业云账号、需要连接内网素材或希望独立管理资源成本的客户，MassRender 可以协助将 Remotion FC 渲染链路部署到客户自己的阿里云环境。

生产接入建议

• 业务后端负责保存 API Key，前端不直接调用渲染接口。
• 为每个项目使用不可变版本，发布新版本时保留回滚能力。
• 对提交接口设置租户配额、并发限制和输入参数校验。
• Webhook 接收方校验签名，并按 renderTaskId 实现幂等处理。
• 长耗时任务使用异步状态，不要保持同步 HTTP 连接等待视频完成。