blitzreels-video-editing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

BlitzReels Video Editing

BlitzReels 视频编辑

Edit videos via the BlitzReels API: upload media, transcribe, edit timeline, apply captions, add overlays and backgrounds, then export.

If the task is specifically long-form to shorts, podcast-to-shorts, suggestion-backed clipping, or public automatic-layout reframe planning, prefer the

blitzreels-clipping

skill first and come back here for lower-level timeline work.

Important: project preview and visual QA endpoints now exist. Use them when an agent needs to verify framing, caption placement, or layout visually before export.

通过BlitzReels API编辑视频：上传媒体、转写内容、编辑时间线、添加字幕、叠加层与背景，最后导出成品。

如果你的任务具体是长视频转短视频、播客转短视频、带建议的剪辑，或者公共自动布局重构图规划，请优先使用

blitzreels-clipping

skill，需要更低层级的时间线操作时再回到本工具。

重要提示：目前已提供项目预览和视觉QA接口。当Agent需要在导出前可视化验证构图、字幕位置或布局时，请使用这些接口。

Quick Start

快速开始

bash

undefined

bash

undefined

Upload a video from URL

bash scripts/editor.sh upload-url PROJECT_ID "https://example.com/video.mp4"

Add to timeline and transcribe

bash scripts/editor.sh add-media PROJECT_ID MEDIA_ID bash scripts/editor.sh transcribe PROJECT_ID MEDIA_ID

Trim, caption, export

bash scripts/editor.sh trim PROJECT_ID ITEM_ID 1.0 -2.0 bash scripts/editor.sh captions PROJECT_ID viral-center bash scripts/editor.sh export PROJECT_ID --resolution 1080p

undefined

bash scripts/editor.sh trim PROJECT_ID ITEM_ID 1.0 -2.0 bash scripts/editor.sh captions PROJECT_ID viral-center bash scripts/editor.sh export PROJECT_ID --resolution 1080p

undefined

Primary Workflow

核心工作流

Create project —

POST /projects {"name":"...", "aspect_ratio":"9:16"}

Upload media —
```
editor.sh upload-url
```
(URL import) or 2-step presigned upload
Add to timeline —
```
editor.sh add-media
```
places media on the timeline
Transcribe —
```
editor.sh transcribe
```
generates word-level captions
Get context —
```
editor.sh context
```
to see timeline state
Edit timeline — trim, split, delete, reorder, auto-remove silences
Apply captions —
```
editor.sh captions <presetId>
```
for styled subtitles
Add overlays — text overlays, motion code, motion graphics
Add background — fill layers (gradients, cinematic, patterns)
Export —
```
editor.sh export
```
renders final video with download URL

创建项目 — 调用

POST /projects {"name":"...", "aspect_ratio":"9:16"}

上传媒体 — 执行
```
editor.sh upload-url
```
（URL导入）或者两步预签名上传
添加到时间线 — 执行
```
editor.sh add-media
```
将媒体放到时间线上
转写 — 执行
```
editor.sh transcribe
```
生成词级字幕
获取上下文 — 执行
```
editor.sh context
```
查看时间线状态
编辑时间线 — 裁剪、拆分、删除、重排序、自动移除静默片段
应用字幕 — 执行
```
editor.sh captions <presetId>
```
使用带样式的字幕模板
添加叠加层 — 文本叠加层、动态代码、动态图形
添加背景 — 填充层（渐变、电影感、图案）
导出 — 执行
```
editor.sh export
```
渲染最终视频并返回下载链接

Scripts

脚本

scripts/editor.sh

scripts/editor.sh

Subcommand wrapper for common editing operations.

Command	Usage	Description
`upload-url`	`<projectId> <url> [name]`	Upload media from URL
`transcribe`	`<projectId> <mediaId>`	Transcribe + poll until done
`context`	`<projectId> [mode]`	Get project context (default: timeline)
`timeline-at`	`<projectId> <seconds>`	Get items at timestamp
`trim`	`<projectId> <itemId> <startDelta> <endDelta>`	Trim item edges
`split`	`<projectId> <itemId> <atSeconds>`	Split item at time
`delete-item`	`<projectId> <itemId>`	Delete timeline item
`add-media`	`<projectId> <mediaId> [startSec]`	Add media to timeline
`add-broll`	`<projectId> <JSON>`	Add B-roll clip
`captions`	`<projectId> <presetId>`	Apply caption preset
`export`	`<projectId> [--resolution R]`	Export + poll + download URL

Run

