把视频项目接入生产系统

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

当前文档重点:统一接入协议,以及已经通过阿里云函数计算验证分片并发渲染链路。

支持的项目

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

项目类型输入接入方式运行时
hyperframes项目入口 + 渲染参数项目构建产物项目适配器

计费方式

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

档位月消费区间单价适合场景
按量起步< ¥5,000¥0.30 / 分钟试用与小规模生产
稳定增长¥5,000–< ¥20,000¥0.25 / 分钟稳定业务调用
规模生产¥20,000–< ¥50,000¥0.20 / 分钟高频批量生成
大规模调用≥ ¥50,000¥0.15 / 分钟大客户与 API 批量任务
示例:当月渲染 20,000 分钟,适用 ¥0.25/分钟时,月费为 ¥5,000。最终档位和结算规则以企业合同为准。

系统架构

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

业务系统
Agent / App
万象渲染 API
鉴权 / 项目 / 任务
Runtime Adapter
按项目类型路由
Render Workers
并行执行
对象存储
状态 / 视频

快速开始

  1. 1

    创建项目与版本

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

  2. 2

    创建 API Key

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

  3. 3

    提交渲染任务

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

  4. 4

    查询或接收结果

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

认证方式

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

CLI 登录

Authorization: Bearer <token>

适合开发者本机,massrender login 自动保存凭据。

Agent / CI

X-API-KEY: <key>

推荐自动化使用,只保存在密钥管理服务或环境变量。

Web 控制台

同源 Session Cookie

仅供浏览器控制台使用,不应复制到自动化脚本。

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
                }

OPENAPI 3.1 · 45 ENDPOINTS

展开端点可查看认证、参数、请求字段、响应 Schema 与示例。

下载 OpenAPI YAML
Base URL: /api/v1

RenderTasks

10
get/render-tasks游标分页查询渲染任务
post/render-tasks创建渲染任务
post/render-tasks/batch批量并行创建渲染任务
post/render-tasks/batch/import上传 Excel 与图片/视频素材并创建批量渲染
get/render-tasks/batches查询当前租户的批量渲染批次
get/render-tasks/batches/{renderBatchId}查询批次逐行状态
get/render-tasks/{renderTaskId}查询渲染任务
post/render-tasks/{renderTaskId}/cancel请求取消渲染任务
get/render-tasks/{renderTaskId}/download刷新渲染产物下载链接(实时重签 OSS URL,返回 200 + JSON)
post/render-tasks/upload-signature获取 bundle 上传签名(CLI 直传 OSS 用)

FfmpegTasks

2
post/ffmpeg-tasks创建通用 FFmpeg 任务
get/ffmpeg-tasks/{taskId}查询 FFmpeg 任务状态

RenderTemplates

6
get/render-templates列出可渲染的模板目录
post/render-templates创建或更新当前租户的私有渲染模板
get/render-templates/{templateId}查询单个模板详情(匿名可读)
put/render-templates/{templateId}更新当前租户的私有模板配置
delete/render-templates/{templateId}删除当前租户的私有模板
post/render-templates/{templateId}/publish发布模板(draft → published)

RenderProjects

4
get/render-projects列出当前租户的项目
post/render-projects创建渲染项目(CTR-006 幂等:按 slug 找或创建)
get/render-projects/{projectId}按 ID 查询项目
get/render-projects/by-slug/{slug}按 slug 查项目(CTR-006 §4.2)

PreviewSessions

3
post/preview-sessions创建短期 HyperFrames 预览会话
put/preview-sessions/{sessionId}更新预览变量
delete/preview-sessions/{sessionId}销毁预览会话

Marketplace

3
get/marketplace/templates浏览已发布市场模板
get/marketplace/templates/{slug}按 slug 查询市场模板详情
get/marketplace/templates/{templateId}/releases/{releaseId}查询一个公开的不可变 Release

Auth

4
post/auth/deviceCLI 设备授权 — 请求 device code
get/auth/device/statusCLI 轮询设备授权状态
post/auth/device/confirm用户在浏览器确认 CLI 授权
post/auth/device/logoutCLI 登出(注销 session)

Account

1
get/account返回当前用户、租户与认证类型

Billing

