把视频项目接入生产系统

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

支持的项目

平台按项目类型选择对应的构建与渲染适配器。两种项目都是上传构建产物创建版本， 渲染运行时的部署与扩缩容由平台处理。

计费方式

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

系统架构

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

快速开始

1. 1

   创建项目与版本

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

2. 2

   创建 API Key

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

3. 3

   提交渲染任务

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

4. 4

   查询或接收结果

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

认证方式

本地交互使用设备授权；Agent、CI 和服务端集成使用账号级 API Key，无需登录或打开 MassRender 网页。API Key 继承账号所属租户和账号权限；模板创建、更新与发布仍需对应模板管理权限。

export MASSRENDER_API_URL=/api/v1
export MASSRENDER_API_KEY=***

npx @massrender/cli auth status --json
npx @massrender/cli whoami --json
npx @massrender/cli capabilities --json

公开 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 快速开始

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

npx @massrender/cli

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

npx @massrender/cli template list

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

npx @massrender/cli render wait <renderTaskId> --output=jsonl
npx @massrender/cli render download <renderTaskId> --file result.mp4 --json

CLI 命令参考

下列资源命令都支持--output text|json|jsonl和 --json。

# 余额、价格与最多 90 天逐日用量
massrender billing balance --json
massrender billing pricing --json
massrender billing usage --daily --from 2026-07-01 --to 2026-07-30 --json

# 筛选任务；from/to 必须同时提供且范围不超过一个月
massrender render list --status completed --limit 50 --json
massrender render list --cursor <nextCursor> --json

# 每次创建都会新建一个渲染任务（后扣费，提交不冻结资金）
massrender render create --template data-report --json

机器输出与错误处理

JSON 模式固定返回成功或失败信封。Agent 应先检查进程退出码，再读取ok和 error.retryable，不要解析人类文本。

{
  "ok": true,
  "data": { "renderTaskId": "rt_01J...", "status": "queued" },
  "meta": { "requestId": "...", "timestamp": "..." }
}

{
  "ok": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "请求过于频繁",
    "retryable": true
  },
  "meta": { "requestId": "...", "timestamp": "..." }
}

任务生命周期

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

模板参数不生效排查（HyperFrames）

编写 HyperFrames 模板 .html 时，如果模板里的 JS 读参数用错了 window 属性名， 会导致「预览里改参数生效、走正式渲染任务出来的视频没生效」的分裂表现。这一节说明成因和唯一需要的一行代码修复。

症状：怎么判断踩到了这个坑

• 在 studio 预览 / 本地 preview 里改参数是生效的；
• 但走正式 /render-tasks 出来的视频里，文本参数（title / subtitle / 文案 等）没变，还是默认值；
• 有些颜色参数（accent、bg 等）却生效了——因为它们同时通过 CSS var(--xxx) 走了另一条通道；
• 后端 API 请求体里 inputProps 的值是对的（浏览器网络面板里能看到改后的值）。

原因：预览和正式渲染注入的名字不一样

@hyperframes/producer 在正式渲染时，会同时做两件事把 inputProps 注入到页面：

而 studio / 本地预览 / ff-server 预览接口为了兼容历史模板，另外挂了两个别名。四个环境注入的 window 属性对照如下：

如果模板脚本里只读 window.__HV_VARS__（很多老 demo 就是这样写的），正式渲染时 variables 就是空 {}，所有 JS 里读的字段就都回退到默认值。 颜色能生效纯属侥幸——它同时借道通道 ① 的 CSS 自定义属性被注入了一遍。

解决方案：一行改动，三段兜底

❌ 错误写法（会踩坑）

// 只读一个别名，正式渲染下拿不到值
const variables = window.__HV_VARS__ || {};

// 更糟：不做保护，__hyperframes 不存在时会 TypeError
const variables = window.__hyperframes.getVariables();

✅ 正确写法（推荐所有模板都用这一段）

// 变量注入通道优先级：
//   1. window.__hyperframes.getVariables()  —— @hyperframes/producer runtime 官方 API
//                                              （sub-composition 作用域 / 未来 runtime 版本）
//   2. window.__hfVariables                —— 当前生产渲染管线 (evaluateOnNewDocument) 注入的名字
//   3. window.__HV_VARS__                  —— HyperFramesStory 预览 shim / MassRender 预览注入的名字
const variables =
  window.__hyperframes?.getVariables?.() ||
  window.__hfVariables ||
  window.__HV_VARS__ ||
  {};