bash scripts/editor.sh --help

for full usage.

常用编辑操作的子命令封装工具。

Command	Usage	描述
`upload-url`	`<projectId> <url> [name]`	从URL上传媒体
`transcribe`	`<projectId> <mediaId>`	转写并轮询直到任务完成
`context`	`<projectId> [mode]`	获取项目上下文（默认：时间线）
`timeline-at`	`<projectId> <seconds>`	获取指定时间戳的素材项
`trim`	`<projectId> <itemId> <startDelta> <endDelta>`	裁剪素材项两端
`split`	`<projectId> <itemId> <atSeconds>`	在指定时间点拆分素材项
`delete-item`	`<projectId> <itemId>`	删除时间线素材项
`add-media`	`<projectId> <mediaId> [startSec]`	向时间线添加媒体
`add-broll`	`<projectId> <JSON>`	添加B-roll片段
`captions`	`<projectId> <presetId>`	应用字幕模板
`export`	`<projectId> [--resolution R]`	导出并轮询返回下载链接

运行

bash scripts/editor.sh --help

查看完整用法。

scripts/blitzreels.sh

scripts/blitzreels.sh

Generic API helper for direct endpoint calls. Use for overlays, effects, and advanced operations where

editor.sh

doesn't have a shortcut.

bash

bash scripts/blitzreels.sh METHOD /path [JSON_BODY]

通用API辅助工具，用于直接调用接口。当

editor.sh

没有对应快捷操作时，可使用它处理叠加层、特效和高级操作。

bash

bash scripts/blitzreels.sh METHOD /path [JSON_BODY]

Environment Variables

环境变量

Variable	Required	Description
`BLITZREELS_API_KEY`	Yes	API key ( `br_live_...` )
`BLITZREELS_API_BASE_URL`	No	Override base URL (default: `https://www.blitzreels.com/api/v1` )
`BLITZREELS_ALLOW_EXPENSIVE`	No	Set to `1` for export calls via `blitzreels.sh`

变量	必填	描述
`BLITZREELS_API_KEY`	是	API密钥（ `br_live_...` ）
`BLITZREELS_API_BASE_URL`	否	覆盖默认基础URL（默认： `https://www.blitzreels.com/api/v1` ）
`BLITZREELS_ALLOW_EXPENSIVE`	否	通过 `blitzreels.sh` 调用导出接口时需将其设置为 `1`

API Endpoint Index

API接口索引

Projects

项目

Method	Path	Description
POST	`/projects`	Create project
GET	`/projects/{id}`	Get project details
PATCH	`/projects/{id}`	Update project settings
DELETE	`/projects/{id}`	Delete project
GET	`/projects`	List projects

Method	Path	描述
POST	`/projects`	创建项目
GET	`/projects/{id}`	获取项目详情
PATCH	`/projects/{id}`	更新项目设置
DELETE	`/projects/{id}`	删除项目
GET	`/projects`	列出项目

Media

媒体

Method	Path	Description
POST	`/projects/{id}/media`	Import media from URL
POST	`/projects/{id}/upload/presigned`	Get presigned upload URL
POST	`/projects/{id}/upload/finalize`	Finalize presigned upload

Method	Path	描述
POST	`/projects/{id}/media`	从URL导入媒体
POST	`/projects/{id}/upload/presigned`	获取预签名上传URL
POST	`/projects/{id}/upload/finalize`	完成预签名上传

Transcription

转写

Method	Path	Description
POST	`/projects/{id}/transcribe`	Start transcription job
GET	`/jobs/{jobId}`	Poll job status
GET	`/projects/{id}/context?mode=transcript`	Get transcript
POST	`/projects/{id}/captions/regenerate`	Re-transcribe media

Method	Path	描述
POST	`/projects/{id}/transcribe`	启动转写任务
GET	`/jobs/{jobId}`	轮询任务状态
GET	`/projects/{id}/context?mode=transcript`	获取转写结果
POST	`/projects/{id}/captions/regenerate`	重新转写媒体

Captions

字幕

Method	Path	Description
POST	`/projects/{id}/captions`	Apply caption preset
GET	`/projects/{id}/captions/style`	Get current style
PATCH	`/projects/{id}/captions/style`	Update style settings
GET	`/projects/{id}/captions/presets`	List presets by category
PATCH	`/projects/{id}/captions/{captionId}`	Update caption words/timing
DELETE	`/projects/{id}/captions/{captionId}`	Delete caption
POST	`/projects/{id}/captions/words/emphasis`	Emphasize specific words