4
get/account/balance查询预付费余额与累计渲染消费
get/usage/summary查询本月、上月和近 30 天用量汇总
get/usage/daily查询最多 90 天的逐日用量
get/pricing查询当前租户生效的渲染价格

Capabilities

1
get/capabilities发现服务端引擎、质量档位和自动化能力

TempAssets

7
get/temp-assets列出当前租户未过期临时素材 + 配额
post/temp-assets上传临时素材(RFC 0004)
post/temp-assets/upload-token获取临时素材直传 OSS 凭证(大文件直传)
get/temp-assets/quota租户临时素材配额快照
post/temp-assets/{assetId}/complete完成临时素材直传注册
get/temp-assets/{assetId}查询单素材元数据(租户隔离,跨租户 404)
delete/temp-assets/{assetId}删除素材并释放配额(租户隔离,跨租户 404)

CLI 快速开始

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

0. 安装 CLI(首次使用)

推荐:直接用 npx,免安装免 PATH

npx @massrender/cli

或全局安装:npm install -g @massrender/cli,安装后即可使用 massrender 命令 (当前版本 v0.2.2,要求 Node.js ≥ 22)。

1. 登录

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

2. 查看可用模板

npx @massrender/cli template list

3. Agent 创建并等待任务

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

身份与能力

massrender auth status
验证凭据,并返回认证来源和 API 地址
massrender whoami
返回当前用户、租户与认证类型
massrender capabilities
返回引擎、质量档位、功能和输出格式

模板与项目

massrender template list
列出当前凭据可用的模板
massrender template get <id-or-key>
按模板 ID 或 key 查询详情
massrender template schema <id-or-key>
输出 inputProps 的 JSON Schema
massrender project list
列出当前租户的渲染项目
massrender project get <id-or-slug>
查询项目、composition 和最新可用版本
massrender project upload [dir]
上传并验证项目,可选注册模板

渲染任务

massrender render create
创建任务后立即返回,适合 Agent 编排
massrender render list
按状态、项目和时间范围分页查询
massrender render get <id>
获取完整任务快照
massrender render wait <id>
轮询至完成、失败、取消或超时
massrender render download <id>
刷新下载 URL,或保存到本地文件
massrender render cancel <id>
请求 best-effort 取消任务
massrender render run
创建并等待完成的一体化交互命令

金额与用量

massrender billing balance
查询预付费余额与累计渲染消费
massrender billing usage
查询月度汇总;--daily 查询最多 90 天逐日明细
massrender billing pricing
查询当前质量档位和每分钟价格
# 余额、价格与最多 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 应先检查进程退出码,再读取okerror.retryable,不要解析人类文本。

成功

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

失败

{
  "ok": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "请求过于频繁",
    "retryable": true
  },
  "meta": { "requestId": "...", "timestamp": "..." }
}
退出码含义建议
0命令成功继续后续步骤
1CLI 本地错误检查参数、文件和本地环境
2API 拒绝且不可重试修正参数、状态或权限
3未认证或无权限更新 API Key / Token
4可重试错误或等待超时指数退避后重试
5渲染失败或取消读取任务 error 后决定是否新建任务

任务生命周期

acceptedqueuedrenderingcombiningcompleted

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

通用 FFmpeg 执行器

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

安全模型

  • • ffmpeg 进程永不直连网络,输入由服务端 fetch 到受控存储
  • • 输入 URL 必须为公网 http(s);gateway 拒绝私网/元数据地址
  • • 命令参数经从严白名单校验(option/filter/值域默认拒绝)
  • -i 只能引用已声明的输入文件名

异步与会员体系

  • • 创建返回 202 + taskId,执行在云函数上异步进行
  • • 用 GET 轮询拿终态;callbackUrl 回调为 best-effort(无重试),不应作为唯一判定来源
  • • 不依赖会员订阅,不因套餐过期或调用次数上限拦截
  • • 计费机制以销售合同为准,本文档不承诺具体结算方式

FFmpeg 命令

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

FFmpeg 任务

massrender ffmpeg create
创建通用 FFmpeg 任务(异步提交后立即返回 taskId)
massrender ffmpeg get <taskId>
查询任务状态、产物下载 URL 或 ffprobe 结果
massrender ffmpeg wait <taskId>
轮询至完成或失败(--interval / --timeout 控制节奏)

ffmpeg create 参数

