### FFmpeg CLI Commands

Source: https://massrender.com/docs

Examples of using the massrender CLI to perform transcoding, watermarking, and media information retrieval via ffprobe.

```bash
# 转码：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
```

--------------------------------

### GET /api/v1/temp-assets

Source: https://massrender.com/docs

列出当前租户下所有未过期的临时素材。

```APIDOC
## GET /api/v1/temp-assets

### Description
列出当前租户下所有未过期的临时素材列表。

### Method
GET

### Endpoint
/api/v1/temp-assets
```

--------------------------------

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

Source: https://massrender.com/docs

获取当前租户的素材配额使用快照。

```APIDOC
## GET /api/v1/temp-assets/quota

### Description
获取当前租户的素材配额使用快照。

### Method
GET

### Endpoint
/api/v1/temp-assets/quota
```

--------------------------------

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

Source: https://massrender.com/docs

获取指定素材的元数据信息。

```APIDOC
## GET /api/v1/temp-assets/:assetId

### Description
获取指定素材的元数据信息。

### Method
GET

### Endpoint
/api/v1/temp-assets/:assetId

### Parameters
#### Path Parameters
- **assetId** (string) - Required - 素材唯一标识
```

--------------------------------

### massrender ffmpeg get

Source: https://massrender.com/docs

Queries the status, output download URL, or ffprobe results for a specific task.

```APIDOC
## massrender ffmpeg get <taskId>

### Description
Retrieves the current status and results of a previously submitted FFmpeg task using its taskId.

### Parameters
- **taskId** (string) - Required - The unique identifier returned by the create command.
```

--------------------------------

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

Source: https://massrender.com/docs

Retrieves the status and details of a specific rendering task.

```APIDOC
## GET /api/v1/render-tasks/:renderTaskId

### Description
Retrieves the current status, progress, and output information for a specific rendering task.

### Method
GET

### Endpoint
/api/v1/render-tasks/:renderTaskId

### Parameters
#### Path Parameters
- **renderTaskId** (string) - Required - The unique identifier of the render task.

### Response
#### Success Response (200)
- **renderTaskId** (string) - The ID of the task.
- **status** (string) - The current status (e.g., rendering).
- **progress** (object) - Progress details including percent and chunks.
- **output** (string|null) - The output URL or null if not ready.

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

--------------------------------

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

Source: https://massrender.com/docs

Retrieves the current status and results of a specific task by its ID.

```APIDOC
## GET /api/v1/ffmpeg-tasks/:taskId

### Description
Polls the status of a previously created task. Clients should use this endpoint to check for task completion.

### Method
GET

### Endpoint
/api/v1/ffmpeg-tasks/:taskId

### Parameters
#### Path Parameters
- **taskId** (string) - Required - The unique identifier of the task.

### Response
#### Success Response (200)
- **taskId** (string) - Unique identifier for the task.
- **status** (string) - Current status (e.g., 'completed').
- **finalHttpUrl** (string) - URL to the processed output file.
- **output** (object) - Metadata about the output file.
- **error** (string|null) - Error message if the task failed.
- **errorCode** (string|null) - Specific error code if the task failed.
```

--------------------------------

### Retrieve Task Status

Source: https://massrender.com/docs

Poll the status of a specific task using its taskId via a GET request.

```bash
curl https://massrender.com/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
}
```

--------------------------------

### 在 FFmpeg 任务中消费素材

Source: https://massrender.com/docs

将上传后获得的 oss:// 链接作为 FFmpeg 任务的输入参数。

```bash
# FFmpeg 任务：把素材作为输入（inputs 值直接用 oss:// 链接）
curl -X POST https://massrender.com/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"
  }'
```

--------------------------------

### 模板与渲染任务操作

Source: https://massrender.com/docs

列出模板并执行渲染任务的创建、等待与下载。

```bash
npx @massrender/cli template list
```

```bash
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
```

--------------------------------

### 账单与任务查询命令

Source: https://massrender.com/docs

查询账户余额、定价、用量以及渲染任务列表的详细用法。

```bash
# 余额、价格与最多 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
```

--------------------------------

### 查询素材列表与配额

Source: https://massrender.com/docs

获取当前租户下未过期的素材列表或仅查询配额快照。

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

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

--------------------------------

### 安装与初始化 CLI

Source: https://massrender.com/docs

使用 npx 运行 CLI 或进行全局安装，并执行登录操作。

```bash
npx @massrender/cli
```

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

--------------------------------

### Configure and Verify MassRender CLI

Source: https://massrender.com/docs

Set environment variables for the API endpoint and key, then verify authentication status and capabilities.

```bash
export MASSRENDER_API_URL=https://massrender.com/api/v1
export MASSRENDER_API_KEY=***

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

