blitzreels-carousels

Original：🇺🇸 English
Translated
4 scripts

Create TikTok/Instagram carousel projects (still slides + text overlays) via the BlitzReels API.

22installs
Sourceblitzreels/agent-skills
Added on

NPX Install

npx skill4agent add blitzreels/agent-skills blitzreels-carousels

Tags

Translated version includes tags in frontmatter
blitzreels-apitiktok-carouselsinstagram-carouselsapi-workflowsocial-media-content

SKILL.md Content

View Translation Comparison →

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.
bash
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

MethodPathPurpose
POST
/projects
Create a project (carousel fields may be ignored if not supported)
POST
/projects/{id}/media
Upload/import slide background images
POST
/projects/{id}/timeline/media
Insert images into the timeline (one segment per slide)
POST
/projects/{id}/text-overlays
Add slide text overlays (time-windowed)
GET
/projects/{id}/context?mode=timeline
Inspect timing + overlay placement
POST
/projects/{id}/export
Export slideshow 
mp4
(expensive)

Export Slideshow (MP4)

bash
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
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
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
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:
bash
# 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.