Back to Details

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

Upload a video from URL

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

Add to timeline and transcribe

Add to timeline and transcribe

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

Trim, caption, export

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

核心工作流

  1. Create project — 
    POST /projects {"name":"...", "aspect_ratio":"9:16"}
  2. Upload media — 
    editor.sh upload-url
    (URL import) or 2-step presigned upload
  3. Add to timeline — 
    editor.sh add-media
    places media on the timeline
  4. Transcribe — 
    editor.sh transcribe
    generates word-level captions
  5. Get context — 
    editor.sh context
    to see timeline state
  6. Edit timeline — trim, split, delete, reorder, auto-remove silences
  7. Apply captions — 
    editor.sh captions <presetId>
    for styled subtitles
  8. Add overlays — text overlays, motion code, motion graphics
  9. Add background — fill layers (gradients, cinematic, patterns)
  10. Export — 
    editor.sh export
    renders final video with download URL
  1. 创建项目 — 调用
    POST /projects {"name":"...", "aspect_ratio":"9:16"}
  2. 上传媒体 — 执行
    editor.sh upload-url
    （URL导入）或者两步预签名上传
  3. 添加到时间线 — 执行
    editor.sh add-media
    将媒体放到时间线上
  4. 转写 — 执行
    editor.sh transcribe
    生成词级字幕
  5. 获取上下文 — 执行
    editor.sh context
    查看时间线状态
  6. 编辑时间线 — 裁剪、拆分、删除、重排序、自动移除静默片段
  7. 应用字幕 — 执行
    editor.sh captions <presetId>
    使用带样式的字幕模板
  8. 添加叠加层 — 文本叠加层、动态代码、动态图形
  9. 添加背景 — 填充层（渐变、电影感、图案）
  10. 导出 — 执行
    editor.sh export
    渲染最终视频并返回下载链接

Scripts

脚本

scripts/editor.sh

scripts/editor.sh

Subcommand wrapper for common editing operations.
CommandUsageDescription
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.
常用编辑操作的子命令封装工具。
CommandUsage描述
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

环境变量

VariableRequiredDescription
BLITZREELS_API_KEY
YesAPI key (
br_live_...
)
BLITZREELS_API_BASE_URL
NoOverride base URL (default: 
https://www.blitzreels.com/api/v1
)
BLITZREELS_ALLOW_EXPENSIVE
NoSet 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

项目

MethodPathDescription
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
MethodPath描述
POST
/projects
创建项目
GET
/projects/{id}
获取项目详情
PATCH
/projects/{id}
更新项目设置
DELETE
/projects/{id}
删除项目
GET
/projects
列出项目

Media

媒体

MethodPathDescription
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
MethodPath描述
POST
/projects/{id}/media
从URL导入媒体
POST
/projects/{id}/upload/presigned
获取预签名上传URL
POST
/projects/{id}/upload/finalize
完成预签名上传

Transcription

转写

MethodPathDescription
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
MethodPath描述
POST
/projects/{id}/transcribe
启动转写任务
GET
/jobs/{jobId}
轮询任务状态
GET
/projects/{id}/context?mode=transcript
获取转写结果
POST
/projects/{id}/captions/regenerate
重新转写媒体

Captions

字幕

MethodPathDescription
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
MethodPath描述
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

时间线编辑

MethodPathDescription
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
MethodPath描述
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

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

MethodPathDescription
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
MethodPath描述
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

背景

MethodPathDescription
POST
/projects/{id}/fill-layers
Add fill layer
PATCH
/projects/{id}/fill-layers/{lid}
Update fill layer
MethodPath描述
POST
/projects/{id}/fill-layers
添加填充层
PATCH
/projects/{id}/fill-layers/{lid}
更新填充层

Context & State

上下文与状态

MethodPathDescription
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
MethodPath描述
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

媒体视图修复

MethodPathDescription
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
MethodPath描述
POST
/projects/{id}/timeline/media-views/{timelineItemId}
为单个素材项更新源视图裁剪/画布状态
POST
/projects/{id}/timeline/media-views/duplicate
将关联的源视图复制到另一个素材项

Clipping / Reframe Preview

剪辑/重构图预览

MethodPathDescription
POST
/workspace/media/assets/{assetId}/reframe-plan/preview
Generate a reframe plan plus preview stills before apply
MethodPath描述
POST
/workspace/media/assets/{assetId}/reframe-plan/preview
应用前生成重构图计划和预览图

Export & Jobs

导出与任务

MethodPathDescription
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
MethodPath描述
POST
/projects/{id}/export
启动导出（成本较高）
GET
/exports/{exportId}
导出状态+下载链接
GET
/projects/{id}/exports
导出历史
DELETE
/projects/{id}/exports
删除所有导出文件
GET
/jobs/{jobId}
通用任务轮询

Effects & Keyframes

特效与关键帧

MethodPathDescription
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
MethodPath描述
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:
ModeReturns
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

Step 1: Get presigned URL

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

Step 2: Upload to presigned URL

Step 2: Upload to presigned URL

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

Step 3: Finalize

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

请求频率限制

PlanRequests/minRequests/day
Free10100
Lite301,000
Creator605,000
Agency12020,000
套餐每分钟请求数每日请求数
免费版10100
轻量版301,000
创作者版605,000
机构版12020,000