home / skills / blitzreels / agent-skills / blitzreels-video-editing

blitzreels-video-editing skill

safe

This skill helps you automate BlitzReels video editing tasks from upload to export, accelerating timeline edits, captions, overlays, and final delivery.

npx playbooks add skill blitzreels/agent-skills --skill blitzreels-video-editing

Review the files below or copy the command above to add this skill to your agents.

Files (11)

SKILL.md

10.0 KB

---
name: blitzreels-video-editing
description: Video editing workflows with BlitzReels API — upload, transcribe, timeline editing, captions, overlays, backgrounds, and export.
---

# BlitzReels Video Editing

Edit videos via the BlitzReels API: upload media, transcribe, edit timeline, apply captions, add overlays and backgrounds, then 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

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
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}/timeline/undo` | Undo last action |

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

Overview

This skill automates video editing workflows using the BlitzReels API: upload media, transcribe audio, edit the timeline, apply captions and overlays, add backgrounds, and export finished videos. It provides CLI scripts for common tasks and direct API helpers for advanced operations. Use it to build repeatable, programmatic editing pipelines or integrate video editing into larger systems.

How this skill works

The skill wraps BlitzReels endpoints with shell scripts that perform upload (URL or presigned), add media to a timeline, run transcription jobs, and poll job status until completion. It exposes timeline operations (trim, split, delete, reorder), caption presets, overlays, fill layers, effects, and an export flow that returns a downloadable URL. For advanced features, a generic API helper lets you call any endpoint directly with JSON payloads.

When to use it

Automate ingest and post-production for batches of clips
Create styled, word-level captions and animated overlays at scale
Programmatically trim, split, or reorder timeline items from other systems
Generate social-ready exports (vertical/horizontal) with consistent presets
Integrate transcription and caption workflows into content pipelines

Best practices

Set BLITZREELS_API_KEY in environment and use the provided base URL to avoid redirects
For large local files prefer the presigned two-step upload to avoid timeouts
Run transcription then use transcript mode to plan caption-based edits or recuts
Use caption presets and fill-layer presets to maintain consistent branding
Enable BLITZREELS_ALLOW_EXPENSIVE=1 when running exports or B-roll generation to avoid failures

Example use cases

Bulk import conference recordings from URLs, transcribe, cut highlights, and export shareable clips
Build a microservice that trims raw footage, applies caption style, and returns an export URL
Create short-form social videos: vertical aspect, animated captions, and background fills from templates
Automate error detection and silence removal to speed up editing of interviews and tutorials
Add motion-code snippets or motion graphics to product demo videos via direct API calls

FAQ

How do I upload a local file?

Request a presigned upload, PUT the file to the returned URL, then call finalize with the storage key.

Are exports free to run?

No. Exports and some B-roll or generation features are expensive; set BLITZREELS_ALLOW_EXPENSIVE=1 to enable them.

How do I get word-level captions?

Run the transcribe endpoint then fetch project context with mode=transcript to retrieve word-level timing.