// 后面照常用 variables.title / variables.subtitle / variables.accent ...

完整最小示例

<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <meta data-composition-id="my-card" data-width="640" data-height="360">
  <style>
    body { margin: 0; background: #07111f; color: #fff; font-family: system-ui, sans-serif; }
    #stage { width: 640px; height: 360px; display: grid; place-content: center; text-align: center; }
    #badge { color: var(--accent); font-weight: 700; letter-spacing: .2em; }
    h1 { color: var(--accent); margin: 0; font-size: 48px; }
    p { color: #bfd7ea; }
  </style>
</head>
<body>
  <main id="stage"
        data-composition-id="my-card"
        data-duration="3"
        data-composition-variables='[
          {"id":"title","type":"string","label":"标题","default":"Hello"},
          {"id":"subtitle","type":"string","label":"副标题","default":"World"},
          {"id":"accent","type":"color","label":"强调色","default":"#38bdf8"}
        ]'>
    <div>
      <div id="badge">BRAND</div>
      <h1 id="title">Hello</h1>
      <p id="subtitle">World</p>
    </div>
  </main>

  <script>
    // ✅ 三段兜底：预览、正式渲染、未来 runtime 都能拿到值
    const variables =
      window.__hyperframes?.getVariables?.() ||
      window.__hfVariables ||
      window.__HV_VARS__ ||
      {};

    // CSS 变量：producer 在 <head> 里已经注入 :root { --accent: <值> }，
    // 这一行是给预览环境或旧运行时的兜底，保持写法一致。
    document.documentElement.style.setProperty('--accent', variables.accent || '#38bdf8');
    document.getElementById('title').textContent = variables.title || 'Hello';
    document.getElementById('subtitle').textContent = variables.subtitle || 'World';
  </script>
</body>
</html>

发布前自检清单

• <script> 里读变量那一行，是否用了推荐的三段兜底？
• 除了 CSS var(--xxx)，所有 JS 读的字段都通过 variables.<id> 取值，且给了 || '默认值' 兜底？
• 至少跑过一次正式 render（不是预览），确认 title / subtitle / 数组 等纯 JS 驱动的字段确实生效？

只在预览里跑不能证明模板参数在生产是好的——预览和生产的注入名字不一样。

通用 FFmpeg 执行器

除了模板渲染，万象渲染还提供通用的 FFmpeg 执行能力：你只传「外部 URL 输入」+ 「命令数组」+「输出文件名」，服务端把输入取到受控存储后在云函数上执行 ffmpeg。 适用于转码、加水印、截图、媒体信息查询等任意 ffmpeg 任务，无需预先制作模板。

FFmpeg 命令

FFmpeg 子命令在 massrender ffmpeg 命名空间下， 与渲染命令同样支持 --json 机器输出。

ffmpeg create 参数

# 转码：1080p → 720p h264
massrender ffmpeg create \
  --input "main.mp4=https://cdn.example.com/input.mp4" \
  --args "-i main.mp4 -vf scale=-2:720 -c:a aac out.mp4" \
  --output-file out.mp4

# 多输入加水印（--args 支持引号）
massrender ffmpeg create \
  --input "main.mp4=https://cdn.example.com/input.mp4" \
  --input "logo.png=https://cdn.example.com/logo.png" \
  --args "-i main.mp4 -i logo.png -filter_complex [0:v][1:v]overlay=W-w-10:10 -c:a copy out.mp4" \
  --output-file out.mp4

# ffprobe 查询媒体信息（无需 --output-file）
massrender ffmpeg create --mode ffprobe \
  --input "main.mp4=https://cdn.example.com/input.mp4" \
  --args "-v error -print_format json -show_format -show_streams -i main.mp4"

# 轮询至终态并以 JSON 输出
massrender ffmpeg wait <ffmpeg-id> --json

FFmpeg RESTful API

外部服务通过 X-API-KEY或 Bearer Token 访问，认证方式与渲染任务一致。成功创建返回 202，任务异步执行； 用 GET 轮询状态。callbackUrl 回调不重试、不保证送达， 客户端应以 GET 轮询结果为准，不要只依赖回调。

POST/api/v1/ffmpeg-tasks

# ffmpeg 模式：转码
curl -X POST /api/v1/ffmpeg-tasks \
  -H "X-API-KEY: $MASSRENDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {"main.mp4": "https://cdn.example.com/input.mp4"},
    "commands": [["-i", "main.mp4", "-c:v", "libx264", "-pix_fmt", "yuv420p", "out.mp4"]],
    "output": {"fileName": "out.mp4"},
    "mode": "ffmpeg",
    "profile": "standard"
  }'

