BlitzReels Carousels (TikTok + Instagram)

This skill focuses on creating still-slide carousel projects: each slide is typically a full-screen image with text on top.

Key idea: model a carousel as a normal BlitzReels project, with:

• project_type: "carousel"
• Slide backgrounds uploaded as image media assets
• Slides laid out as timeline media items (one per slide segment)
• Text placed as text overlays aligned to each slide’s time window

Important Limitations (Current Public API)

• The public OpenAPI spec currently does not expose a ZIP export of per-slide images. Treat carousels as a slideshow video: image-per-slide on the timeline + timed text overlays + mp4 export.
• Safe area presets are metadata only — they don't auto-position text. You must manually set position_x/position_y (see Safe Area Positioning section below).

Always validate what's available via OpenAPI:

• https://www.blitzreels.com/api/openapi.json

Platform Presets

TikTok (Photo Mode)

• Aspect ratio: 9:16 ✅
• safe_area_preset: tiktok_9_16 (metadata only — manual positioning required)

Instagram Feed Carousel

• Aspect ratio: 4:5 ✅ (now supported as of 2026-02-12)
• safe_area_preset: instagram_4_5 (metadata only — manual positioning required)

Instagram square is also common:

• Aspect ratio: 1:1 ✅
• safe_area_preset: instagram_1_1 (metadata only — manual positioning required)

Carousel Project Support

As of 2026-02-12, the public API now supports:

• ✅ project_type: "carousel" — creates a carousel-specific project
• ✅ carousel_settings (JSONB) — stores platform, safe area preset, slide count, etc.
• ✅ aspect_ratio: "4:5" — Instagram portrait format now supported

Workflow (Manual Carousel Assembly)

1. Create a carousel project (POST /projects)
2. Upload slide background images (POST /projects/{id}/media with url or presigned upload)
3. Insert each image on the timeline (POST /projects/{id}/timeline/media) at start_seconds = slideIndex * slideDuration
4. Add text overlays for each slide (POST /projects/{id}/text-overlays) with matching start_seconds and duration_seconds
5. Fetch context to confirm layout (GET /projects/{id}/context?mode=timeline)
6. Export an mp4 slideshow video (POST /projects/{id}/export with format:"mp4")

Workflow (One-Call Generation)

This repo includes scripts/generate.sh for an experimental one-call carousel generator, but it is not currently part of the public OpenAPI spec. Prefer the manual assembly flow above.

Quickstart (Script)

This skill includes scripts/carousel.sh which creates a carousel project and inserts slide images + optional per-slide titles.

export BLITZREELS_API_KEY="br_live_xxxxx"
export BLITZREELS_ALLOW_EXPENSIVE=1  # only needed if you export a video preview

# TikTok: 3 slides (URLs) + titles
bash scripts/carousel.sh \
  --platform tiktok \
  --name "My TikTok Carousel" \
  --slide-duration 3 \
  --images "https://.../1.jpg|https://.../2.jpg|https://.../3.jpg" \
  --titles "Hook line|Main point|CTA"

# Instagram feed: 4:5
bash scripts/carousel.sh \
  --platform instagram \
  --aspect 4:5 \
  --name "My IG Carousel" \
  --images "https://.../1.jpg|https://.../2.jpg"

API Endpoints Used

Export Slideshow (MP4)

export BLITZREELS_ALLOW_EXPENSIVE=1

# Slideshow video
bash scripts/blitzreels.sh POST "/projects/${PROJECT_ID}/export" '{"resolution":"1080p","format":"mp4"}'

Marketing Slide Structure

Carousels perform best when structured for social media consumption:

3-Slide Formula (TikTok):

1. Hook (Slide 1): Attention-grabbing statement or question (e.g., "3 Mistakes Killing Your Startup")
2. Value (Slide 2): Core insight or key points
3. CTA (Slide 3): Clear next step (e.g., "Save This Post" / "Follow for More")

5-Slide Formula (Instagram Feed):