--------------------------------

### Create a Render Task

Source: https://massrender.com/docs

Submit a new render task using a POST request. Ensure the API key is included in the header and do not expose it in client-side code.

```bash
curl -X POST https://massrender.com/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 }
  }'
```

--------------------------------

### Create FFmpeg and FFprobe Tasks

Source: https://massrender.com/docs

Submit transcoding or media analysis tasks using the POST endpoint. FFprobe mode omits the output field.

```bash
# ffmpeg 模式：转码
curl -X POST https://massrender.com/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}
```

```bash
# ffprobe 模式：媒体信息查询（无 output 字段）
curl -X POST https://massrender.com/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"
  }'
```

--------------------------------

### POST /api/v1/render-tasks

Source: https://massrender.com/docs

Creates a new rendering task for the authenticated tenant.

```APIDOC
## POST /api/v1/render-tasks

### Description
Creates a new rendering task. The task is associated with the tenant of the API Key used for authentication.

### Method
POST

### Endpoint
/api/v1/render-tasks

### Request Body
- **projectVersionId** (string) - Required - The ID of the project version.
- **compositionId** (string) - Required - The ID of the composition.
- **inputProps** (object) - Required - Input properties for the render.

### Request Example
{
  "projectVersionId": "pv_01J...",
  "compositionId": "DataReport",
  "inputProps": { "headline": "2026 年度增长", "metricValue": 1280 }
}
```

--------------------------------

### 管理单个临时素材

Source: https://massrender.com/docs

获取单个素材的元数据或删除素材以释放配额。

```bash
# 单素材元数据
curl https://massrender.com/api/v1/temp-assets/ta_0123456789abcdef0123456789abcdef -H "X-API-KEY: $MASSRENDER_API_KEY"

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

--------------------------------

### 上传临时素材

Source: https://massrender.com/docs

使用 POST 请求上传原始二进制文件。文件名建议进行 percent-encode 处理。

```bash
# 上传原始字节（raw body，不要 JSON 包装；文件名建议 percent-encode）
curl -X POST https://massrender.com/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
```

--------------------------------

### massrender ffmpeg create

Source: https://massrender.com/docs

Creates a new asynchronous FFmpeg or ffprobe task. Returns a taskId upon successful submission.

```APIDOC
## massrender ffmpeg create

### Description
Creates a new asynchronous FFmpeg or ffprobe task. The task is executed in the cloud, and the command returns a taskId immediately.

### Parameters
- **--mode** (string) - Optional - Execution mode: 'ffmpeg' (default) or 'ffprobe'.
- **--profile** (string) - Optional - Resource tier: 'standard' (default), 'highmem', or 'gpu'.
- **--input** (string) - Required - Input file declaration in 'name=url' format. Can be repeated.
- **--args** (string) - Required - FFmpeg/ffprobe command arguments. Must reference files declared in --input.
- **--output-file** (string) - Required (if mode=ffmpeg) - The output filename.
- **--callback-url** (string) - Optional - URL to POST to when the task reaches a terminal state.

### Request Example
```bash
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
```
```

--------------------------------

### POST /api/v1/temp-assets

Source: https://massrender.com/docs

上传原始素材文件。通过 HTTP 请求体发送原始字节，文件名通过 X-File-Name 请求头指定。

```APIDOC
## POST /api/v1/temp-assets

### Description
上传原始素材文件，服务端返回内网 oss:// 链接作为渲染任务的消费凭证。

### Method
POST

### Endpoint
/api/v1/temp-assets

### Parameters
#### Request Headers
- **X-File-Name** (string) - Required - 文件名，建议进行 percent-encode
- **Content-Type** (string) - Required - 文件的 MIME 类型

### Response
#### Success Response (201)
- **assetId** (string) - 素材唯一标识
- **fileName** (string) - 文件名
- **sizeBytes** (number) - 文件大小
- **url** (string) - 内网 oss:// 链接
- **expiresAt** (string) - 过期时间
- **quota** (object) - 当前租户配额使用情况
```

--------------------------------

### massrender render create

Source: https://massrender.com/docs

Initiates a new rendering task based on a specified template and properties.

```APIDOC
## massrender render create