# → 202 Accepted
{"taskId": "ffmpeg-3f0e6a1f-...","status": "queued", "error": null}

# ffprobe 模式：媒体信息查询（无 output 字段）
curl -X POST /api/v1/ffmpeg-tasks \
  -H "X-API-KEY: $MASSRENDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {"main.mp4": "https://cdn.example.com/input.mp4"},
    "commands": [["-v","error","-print_format","json","-show_format","-show_streams","-i","main.mp4"]],
    "mode": "ffprobe",
    "profile": "standard"
  }'

GET/api/v1/ffmpeg-tasks/:taskId

curl /api/v1/ffmpeg-tasks/ffmpeg-3f0e6a1f-... \
  -H "X-API-KEY: $MASSRENDER_API_KEY"

{
  "taskId": "ffmpeg-3f0e6a1f-...",
  "status": "completed",
  "finalHttpUrl": "https://signed.example.com/.../out.mp4",
  "output": {
    "sizeInBytes": 60098, "width": 1280, "height": 720,
    "codec": "h264", "durationSeconds": 3.0
  },
  "probeResult": null,
  "error": null, "errorCode": null
}

错误码

任务进入 failed 终态时，errorCode字段携带任务级原因（FFMPEG_TIMEOUT、FFMPEG_INPUT_FETCH_FAILED、FFMPEG_EXEC_FAILED 等）。 下方结构化参考由 OpenAPI 规范自动生成。

临时素材（素材库）

除了「外部 URL」输入，万象渲染还提供临时素材能力： 客户先把生产素材（视频、图片等）上传，服务端返回一个内网oss://链接。该链接只能回传给 ffmpeg 任务的 inputs 或渲染任务的inputProps 媒体变量作为消费凭证， 不能当作 HTTP URL 在浏览器直接打开。

素材 RESTful API

通过 X-API-KEY 或 Bearer Token 访问， 认证方式与渲染任务一致。租户由登录态自动注入，客户端无需也无法指定租户。

POST/api/v1/temp-assets

# 上传原始字节（raw body，不要 JSON 包装；文件名建议 percent-encode）
curl -X POST /api/v1/temp-assets \
  -H "X-API-KEY: $MASSRENDER_API_KEY" \
  -H "X-File-Name: hero.mp4" \
  -H "Content-Type: video/mp4" \
  --data-binary @hero.mp4

# → 201 Created
{
  "assetId": "ta_0123456789abcdef0123456789abcdef",
  "fileName": "hero.mp4",
  "sizeBytes": 1048576,
  "contentType": "video/mp4",
  "sha256": "a".repeat(64),
  "url": "oss://framefuture-video/remotion-fc-renders/temp-assets/tenant-xxx/ta_0123.../hero.mp4",
  "expiresAt": "2026-08-07T08:00:00.000Z",
  "quota": {"usedBytes": 1048576, "quotaBytes": 10737418240, "remainingBytes": 10736369664, "assetCount": 1}
}

GET/api/v1/temp-assets · /api/v1/temp-assets/quota

# 列出未过期素材 + 配额
curl /api/v1/temp-assets -H "X-API-KEY: $MASSRENDER_API_KEY"

# 只取配额快照
curl /api/v1/temp-assets/quota -H "X-API-KEY: $MASSRENDER_API_KEY"

GET/DELETE/api/v1/temp-assets/:assetId

# 单素材元数据
curl /api/v1/temp-assets/ta_0123456789abcdef0123456789abcdef -H "X-API-KEY: $MASSRENDER_API_KEY"

# 删除素材并释放配额
curl -X DELETE /api/v1/temp-assets/ta_0123456789abcdef0123456789abcdef \
  -H "X-API-KEY: $MASSRENDER_API_KEY"

# → 200 {"deleted": true, "tenantRef": "tenant-xxx", "quota": {...}}

消费方式

上传返回的 oss:// 链接可回传给：

# FFmpeg 任务：把素材作为输入（inputs 值直接用 oss:// 链接）
curl -X POST /api/v1/ffmpeg-tasks \
  -H "X-API-KEY: $MASSRENDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {"main.mp4": "oss://framefuture-video/remotion-fc-renders/temp-assets/tenant-xxx/ta_0123.../hero.mp4"},
    "commands": [["-i", "main.mp4", "-c:v", "libx264", "-pix_fmt", "yuv420p", "out.mp4"]],
    "output": {"fileName": "out.mp4"},
    "mode": "ffmpeg", "profile": "standard"
  }'