1. Hook: Compelling title/question 2-4. Key Points: 3 actionable insights (one per slide)
2. CTA + Recap: Summary + follow/save/comment prompt

Template Patterns:

• Educational: "How to [X]" → Steps 1-3 → Recap
• Listicle: "[N] Ways to [X]" → Point 1 → Point 2 → Point 3 → Summary
• Storytelling: Problem → Struggle → Solution → Result → CTA

Readability Rules (CRITICAL)

Character & Line Limits:

• Max 40 chars/line (mobile readable at thumb-scrolling speed)
• Max 4 lines/slide (avoid visual clutter)
• Break long text into multiple slides rather than cramming

Contrast & Legibility:

• WCAG AA minimum: 4.5:1 contrast ratio (text vs background)
• Always enable text stroke: 6px black stroke on white text (or vice versa)
• Use web contrast checkers: WebAIM Contrast Checker

Font Sizing:

• Titles: 64-80px (hook slides, CTAs)
• Body text: 48-64px (key points)
• Minimum: 48px (anything smaller risks illegibility on mobile)

Typography Best Practices:

• Bold fonts (700+ weight) for better mobile readability
• Center-aligned text for carousels (easier to scan)
• Sans-serif fonts (Inter, Montserrat, Poppins) over serif

Safe Area Positioning (Platform-Specific)

The API supports carousel_settings.safe_area_preset, but you must manually position text to respect UI danger zones.

TikTok Photo Mode (9:16)

Danger Zones (Absolute Pixels @ 1080x1920):

• Right edge: Avoid rightmost 120px (share/like/comment buttons)
• Bottom: Avoid bottom 450px (username, caption overlay, sound)
• Top: Avoid top 80px (status bar, back button)

Safe Positioning (Normalized Coords):

• Top-center safe: position_x: 0.5, position_y: 0.18 (hook slides)
• Middle-left safe: position_x: 0.35, position_y: 0.5 (body text, avoids right UI)
• Bottom safe: position_x: 0.5, position_y: 0.65 (max safe before captions)

TikTok Best Practices:

• Always offset text slightly left (position_x: 0.45 instead of 0.5) to avoid right-side buttons
• Use position: "top" preset for simplicity
• Test with TikTok watermark/UI overlay in mind

Instagram Feed Carousel (4:5 or 1:1)

Danger Zones (Absolute Pixels @ 1080x1350 for 4:5):

• Bottom: Avoid bottom 420px (username, caption preview, action buttons)
• Edges: Keep text 80px from all edges (safe margins)

Safe Positioning (Normalized Coords):

• Top-center safe: position_x: 0.5, position_y: 0.15 (titles)
• Middle-center safe: position_x: 0.5, position_y: 0.45 (body text)
• Bottom safe (max): position_x: 0.5, position_y: 0.6 (before caption zone)

Instagram Best Practices:

• Center all text (Instagram's feed is symmetrical)
• Use consistent vertical positioning across all slides (e.g., always position_y: 0.18)
• Leave generous bottom margin (users expect captions below)

Square Format (1:1)

Danger Zones (Absolute Pixels @ 1080x1080):

• Bottom: Avoid bottom 380px (captions, profile link)
• Edges: 80px margins on all sides

Safe Positioning:

• Top-center: position_x: 0.5, position_y: 0.15
• Middle-center: position_x: 0.5, position_y: 0.5

Text Overlay Mandate (CRITICAL)

ALWAYS use POST /projects/{id}/text-overlays for carousel text.

NEVER use motion graphics or motion code for slide text — those tools are for:

• Animated lower thirds (video editing)
• Dynamic charts/graphs
• Complex multi-layer compositions

Why text overlays for carousels:

• Optimized for static text rendering
• Direct control over positioning, stroke, alignment
• No unnecessary animation overhead
• Consistent with per-slide timing model

API Call Pattern:

bash scripts/blitzreels.sh POST "/projects/${PROJECT_ID}/text-overlays" '{
  "text": "Your slide text here\nMax 40 chars/line",
  "start_seconds": 0,
  "duration_seconds": 3,
  "position_x": 0.5,
  "position_y": 0.18,
  "style": {
    "font_size": 64,
    "font_weight": "700",
    "text_align": "center",
    "color": "#ffffff",
    "text_stroke_enabled": true,
    "text_stroke_color": "#000000",
    "text_stroke_width_px": 6
  }
}'

