blitzreels-motion-graphics

BlitzReels Motion Graphics (Playground API)

Create and edit motion graphics compositions via the Playground API. Build animated scenes with text, shapes, images, video, charts, code blocks, and more.

Quick Start

# List available presets
bash scripts/playground.sh list-presets PROJECT_ID

# Create a composition from a JSON file
bash scripts/playground.sh create PROJECT_ID spec.json

# Create from inline JSON
bash scripts/playground.sh create PROJECT_ID '{"name":"Title Card","fps":30,"width":1920,"height":1080,"durationInFrames":90,"mode":"elements","elements":[{"id":"title","type":"text","content":"Hello World","style":{"fontSize":96,"fontWeight":"bold","color":"#fff","display":"flex","justifyContent":"center","alignItems":"center"}}]}'

Get, update, delete

bash scripts/playground.sh get PROJECT_ID COMP_ID bash scripts/playground.sh update PROJECT_ID COMP_ID updated-spec.json bash scripts/playground.sh delete PROJECT_ID COMP_ID

Export the project

bash scripts/playground.sh export PROJECT_ID --resolution 1080p

## Workflow

1. **Create a project** (or use an existing one)
2. **Browse presets** — `playground.sh list-presets` for inspiration
3. **Build composition spec** — JSON describing canvas, elements, and animations
4. **Create composition** — `playground.sh create`
5. **Iterate** — Update elements, adjust timing, add animations
6. **Export** — `playground.sh export`

## Scripts

### `scripts/playground.sh`
Purpose-built CRUD wrapper for playground compositions.

| Command | Usage |
|---------|-------|
| `list-presets` | `playground.sh list-presets <projectId>` |
| `list` | `playground.sh list <projectId>` |
| `create` | `playground.sh create <projectId> <spec.json\|-\|JSON>` |
| `get` | `playground.sh get <projectId> <compositionId>` |
| `update` | `playground.sh update <projectId> <compositionId> <spec>` |
| `delete` | `playground.sh delete <projectId> <compositionId>` |
| `export` | `playground.sh export <projectId> [--resolution 1080p]` |

Run `bash scripts/playground.sh --help` for full usage.

### `scripts/blitzreels.sh`
Generic API helper for ad-hoc calls.

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `BLITZREELS_API_KEY` | Yes | API key |
| `BLITZREELS_API_BASE_URL` | No | Override base URL |
| `BLITZREELS_ALLOW_EXPENSIVE` | No | Set to `1` for export calls via blitzreels.sh |

## API Endpoints

### Playground Compositions
| Method | Path | Description |
|--------|------|-------------|
| GET | `/projects/{id}/playground/presets` | List preset templates |
| GET | `/projects/{id}/playground/compositions` | List compositions |
| POST | `/projects/{id}/playground/compositions` | Create composition |
| GET | `/projects/{id}/playground/compositions/{cid}` | Get composition |
| PATCH | `/projects/{id}/playground/compositions/{cid}` | Update composition |
| DELETE | `/projects/{id}/playground/compositions/{cid}` | Delete composition |

### Element-Level Operations
| Method | Path | Description |
|--------|------|-------------|
| PATCH | `/projects/{id}/playground/compositions/{cid}/elements/{eid}` | Update single element |
| DELETE | `/projects/{id}/playground/compositions/{cid}/elements/{eid}` | Delete element |

### Project Operations
| Method | Path | Description |
|--------|------|-------------|
| POST | `/projects` | Create project |
| POST | `/projects/{id}/export` | Start export (expensive) |
| GET | `/exports/{export_id}` | Get export status + download URL |

## Composition Spec

The composition JSON spec defines the canvas, elements, and animations. See `references/composition-spec.md` for the full schema.

### Minimal Example
```json
{
  "name": "Title Card",
  "fps": 30,
  "width": 1920,
  "height": 1080,
  "durationInFrames": 150,
  "background": "#1a1a2e",
  "mode": "elements",
  "elements": [
    {
      "id": "title",
      "type": "text",
      "content": "Hello World",
      "from": 0,
      "durationInFrames": 150,
      "style": {
        "fontSize": 96,
        "fontWeight": "bold",
        "color": "#ffffff",
        "opacity": {
          "keyframes": [
            { "frame": 0, "value": 0 },
            { "frame": 30, "value": 1 }
          ]
        }
      }
    }
  ]
}

Element Types

Type	Description
text	Text with typewriter, highlight effects
shape	Rectangle, circle, ellipse, line, arrow, polygon, star
image	Static image with optional Ken Burns effect
video	Video clip with volume, loop, playback control
audio	Audio track
chart	Bar, pie, line, area, donut charts with animated reveal
code	Syntax-highlighted code with line-by-line reveal
svg	SVG with path draw/morph animations
group	Container for child elements (parallel or series)
lottie	Lottie animation from JSON or URL

Animation Options

• Static values: "opacity": 1
• Keyframes: Frame-by-frame with easing
• Spring physics: smooth, snappy, bouncy, heavy, gentle presets
• Easing: linear, easeIn, easeOut, easeInOut, elastic, bounce, bezier

Scene Transitions (scenes mode)

fade, slide, wipe, flip, clockWipe — with directional variants.

Timeline & Overlay Editing

For editing existing video projects (not playground compositions), use these endpoints:

Method	Path	Description
GET	/projects/{id}/context?mode=timeline	Get project timeline
POST	/projects/{id}/overlays	Add text/image overlay
PATCH	/projects/{id}/overlays/{oid}	Update overlay
DELETE	/projects/{id}/overlays/{oid}	Remove overlay
POST	/projects/{id}/captions	Add/update captions
PATCH	/projects/{id}/captions/style	Update caption style

References

• references/composition-spec.md — Full composition JSON schema, element types, animation format, spring presets, transitions

Notes

• Use https://www.blitzreels.com/api/v1 as your base URL. https://blitzreels.com redirects to www, and some HTTP clients drop the Authorization header on redirects.
• When animating, prefer the smallest number of keyframes that communicates the motion (reduces jitter).
• Full OpenAPI spec: https://www.blitzreels.com/api/openapi.json

Rate Limits

Plan	Requests/min
Free	10
Creator	30
Pro	60
Agency	120