Method	Path	描述
POST	`/projects/{id}/captions`	应用字幕模板
GET	`/projects/{id}/captions/style`	获取当前字幕样式
PATCH	`/projects/{id}/captions/style`	更新样式设置
GET	`/projects/{id}/captions/presets`	按分类列出字幕模板
PATCH	`/projects/{id}/captions/{captionId}`	更新字幕内容/时间轴
DELETE	`/projects/{id}/captions/{captionId}`	删除字幕
POST	`/projects/{id}/captions/words/emphasis`	强调指定字词

Timeline Editing

时间线编辑

Method	Path	Description
POST	`/projects/{id}/timeline/media`	Add media to timeline
POST	`/projects/{id}/timeline/trim`	Trim item by deltas
POST	`/projects/{id}/timeline/split`	Split item at timestamp
DELETE	`/projects/{id}/timeline/items/{itemId}`	Delete item
PATCH	`/projects/{id}/timeline/items/{itemId}`	Update item
POST	`/projects/{id}/timeline/items/batch-update`	Batch update items
PATCH	`/projects/{id}/timeline/items/{itemId}/volume`	Set volume
PATCH	`/projects/{id}/timeline/items/{itemId}/transform`	Set transform
POST	`/projects/{id}/timeline/pack-clips`	Remove gaps
POST	`/projects/{id}/timeline/silence-detection`	Detect silences
POST	`/projects/{id}/timeline/mistake-detection`	AI mistake detection
POST	`/projects/{id}/timeline/caption-recut`	Caption-based recut plan

Method	Path	描述
POST	`/projects/{id}/timeline/media`	向时间线添加媒体
POST	`/projects/{id}/timeline/trim`	按偏移量裁剪素材项
POST	`/projects/{id}/timeline/split`	在指定时间戳拆分素材项
DELETE	`/projects/{id}/timeline/items/{itemId}`	删除素材项
PATCH	`/projects/{id}/timeline/items/{itemId}`	更新素材项
POST	`/projects/{id}/timeline/items/batch-update`	批量更新素材项
PATCH	`/projects/{id}/timeline/items/{itemId}/volume`	设置音量
PATCH	`/projects/{id}/timeline/items/{itemId}/transform`	设置变换参数
POST	`/projects/{id}/timeline/pack-clips`	移除间隙
POST	`/projects/{id}/timeline/silence-detection`	检测静默片段
POST	`/projects/{id}/timeline/mistake-detection`	AI错误检测
POST	`/projects/{id}/timeline/caption-recut`	基于字幕的重剪计划

Overlays — Text, Motion Code, Motion Graphics

叠加层——文本、动态代码、动态图形

Method	Path	Description
POST	`/projects/{id}/text-overlays`	Add text overlay
PATCH	`/projects/{id}/text-overlays/{oid}`	Update text overlay
DELETE	`/projects/{id}/text-overlays/{oid}`	Remove text overlay
POST	`/projects/{id}/motion-code`	Add animated code block
PATCH	`/projects/{id}/motion-code/{cid}`	Update code block
POST	`/projects/{id}/motion-graphics`	Add motion graphic
PATCH	`/projects/{id}/motion-graphics/{gid}`	Update motion graphic

Method	Path	描述
POST	`/projects/{id}/text-overlays`	添加文本叠加层
PATCH	`/projects/{id}/text-overlays/{oid}`	更新文本叠加层
DELETE	`/projects/{id}/text-overlays/{oid}`	移除文本叠加层
POST	`/projects/{id}/motion-code`	添加动态代码块
PATCH	`/projects/{id}/motion-code/{cid}`	更新代码块
POST	`/projects/{id}/motion-graphics`	添加动态图形
PATCH	`/projects/{id}/motion-graphics/{gid}`	更新动态图形

Backgrounds

背景

Method	Path	Description
POST	`/projects/{id}/fill-layers`	Add fill layer
PATCH	`/projects/{id}/fill-layers/{lid}`	Update fill layer

Method	Path	描述
POST	`/projects/{id}/fill-layers`	添加填充层
PATCH	`/projects/{id}/fill-layers/{lid}`	更新填充层

Context & State

上下文与状态

Method	Path	Description
GET	`/projects/{id}/context?mode=...`	Get project context
GET	`/projects/{id}/timeline/at?time_seconds=X`	Items at timestamp
POST	`/projects/{id}/preview-frame`	Render one still preview
POST	`/projects/{id}/preview-frames`	Render multiple still previews
POST	`/projects/{id}/visual-analysis`	Run structured frame QA
GET	`/projects/{id}/visual-debug`	Get machine-readable layout geometry
POST	`/projects/{id}/timeline/undo`	Undo last action