错误码

下方结构化参考由 OpenAPI 规范自动生成。

prepare 阶段

很多视频在正式渲染前需要先做一步准备：抽音轨、做语音识别、按文稿打轴、算出字幕分页。 万象渲染把这步交给你自己的代码——项目里声明一个 prepare 入口， 平台在渲染前执行它，把它返回的 props 作为这次渲染的inputProps。平台在这个过程中提供 ffmpeg、 ASR、存储和受限 HTTP 四类调用，怎么组合、分页规则是什么，都由你的代码决定。

声明方式随项目类型不同：Remotion 项目写在 package.json 的massrender.prepare 里；HyperFrames 项目写在项目清单的entries[].prepare 里。

// package.json（Remotion）
{
  "massrender": {
    "prepare": "prepare/main.mjs",
    "allowedHosts": ["api.example.com"]
  }
}

// prepare/main.mjs —— 最小骨架
export default async (ctx) => {
  const {video, script, language} = ctx.input;

  // ① 抽音轨
  const audio = await ctx.ffmpeg.run({
    inputs: {src: video.url},
    commands: [['-i', 'src', '-vn', '-c:a', 'aac', '-ar', '16000', '-ac', '1', 'narration.m4a']],
    output: {fileName: 'narration.m4a'},
  });

  // ② 有稿子打轴，没稿子纯识别
  const asr = script
    ? await ctx.asr.align({audio: audio.output.url, text: script, language})
    : await ctx.asr.transcribe({audio: audio.output.url, language});

  // ③ 返回的 props 直接成为渲染 inputProps
  return {
    props: {
      video,
      voiceover: audio.output,
      pages: [{
        text: asr.utterances.map((u) => u.text).join(''),
        start: 0,
        end: asr.audioSeconds ?? 0,
      }],
    },
    usage: {audioSeconds: asr.audioSeconds},
  };
};

能力清单

四类调用的凭据都在平台侧，你的代码只拿到调用入口。每次调用都计入usage，费用以平台侧计数为准。

返回值与缓存

return {
  props,                               // 必填：这次渲染的 inputProps
  cacheable: false,                    // 可选：是否允许平台缓存本次结果
  usage: {audioSeconds: 42.5},         // 可选：仅为提示，计费以平台计数为准
};

• • props 必须满足 entry 的 inputSchema。该 schema 由项目的默认参数反推，且不允许额外字段。prepare 多返回一个 key 就会判为PREPARE_OUTPUT_INVALID，所以默认参数要覆盖 prepare 会返回的全部顶层字段（例如字幕组件返回 voiceover，默认参数里就要有这个 key）。
• • 默认不缓存。设 cacheable: true 才按「制品 + prepare 路径 + entry + 输入」缓存 30 天； 但产出过 output.url 的那次运行永不缓存（URL 有效期远短于缓存）。 要复用昂贵计算，用 ctx.storage。
• • ASR 结果平台另有缓存（默认 30 天），命中时不再向识别服务提交，但仍按命中时长计费—— 缓存省的是延迟和上游配额，不是这笔费用。
  命中条件很严格：缓存键包含音频地址本身。每次用ctx.ffmpeg.run 重新抽音轨都会得到新地址， 即使音频内容相同也不会命中。要复用结果，二选一：把音频地址固定下来 （每轮都指向同一个稳定地址，而不是重新抽），或用 ctx.storage 自己按内容缓存。
• • props 超过 1 MiB 时平台会把它存到对象存储，任务详情里只保留引用。

错误码与排查

prepare 阶段的失败会让任务以 failed 结束，回调render.failed 的error.stage 为prepare，error.code 是下表之一。查询任务时读error.code 判断原因。

一个容易误判的场景：用命令行工具生成预签名地址做调试，如果工具把额外的计时行混进了输出，或把路径里的/ 编码成%2F，对象存储会返回 403SignatureDoesNotMatch，但在任务里看到的却是FFMPEG_TASK_FAILED: input URL returned HTTP 403。 判断方法：同一串地址用 curl 能取到、换另一个 HTTP 客户端却 403，问题在地址本身，不在权限。

FC 实现

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

企业级 FC 自部署

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

生产接入建议

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