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

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

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