Method	Path	描述
GET	`/projects/{id}/context?mode=...`	获取项目上下文
GET	`/projects/{id}/timeline/at?time_seconds=X`	获取指定时间戳的素材项
POST	`/projects/{id}/preview-frame`	渲染单张预览图
POST	`/projects/{id}/preview-frames`	渲染多张预览图
POST	`/projects/{id}/visual-analysis`	运行结构化帧QA
GET	`/projects/{id}/visual-debug`	获取机器可读的布局几何信息
POST	`/projects/{id}/timeline/undo`	撤销上一步操作

Media View Repair

媒体视图修复

Method	Path	Description
POST	`/projects/{id}/timeline/media-views/{timelineItemId}`	Upsert source-view crop/canvas state for one item
POST	`/projects/{id}/timeline/media-views/duplicate`	Duplicate a linked source view to another item

Method	Path	描述
POST	`/projects/{id}/timeline/media-views/{timelineItemId}`	为单个素材项更新源视图裁剪/画布状态
POST	`/projects/{id}/timeline/media-views/duplicate`	将关联的源视图复制到另一个素材项

Clipping / Reframe Preview

剪辑/重构图预览

Method	Path	Description
POST	`/workspace/media/assets/{assetId}/reframe-plan/preview`	Generate a reframe plan plus preview stills before apply

Method	Path	描述
POST	`/workspace/media/assets/{assetId}/reframe-plan/preview`	应用前生成重构图计划和预览图

Export & Jobs

导出与任务

Method	Path	Description
POST	`/projects/{id}/export`	Start export (expensive)
GET	`/exports/{exportId}`	Export status + download URL
GET	`/projects/{id}/exports`	Export history
DELETE	`/projects/{id}/exports`	Delete all exports
GET	`/jobs/{jobId}`	Generic job polling

Method	Path	描述
POST	`/projects/{id}/export`	启动导出（成本较高）
GET	`/exports/{exportId}`	导出状态+下载链接
GET	`/projects/{id}/exports`	导出历史
DELETE	`/projects/{id}/exports`	删除所有导出文件
GET	`/jobs/{jobId}`	通用任务轮询

Effects & Keyframes

特效与关键帧

Method	Path	Description
POST	`/projects/{id}/timeline/effects/zoom`	Add zoom effect
POST	`/projects/{id}/timeline/effects/mask`	Add mask effect
POST	`/projects/{id}/timeline/effects/color-grade`	Add color grade
POST	`/projects/{id}/timeline/items/{itemId}/keyframes`	Create keyframe

Method	Path	描述
POST	`/projects/{id}/timeline/effects/zoom`	添加缩放特效
POST	`/projects/{id}/timeline/effects/mask`	添加蒙版特效
POST	`/projects/{id}/timeline/effects/color-grade`	添加调色特效
POST	`/projects/{id}/timeline/items/{itemId}/keyframes`	创建关键帧

Context Modes

上下文模式

Use

?mode=

to control what data the context endpoint returns:

Mode	Returns
`summary`	Project metadata, duration, media count
`assets`	All media assets with metadata
`timeline`	Full timeline with items, layers, timing
`transcript`	Word-level transcript from transcription
`full`	Everything combined

Default:

timeline

bash

bash scripts/editor.sh context PROJECT_ID timeline
bash scripts/editor.sh context PROJECT_ID full

使用

?mode=

参数控制上下文接口返回的数据内容：

Mode	返回内容
`summary`	项目元数据、时长、媒体数量
`assets`	所有带元数据的媒体资产
`timeline`	完整时间线，包含素材项、图层、时间信息
`transcript`	转写生成的词级字幕
`full`	所有内容合并

默认值：

timeline

bash

bash scripts/editor.sh context PROJECT_ID timeline
bash scripts/editor.sh context PROJECT_ID full

Upload Modes

上传模式

URL Import (Simpler)

URL导入（更简单）

bash

bash scripts/editor.sh upload-url PROJECT_ID "https://example.com/video.mp4"

bash

bash scripts/editor.sh upload-url PROJECT_ID "https://example.com/video.mp4"

Presigned 2-Step (For Local Files)

预签名两步上传（适用于本地文件）

bash

undefined

bash

undefined

Step 1: Get presigned URL