### Description
Creates a new rendering task. This command returns immediately, making it suitable for Agent orchestration.

### Parameters
- **--template** (string) - Required - The template ID or key to use for rendering.
- **--props** (string) - Optional - JSON string containing input properties for the template.
- **--json** (flag) - Optional - Output the result in JSON format.
```

--------------------------------

### POST /api/v1/ffmpeg-tasks

Source: https://massrender.com/docs

Creates a new FFmpeg or ffprobe task. The task is processed asynchronously, and the API returns a 202 Accepted status with a taskId.

```APIDOC
## POST /api/v1/ffmpeg-tasks

### Description
Creates a new media processing task. Use 'ffmpeg' mode for transcoding and 'ffprobe' mode for media information retrieval.

### Method
POST

### Endpoint
/api/v1/ffmpeg-tasks

### Request Body
- **inputs** (object) - Required - Map of input file names to their source URLs.
- **commands** (array) - Required - List of FFmpeg/ffprobe command arguments.
- **output** (object) - Optional - Configuration for the output file (required for ffmpeg mode).
- **mode** (string) - Required - Processing mode: 'ffmpeg' or 'ffprobe'.
- **profile** (string) - Required - Execution profile, e.g., 'standard'.

### Request Example
{
  "inputs": {"main.mp4": "https://cdn.example.com/input.mp4"},
  "commands": [["-i", "main.mp4", "-c:v", "libx264", "out.mp4"]],
  "output": {"fileName": "out.mp4"},
  "mode": "ffmpeg",
  "profile": "standard"
}

### Response
#### Success Response (202)
- **taskId** (string) - Unique identifier for the task.
- **status** (string) - Current status of the task (e.g., 'queued').
- **error** (string|null) - Error message if applicable.
```

--------------------------------

### Retrieve Render Task Status

Source: https://massrender.com/docs

Fetch the status and progress of a specific render task by its ID.

```bash
curl https://massrender.com/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
                }
```

--------------------------------

### Success Response Format

Source: https://massrender.com/docs

The standard JSON structure returned upon successful API requests.

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

--------------------------------

### massrender billing usage

Source: https://massrender.com/docs

Queries billing usage information, including monthly summaries and daily details.

```APIDOC
## massrender billing usage

### Description
Retrieves billing usage data. Supports daily breakdowns and date range filtering.

### Parameters
- **--daily** (flag) - Optional - Enables daily detail view.
- **--from** (string) - Optional - Start date (YYYY-MM-DD).
- **--to** (string) - Optional - End date (YYYY-MM-DD).
- **--json** (flag) - Optional - Output the result in JSON format.
```

--------------------------------

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

Source: https://massrender.com/docs

删除指定素材并释放对应的配额。

```APIDOC
## DELETE /api/v1/temp-assets/:assetId

### Description
删除指定素材并立即释放配额。

### Method
DELETE

### Endpoint
/api/v1/temp-assets/:assetId

### Parameters
#### Path Parameters
- **assetId** (string) - Required - 素材唯一标识
```

--------------------------------

### massrender ffmpeg wait

Source: https://massrender.com/docs

Polls a task until it reaches a terminal state (completed or failed).

```APIDOC
## massrender ffmpeg wait <taskId>

### Description
Blocks execution and polls the task status until it completes or fails. Supports --json output for machine parsing.

### Parameters
- **taskId** (string) - Required - The unique identifier of the task.
- **--interval** (number) - Optional - Polling interval.
- **--timeout** (number) - Optional - Maximum wait time.
- **--json** (flag) - Optional - Output result in JSON format.
```

--------------------------------

### massrender render wait

Source: https://massrender.com/docs

Polls a rendering task until it reaches a terminal state (completed, failed, cancelled, or timed out).

```APIDOC
## massrender render wait <renderTaskId>

### Description
Polls the status of a specific rendering task until it completes or reaches a final state.

### Parameters
- **renderTaskId** (string) - Required - The unique identifier of the rendering task.
- **--output** (string) - Optional - Format of the output (text, json, or jsonl).
```

--------------------------------

### Failure Response Format

Source: https://massrender.com/docs

The standard JSON structure returned when an API request fails, including error details and retryability status.

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

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.