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

bash

# 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 <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

Scripts

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.

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]

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

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

Upload Modes

URL Import (Simpler)

bash

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

Presigned 2-Step (For Local Files)

bash

# 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

blitzreels-video-editing

NPX Install

Tags

SKILL.md Content

BlitzReels Video Editing

Quick Start

Primary Workflow

Scripts

`scripts/editor.sh`

`scripts/blitzreels.sh`

Environment Variables

API Endpoint Index

Projects

Media

Transcription

Captions

Timeline Editing

Overlays — Text, Motion Code, Motion Graphics

Backgrounds

Context & State

Media View Repair

Clipping / Reframe Preview

Export & Jobs

Effects & Keyframes

Context Modes

Upload Modes

URL Import (Simpler)

Presigned 2-Step (For Local Files)

Quick Reference

References

Safety & Notes

Rate Limits