PRESIGNED=$(bash scripts/blitzreels.sh POST /projects/PROJECT_ID/upload/presigned
'{"fileName":"video.mp4","contentType":"video/mp4"}')

Step 2: Upload to presigned URL

curl -X PUT "$(echo $PRESIGNED | jq -r '.url')"
-H "Content-Type: video/mp4"
--data-binary @video.mp4

Step 3: Finalize

bash scripts/blitzreels.sh POST /projects/PROJECT_ID/upload/finalize
"{"storageKey":"$(echo $PRESIGNED | jq -r '.key')"}"

undefined

bash scripts/blitzreels.sh POST /projects/PROJECT_ID/upload/finalize
"{"storageKey":"$(echo $PRESIGNED | jq -r '.key')"}"

undefined

Quick Reference

快速参考

Caption presets: 30+ presets across 6 categories — see
```
references/caption-styles.md
```
Active word animations: highlight, scale, glow, lift, bounce, punch, slam, elastic, shake, none
Motion code themes: github-dark, one-dark, dracula, nord, monokai, tokyo-night
Fill layer presets: 38+ across 7 categories — see
```
references/fill-layers.md
```
Timeline layer order: caption(0) → effect(1) → image(2) → video(3) → audio(4) → background(5)

字幕模板：覆盖6个分类的30+模板——详见
```
references/caption-styles.md
```
动态字词动画：高亮、缩放、发光、上浮、弹跳、重击、猛击、弹性、抖动、无
动态代码主题：github-dark、one-dark、dracula、nord、monokai、tokyo-night
填充层模板：覆盖7个分类的38+模板——详见
```
references/fill-layers.md
```
时间线层级顺序：字幕(0) → 特效(1) → 图片(2) → 视频(3) → 音频(4) → 背景(5)

References

参考文档

```
references/clipping.md
```
— Long-form to short workflow, podcast QA loop, preview/repair endpoints
```
references/caption-styles.md
```
— All 30+ presets, CaptionStyleSettings schema, animations
```
references/overlays.md
```
— Text overlays, motion code, motion graphics schemas
```
references/fill-layers.md
```
— 38+ background presets, FillLayerSettings schema
```
references/timeline-ops.md
```
— Timeline endpoints, AI features, keyframes, effects
```
references/export-settings.md
```
— Export params, codecs, polling pattern
```
examples/edit-uploaded-video.md
```
— Full upload→edit→export walkthrough
```
examples/enhance-with-overlays.md
```
— Adding graphics to existing project

```
references/clipping.md
```
— 长视频转短视频工作流、播客QA循环、预览/修复接口
```
references/caption-styles.md
```
— 全部30+模板、CaptionStyleSettings schema、动画效果
```
references/overlays.md
```
— 文本叠加层、动态代码、动态图形schema
```
references/fill-layers.md
```
— 38+背景模板、FillLayerSettings schema
```
references/timeline-ops.md
```
— 时间线接口、AI功能、关键帧、特效
```
references/export-settings.md
```
— 导出参数、编码、轮询模式
```
examples/edit-uploaded-video.md
```
— 上传→编辑→导出完整流程
```
examples/enhance-with-overlays.md
```
— 为现有项目添加图形元素

Safety & Notes

安全提示与注意事项

Use
```
https://www.blitzreels.com/api/v1
```
as base URL (avoid redirect from non-www)
Export and B-roll generation are expensive — require
```
BLITZREELS_ALLOW_EXPENSIVE=1
```
```
editor.sh export
```
sets this automatically;
```
blitzreels.sh
```
requires explicit opt-in
Download URLs are temporary (24h TTL)

Full OpenAPI spec:

https://www.blitzreels.com/api/openapi.json

请使用
```
https://www.blitzreels.com/api/v1
```
作为基础URL（避免非www域名的重定向）
导出和B-roll生成成本较高——需要设置
```
BLITZREELS_ALLOW_EXPENSIVE=1
```
```
editor.sh export
```
会自动设置该参数；
```
blitzreels.sh
```
需要显式开启
下载URL是临时的（24小时有效期）

完整OpenAPI规范：

https://www.blitzreels.com/api/openapi.json

Rate Limits

请求频率限制

Plan	Requests/min	Requests/day
Free	10	100
Lite	30	1,000
Creator	60	5,000
Agency	120	20,000

套餐	每分钟请求数	每日请求数
免费版	10	100
轻量版	30	1,000
创作者版	60	5,000
机构版	120	20,000