把视频项目接入生产系统
万象渲染为不同视频代码项目提供统一的项目管理、鉴权和异步任务 API。可以从内置模板快速生成首个视频,也可以接入已有项目并继续二创;渲染运行时的部署、扩缩容与结果存储由平台处理。
支持的项目
三类项目通过同一套 万象渲染 API 对外提供服务,平台根据项目类型选择对应的构建与渲染适配器。
| 项目类型 | 输入 | 接入方式 | 运行时 |
|---|---|---|---|
| hyperframes | 项目入口 + 渲染参数 | 项目构建产物 | 项目适配器 |
计费方式
托管云渲染以最终输出的视频分钟数为用量单位。月消费达到更高档位后,当月全部渲染分钟使用对应单价,不采用累进分段计算。以下价格作为方案参考,实际开放档位以合同为准。
| 档位 | 月消费区间 | 单价 | 适合场景 |
|---|---|---|---|
| 按量起步 | < ¥5,000 | ¥0.30 / 分钟 | 试用与小规模生产 |
| 稳定增长 | ¥5,000–< ¥20,000 | ¥0.25 / 分钟 | 稳定业务调用 |
| 规模生产 | ¥20,000–< ¥50,000 | ¥0.20 / 分钟 | 高频批量生成 |
| 大规模调用 | ≥ ¥50,000 | ¥0.15 / 分钟 | 大客户与 API 批量任务 |
系统架构
服务层统一处理 API Key、项目和版本解析、参数校验、租户配额与任务状态;运行时层根据项目类型执行实际渲染。
Agent / App
鉴权 / 项目 / 任务
按项目类型路由
并行执行
状态 / 视频
快速开始
- 1
创建项目与版本
选择 hyperframes,并上传对应的构建产物。每次发布生成不可变的项目版本。
- 2
创建 API Key
API Key 只应保存在服务端环境变量或密钥管理服务中,不要暴露在浏览器代码里。
- 3
提交渲染任务
指定项目、版本、渲染入口和业务参数。接口异步返回 renderTaskId。
- 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 与示例。
RenderTasks
10get/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
2post/ffmpeg-tasks创建通用 FFmpeg 任务
get/ffmpeg-tasks/{taskId}查询 FFmpeg 任务状态
RenderTemplates
6get/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
4get/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
3post/preview-sessions创建短期 HyperFrames 预览会话
put/preview-sessions/{sessionId}更新预览变量
delete/preview-sessions/{sessionId}销毁预览会话
Marketplace
3get/marketplace/templates浏览已发布市场模板
get/marketplace/templates/{slug}按 slug 查询市场模板详情
get/marketplace/templates/{templateId}/releases/{releaseId}查询一个公开的不可变 Release
Auth
4post/auth/deviceCLI 设备授权 — 请求 device code
get/auth/device/statusCLI 轮询设备授权状态
post/auth/device/confirm用户在浏览器确认 CLI 授权
post/auth/device/logoutCLI 登出(注销 session)
Account
1get/account返回当前用户、租户与认证类型
Billing
4get/account/balance查询预付费余额与累计渲染消费
get/usage/summary查询本月、上月和近 30 天用量汇总
get/usage/daily查询最多 90 天的逐日用量
get/pricing查询当前租户生效的渲染价格
Capabilities
1get/capabilities发现服务端引擎、质量档位和自动化能力
TempAssets
7get/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 list3. 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 --jsonCLI 命令参考
下列资源命令都支持--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 应先检查进程退出码,再读取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": "..." }
}| 退出码 | 含义 | 建议 |
|---|---|---|
| 0 | 命令成功 | 继续后续步骤 |
| 1 | CLI 本地错误 | 检查参数、文件和本地环境 |
| 2 | API 拒绝且不可重试 | 修正参数、状态或权限 |
| 3 | 未认证或无权限 | 更新 API Key / Token |
| 4 | 可重试错误或等待超时 | 指数退避后重试 |
| 5 | 渲染失败或取消 | 读取任务 error 后决定是否新建任务 |
任务生命周期
任务失败时返回 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 参数
| 参数 | 取值 | 说明 |
|---|---|---|
--mode | ffmpeg | ffprobe | 执行模式;ffmpeg=转码/处理,ffprobe=媒体信息查询。默认 ffmpeg。 |
--profile | standard | highmem | gpu | 规格档位;MVP 仅 standard 已部署(2 vCPU / 3GB / 600s)。 |
--input | "name=url" | 输入文件声明,可重复;URL 必须为 http(s)。如 --input "main.mp4=https://cdn/a.mp4"。 |
--args | shell 字符串 | ffmpeg/ffprobe 参数(支持引号);-i 只能引用 --input 声明的文件名。 |
--output-file | 文件名 | 输出文件名(mode=ffmpeg 必填,且 --args 最后一个参数必须指向它)。 |
--callback-url | URL | 可选;任务进入终态时 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> --jsonFFmpeg 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
}错误码
| HTTP | code | 含义 |
|---|---|---|
| 400 | FFMPEG_INPUT_URL_FORBIDDEN | 输入 URL 协议非 http(s),或指向私网/元数据/localhost 地址 |
| 400 | FFMPEG_COMMAND_URL_FORBIDDEN | commands 里嵌入了网络 URL/协议(-i 只能引用已声明的输入文件名) |
| 400 | FFMPEG_VALIDATION_ERROR | 请求体或命令校验失败(option/filter 白名单、值域等) |
| 404 | FFMPEG_TASK_NOT_FOUND | 任务不存在,或归属校验不通过(任务归属另一租户) |
| 503 | RENDER_SERVICE_UNAVAILABLE | 渲染服务暂时不可用,可重试 |
任务进入 failed 终态时,errorCode字段携带任务级原因(FFMPEG_TIMEOUT、FFMPEG_INPUT_FETCH_FAILED、FFMPEG_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"
}'错误码
| HTTP | code | 含义 |
|---|---|---|
| 400 | VALIDATION_ERROR | 缺/非法租户头、非法文件名、空 body |
| 409 | TEMP_ASSET_QUOTA_EXCEEDED | 租户配额超限(默认 10G) |
| 413 | TEMP_ASSET_FILE_TOO_LARGE | 单文件超过上限(默认 2G) |
| 404 | TEMP_ASSET_NOT_FOUND | 素材不存在,或归属另一租户(IDOR 防护) |
| 429 | TEMP_ASSET_UPLOAD_BUSY | 租户并发上传超过上限,稍后重试 |
| 502 | TEMP_ASSET_UPSTREAM_ERROR | ff-server 无法到达渲染服务(网络层失败),可重试 |
| 503 | RENDER_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 渲染链路部署到客户自己的阿里云环境。
部署范围
FC custom-container、ACR 镜像、OSS 路径、VPC 网络、API 接入、日志与基础监控。
交付服务
环境评估、容量规划、部署验证、使用培训、版本升级和约定周期的技术支持。
价格:商务报价
通常由一次性实施费用与年度支持服务组成,阿里云资源费由企业自行承担。
生产接入建议
- 业务后端负责保存 API Key,前端不直接调用渲染接口。
- 为每个项目使用不可变版本,发布新版本时保留回滚能力。
- 对提交接口设置租户配额、并发限制和输入参数校验。
- Webhook 接收方校验签名,并按 renderTaskId 实现幂等处理。
- 长耗时任务使用异步状态,不要保持同步 HTTP 连接等待视频完成。
准备接入你的第一个项目?
联系我们评估项目类型、运行依赖、并发目标和结果交付方式。