参数取值说明
--modeffmpeg | ffprobe执行模式;ffmpeg=转码/处理,ffprobe=媒体信息查询。默认 ffmpeg。
--profilestandard | highmem | gpu规格档位;MVP 仅 standard 已部署(2 vCPU / 3GB / 600s)。
--input"name=url"输入文件声明,可重复;URL 必须为 http(s)。如 --input "main.mp4=https://cdn/a.mp4"。
--argsshell 字符串ffmpeg/ffprobe 参数(支持引号);-i 只能引用 --input 声明的文件名。
--output-file文件名输出文件名(mode=ffmpeg 必填,且 --args 最后一个参数必须指向它)。
--callback-urlURL可选;任务进入终态时 POST 到该 URL 通知。
# 转码: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 回调为 best-effort(fire-and-forget,无重试), 客户端应保留 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
}

错误码

HTTPcode含义
400FFMPEG_INPUT_URL_FORBIDDEN输入 URL 协议非 http(s),或指向私网/元数据/localhost 地址
400FFMPEG_COMMAND_URL_FORBIDDENcommands 里嵌入了网络 URL/协议(-i 只能引用已声明的输入文件名)
400FFMPEG_VALIDATION_ERROR请求体或命令校验失败(option/filter 白名单、值域等)
404FFMPEG_TASK_NOT_FOUND任务不存在,或归属校验不通过(任务归属另一租户)
503RENDER_SERVICE_UNAVAILABLE渲染服务暂时不可用,可重试

任务进入 failed 终态时,errorCode字段携带任务级原因(FFMPEG_TIMEOUTFFMPEG_INPUT_FETCH_FAILEDFFMPEG_EXEC_FAILED 等)。 下方结构化参考由 OpenAPI 规范自动生成。

临时素材(素材库)

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

生命周期与配额

  • • 素材存活默认 24h(TTL),过期后自动清理,不计入配额
  • • 配额按租户计,默认 10G;上传超过配额返回 409
  • • 单文件默认上限 2G,超过返回 413
  • • 删除素材立即释放配额

安全模型

  • • 素材按租户隔离,跨租户读取/删除返回 404(IDOR 防护)
  • • 文件名经服务端 sanitize:路径分隔符、控制字符、保留控制名会被拒绝
  • oss:// 链接为内网消费凭证,bucket 私有,浏览器不可访问
  • • 上传并发按租户限流,防止单租户占满 worker

素材 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"
  }'

错误码

HTTPcode含义
400VALIDATION_ERROR缺/非法租户头、非法文件名、空 body
409TEMP_ASSET_QUOTA_EXCEEDED租户配额超限(默认 10G)
413TEMP_ASSET_FILE_TOO_LARGE单文件超过上限(默认 2G)
404TEMP_ASSET_NOT_FOUND素材不存在,或归属另一租户(IDOR 防护)
429TEMP_ASSET_UPLOAD_BUSY租户并发上传超过上限,稍后重试
502TEMP_ASSET_UPSTREAM_ERRORff-server 无法到达渲染服务(网络层失败),可重试
503RENDER_SERVICE_UNAVAILABLE渲染服务暂时不可用,可重试

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

FC 实现

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

无状态执行

bundle、job.json、chunk 和最终视频都保存在 OSS,函数实例可以弹性创建和回收。

动态并发

并发来自多个 FC Worker invocation;单个 Worker 内部保持顺序渲染,减少资源竞争。

浏览器复用

温实例复用 Chromium 进程,只为每次渲染创建页面,降低重复启动浏览器的固定开销。

可重入分片

稳定对象键和完成状态检查支持分片重试,Combiner 会根据 OSS 对象校正部分状态。

企业级 FC 自部署

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

企业业务系统
企业 API 网关
FC Orchestrator
FC Workers × N
企业 OSS

部署范围

FC custom-container、ACR 镜像、OSS 路径、VPC 网络、API 接入、日志与基础监控。

交付服务

环境评估、容量规划、部署验证、使用培训、版本升级和约定周期的技术支持。

价格:商务报价

通常由一次性实施费用与年度支持服务组成,阿里云资源费由企业自行承担。

咨询自部署

生产接入建议

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

准备接入你的第一个项目?

联系我们评估项目类型、运行依赖、并发目标和结果交付方式。