Video editing workflows with BlitzReels API — upload, transcribe, timeline editing, captions, overlays, backgrounds, export, and source-view ROI-aware reframing for stronger clipping flows.
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.
# 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
POST /projects {"name":"...", "aspect_ratio":"9:16"}editor.sh upload-url (URL import) or 2-step presigned uploadeditor.sh add-media places media on the timelineeditor.sh transcribe generates word-level captionseditor.sh context to see timeline stateeditor.sh captions <presetId> for styled subtitleseditor.sh export renders final video with download URLscripts/editor.shSubcommand 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.shGeneric 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]
| 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 |
| 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 | 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 | 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 | 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 | 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 | 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 | Description |
|---|---|---|
| POST | /projects/{id}/fill-layers | Add fill layer |
| PATCH | /projects/{id}/fill-layers/{lid} | Update fill layer |
| 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 | 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 | Description |
|---|---|---|
| POST | /workspace/media/assets/{assetId}/reframe-plan/preview | Generate a reframe plan plus preview stills before apply |
| 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 | 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 |
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
bash scripts/editor.sh upload-url PROJECT_ID "https://example.com/video.mp4"
# 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')\"}"
references/caption-styles.mdreferences/fill-layers.mdreferences/clipping.md — Long-form to short workflow, podcast QA loop, preview/repair endpointsreferences/caption-styles.md — All 30+ presets, CaptionStyleSettings schema, animationsreferences/overlays.md — Text overlays, motion code, motion graphics schemasreferences/fill-layers.md — 38+ background presets, FillLayerSettings schemareferences/timeline-ops.md — Timeline endpoints, AI features, keyframes, effectsreferences/export-settings.md — Export params, codecs, polling patternexamples/edit-uploaded-video.md — Full upload→edit→export walkthroughexamples/enhance-with-overlays.md — Adding graphics to existing projecthttps://www.blitzreels.com/api/v1 as base URL (avoid redirect from non-www)BLITZREELS_ALLOW_EXPENSIVE=1editor.sh export sets this automatically; blitzreels.sh requires explicit opt-inhttps://www.blitzreels.com/api/openapi.json| Plan | Requests/min | Requests/day |
|---|---|---|
| Free | 10 | 100 |
| Lite | 30 | 1,000 |
| Creator | 60 | 5,000 |
| Agency | 120 | 20,000 |