Complete Examples

Example 1: TikTok Entrepreneurship Carousel (3 Slides)

Topic: "3 Mistakes Killing Your Startup"

Slide 1 (Hook):

• Text: "3 Mistakes Killing\nYour Startup"
• Duration: 3s
• Position: position_x: 0.45, position_y: 0.18 (top-left-of-center)
• Style: 72px, bold, white text, 6px black stroke

Slide 2 (Value):

• Text: "1. Building without users\n2. Ignoring metrics\n3. Perfectionism"
• Duration: 3s
• Position: position_x: 0.35, position_y: 0.5
• Style: 56px, bold

Slide 3 (CTA):

• Text: "Save this for later ↓\nFollow for more tips"
• Duration: 3s
• Position: position_x: 0.45, position_y: 0.18
• Style: 64px, bold

Script:

bash scripts/tiktok.sh \
  --name "Startup Mistakes Carousel" \
  --slide-duration 3 \
  --images "https://example.com/slide1.jpg|https://example.com/slide2.jpg|https://example.com/slide3.jpg" \
  --titles "3 Mistakes Killing\nYour Startup|1. Building without users\n2. Ignoring metrics\n3. Perfectionism|Save this for later ↓\nFollow for more tips"

Example 2: Instagram Educational Carousel (5 Slides)

Topic: "How Photosynthesis Works"

Slide 1 (Hook):

• Text: "How Photosynthesis\nWorks (Explained)"
• Position: position_x: 0.5, position_y: 0.15 (top-center)

Slides 2-4 (Steps):

• Slide 2: "Step 1: Light Absorption\nChloroplasts capture sunlight"
• Slide 3: "Step 2: Water Splitting\nH2O breaks into H + O2"
• Slide 4: "Step 3: Sugar Formation\nCO2 + H → Glucose"

Slide 5 (Recap):

• Text: "Light → Water → Sugar\nSave for biology class!"

Script:

bash scripts/instagram.sh \
  --aspect 4:5 \
  --name "Photosynthesis Explained" \
  --slide-duration 3 \
  --images "url1|url2|url3|url4|url5" \
  --titles "How Photosynthesis\nWorks (Explained)|Step 1: Light Absorption\nChloroplasts capture sunlight|Step 2: Water Splitting\nH2O breaks into H + O2|Step 3: Sugar Formation\nCO2 + H → Glucose|Light → Water → Sugar\nSave for biology class!"

API Validation & Drift Prevention

Before starting carousel work, validate that required endpoints exist:

# Validate API endpoints
bash scripts/validate-api.sh

Required Endpoints:

• POST /projects (carousel project creation)
• POST /projects/{id}/media (slide background upload)
• POST /projects/{id}/timeline/media (slide sequencing)
• POST /projects/{id}/text-overlays (text placement)
• GET /projects/{id}/context (layout inspection)
• POST /projects/{id}/export (mp4 slideshow export)

OpenAPI Spec Reference:

• Live spec: https://www.blitzreels.com/api/openapi.json
• Always check spec before assuming endpoint availability

Safe Area Guidance (Practical)

The API supports carousel_settings.safe_area_preset, but the preset is metadata today. To "respect safe areas" in practice:

• Keep critical text away from the extreme edges.
• On TikTok, avoid the right side (UI buttons) and the bottom (captions/CTA overlays).
• Prefer using position: "top" or position: "center" for text overlays, or set normalized position_x/position_y (0..1) conservatively.