blitzreels-video-editing

What this skill does

# 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. Preview and render calls can be slow; request only the timestamps you need.

Important: do not infer endpoint names from dashboard URLs or likely nouns. Public API coverage is narrower than the product UI. Search this skill, `llms-full.txt`, and `references/api-dogfood-caveats.md` before trying a new path.

## 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/copy captions** — `editor.sh captions <presetId>` for styled subtitles, or copy settings with `GET/PATCH /projects/{id}/captions/style`
8. **Add overlays** — canonical editable overlays via `/content-items` (`kind: "overlay"`), plus motion code when explicitly needed
9. **Add background** — fill layers (gradients, cinematic, patterns)
10. **Export** — `editor.sh export` renders final video with download URL

After any correction or style copy, verify with `editor.sh context PROJECT_ID full` and preview frames before export. Caption writes can change chunking; the transcript may be correct while the rendered caption blocks need manual split/repair.

## Creative Placement Guidance

When the user gives natural-language layout direction, do not turn every word into a new API argument. Interpret the request, state the interpretation, and implement it using the current documented API fields. For example, "big text that fits in two lines and is as wide as possible inside the safe zone" should become a concrete editable text spec/style and placement choice, not a new REST parameter.

Tell the user which safe zone you are targeting whenever important text, logos, product shots, or CTAs are involved. Safe zones are platform placement constraints, not API filters. If the target platform is missing, use a conservative universal short-form safe zone and mention that assumption. Keep critical content clear of top navigation chrome, bottom caption/description areas, and right-side action rails.

For B-roll and logos, prioritize asset quality before placement:

- Use the highest-quality available asset; avoid thumbnails, favicons, low-bitrate screenshots, and watermarked previews.
- Prefer source dimensions at least twice the final canvas dimensions for logos and static images.
- Be cautious with SVG logos. SVGs may rasterize or simplify differently in preview/export paths; if the logo appears jagged, low-poly, clipped, or inconsistent, convert it to a high-resolution PNG/WebP and verify again.
- Avoid stretching assets across mismatched aspect ratios unless the user explicitly asks for that effect.

Always verify visual placement with preview frames or snapshots after edits that affect text, B-roll, logos, safe zones, or overlays.

## 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 |
| `words` | `<projectId> [limit] [offset]` | List caption words when endpoint is healthy |
| `transcript-corrections` | `<projectId> <assetId> <JSON>` | Apply transcript replacements |
| `list-assets` | `[limit] [offset] [assetType]` | List workspace media assets |
| `get-asset` | `<assetId>` | Get workspace media asset detail |
| `workspace-settings` | `[JSON_PATCH]` | Get or patch workspace settings |
| `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 |
| DELETE | `/projects/{id}` | Delete project |
| GET | `/projects` | List projects |
| PATCH | `/projects/{id}` | Update project metadata (`name`, `description`) |

`PATCH /projects/{id}` is metadata-only. Use `/projects/{id}/settings` and `/projects/{id}/captions/style` for editor/render settings.

### Media

| Method | Path | Description |
|--------|------|-------------|
| POST | `/projects/{id}/media` | Import media from URL |
| POST | `/workspace/media/upload/init` | Create direct upload URL |
| POST | `/workspace/media/upload/finalize` | Finalize direct upload |
| GET | `/workspace/media/assets` | List workspace media assets (`limit` max 100) |
| GET | `/workspace/media/assets/{assetId}` | Get media asset details and signed file URL |

Use `/workspace/media/assets/{assetId}` for asset lookup. Do not try `/assets/{id}`, `/media/{id}`, `/uploads/{id}`, `/videos/{id}`, `/source-videos/{id}`, or `/long-videos/{id}`.

### 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 |
| GET | `/projects/{id}/transcript/segments` | Get transcript segments |
| POST | `/projects/{id}/transcript/corrections` | Bulk transcript corrections |
| POST | `/projects/{id}/transcribe` | Re-transcribe media by media asset |

Transcript corrections accept single-token `replacements` and same-token-count `phrase_replacements`. For `"Cloud Code" -> "Claude Code"`, use `phrase_replacements` with `from_words: ["Cloud", "Code"]` and `to_words: ["Claude", "Code"]`. Token-count-changing edits such as `"de Expo" -> "d'Expo"` are not supported by t