BlitzReels Video Editing
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.
Quick Start
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
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
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
Scripts
scripts/editor.sh
Subcommand wrapper for common editing operations.
Command
Usage
Description
upload-url
[name]
Upload media from URL
transcribe
Transcribe + poll until done
context
[mode]
Get project context (default: timeline)
timeline-at
Get items at timestamp
trim
Trim item edges
split
Split item at time
delete-item
Delete timeline item
add-media
[startSec]
Add media to timeline
add-broll
Add B-roll clip
captions
Apply caption preset
export
[--resolution R]
Export + poll + download URL
Run
bash scripts/editor.sh --help
for full usage.
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
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
API Endpoint Index
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
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
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
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
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
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
Backgrounds
Method
Path
Description
POST
/projects/{id}/fill-layers
Add fill layer
PATCH
/projects/{id}/fill-layers/{lid}
Update fill layer
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
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
Clipping / Reframe Preview
Method
Path
Description
POST
/workspace/media/assets/{assetId}/reframe-plan/preview
Generate a reframe plan plus preview stills before apply
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
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
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
scripts/editor.sh context PROJECT_ID timeline
bash
scripts/editor.sh context PROJECT_ID full
Upload Modes
URL Import (Simpler)
bash
scripts/editor.sh upload-url PROJECT_ID
"https://example.com/video.mp4"
Presigned 2-Step (For Local Files)
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'
- )
- \"
- }"
- 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)
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
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
Rate Limits
Plan
Requests/min
Requests/day
Free
10
100
Lite
30
1,000
Creator
60
5,000
Agency
120
20,000