blitzreels-carousels
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseBlitzReels Carousels (TikTok + Instagram)
BlitzReels轮播图(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
本技能专注于创建静态幻灯片轮播项目:每张幻灯片通常是带有顶部文字的全屏图片。
核心思路:将轮播图建模为普通的BlitzReels项目,包含:
project_type: "carousel"- 幻灯片背景以图片媒体资源上传
- 幻灯片作为时间轴媒体项布局(每个幻灯片对应一个片段)
- 文字作为文字叠加层与每张幻灯片的时间窗口对齐
Important Limitations (Current Public API)
重要限制(当前公开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 + export.
mp4 - Safe area presets are metadata only — they don't auto-position text. You must manually set /
position_x(see Safe Area Positioning section below).position_y
Always validate what's available via OpenAPI:
https://www.blitzreels.com/api/openapi.json
- 公开的OpenAPI规范目前不支持导出单张幻灯片图片的ZIP包。请将轮播图视为幻灯片视频:时间轴上每张幻灯片对应一张图片+定时文字叠加层+导出为格式。
mp4 - 安全区域预设仅为元数据——它们不会自动定位文字。你必须手动设置/
position_x(见下方“安全区域定位”章节)。position_y
请始终通过OpenAPI验证可用功能:
https://www.blitzreels.com/api/openapi.json
Platform Presets
平台预设
TikTok (Photo Mode)
TikTok(照片模式)
- Aspect ratio: ✅
9:16 - :
safe_area_preset(metadata only — manual positioning required)tiktok_9_16
- 宽高比:✅
9:16 - :
safe_area_preset(仅为元数据——需手动定位)tiktok_9_16
Instagram Feed Carousel
Instagram动态轮播图
- Aspect ratio: ✅ (now supported as of 2026-02-12)
4:5 - :
safe_area_preset(metadata only — manual positioning required)instagram_4_5
Instagram square is also common:
- Aspect ratio: ✅
1:1 - :
safe_area_preset(metadata only — manual positioning required)instagram_1_1
- 宽高比:✅(2026年2月12日起支持)
4:5 - :
safe_area_preset(仅为元数据——需手动定位)instagram_4_5
Instagram正方形格式也很常用:
- 宽高比:✅
1:1 - :
safe_area_preset(仅为元数据——需手动定位)instagram_1_1
Carousel Project Support
轮播项目支持情况
As of 2026-02-12, the public API now supports:
- ✅ — creates a carousel-specific project
project_type: "carousel" - ✅ (JSONB) — stores platform, safe area preset, slide count, etc.
carousel_settings - ✅ — Instagram portrait format now supported
aspect_ratio: "4:5"
截至2026年2月12日,公开API现在支持:
- ✅ ——创建轮播专属项目
project_type: "carousel" - ✅ (JSONB)——存储平台、安全区域预设、幻灯片数量等信息
carousel_settings - ✅ ——支持Instagram竖版格式
aspect_ratio: "4:5"
Workflow (Manual Carousel Assembly)
工作流程(手动组装轮播图)
- Create a carousel project ()
POST /projects - Upload slide background images (with
POST /projects/{id}/mediaor presigned upload)url - Insert each image on the timeline () at
POST /projects/{id}/timeline/mediastart_seconds = slideIndex * slideDuration - Add text overlays for each slide () with matching
POST /projects/{id}/text-overlaysandstart_secondsduration_seconds - Fetch context to confirm layout ()
GET /projects/{id}/context?mode=timeline - Export an slideshow video (
mp4withPOST /projects/{id}/export)format:"mp4"
- 创建轮播项目()
POST /projects - 上传幻灯片背景图片(,使用
POST /projects/{id}/media或预签名上传)url - 在时间轴中插入每张图片(,设置
POST /projects/{id}/timeline/media)start_seconds = slideIndex * slideDuration - 为每张幻灯片添加文字叠加层(,匹配对应的
POST /projects/{id}/text-overlays和start_seconds)duration_seconds - 获取上下文以确认布局()
GET /projects/{id}/context?mode=timeline - 导出幻灯片视频(
mp4,设置POST /projects/{id}/export)format:"mp4"
Workflow (One-Call Generation)
工作流程(一键生成)
This repo includes for an experimental one-call carousel generator, but it is not currently part of the public OpenAPI spec. Prefer the manual assembly flow above.
scripts/generate.sh本仓库包含实验性的一键轮播图生成脚本,但目前不属于公开OpenAPI规范。建议优先使用上述手动组装流程。
scripts/generate.shQuickstart (Script)
快速开始(脚本)
This skill includes which creates a carousel project and inserts slide images + optional per-slide titles.
scripts/carousel.shbash
export BLITZREELS_API_KEY="br_live_xxxxx"
export BLITZREELS_ALLOW_EXPENSIVE=1 # only needed if you export a video preview本技能包含脚本,可创建轮播项目并插入幻灯片图片+可选的单张幻灯片标题。
scripts/carousel.shbash
export BLITZREELS_API_KEY="br_live_xxxxx"
export BLITZREELS_ALLOW_EXPENSIVE=1 # 仅在导出视频预览时需要TikTok: 3 slides (URLs) + titles
TikTok:3张幻灯片(URL)+ 标题
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"
--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"
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"
--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
Instagram动态:4:5比例
bash scripts/carousel.sh
--platform instagram
--aspect 4:5
--name "My IG Carousel"
--images "https://.../1.jpg|https://.../2.jpg"
--platform instagram
--aspect 4:5
--name "My IG Carousel"
--images "https://.../1.jpg|https://.../2.jpg"
undefinedbash scripts/carousel.sh
--platform instagram
--aspect 4:5
--name "My IG Carousel"
--images "https://.../1.jpg|https://.../2.jpg"
--platform instagram
--aspect 4:5
--name "My IG Carousel"
--images "https://.../1.jpg|https://.../2.jpg"
undefinedAPI Endpoints Used
使用的API端点
| Method | Path | Purpose |
|---|---|---|
| POST | | Create a project (carousel fields may be ignored if not supported) |
| POST | | Upload/import slide background images |
| POST | | Insert images into the timeline (one segment per slide) |
| POST | | Add slide text overlays (time-windowed) |
| GET | | Inspect timing + overlay placement |
| POST | | Export slideshow |
| 请求方法 | 路径 | 用途 |
|---|---|---|
| POST | | 创建项目(如果不支持,轮播相关字段可能会被忽略) |
| POST | | 上传/导入幻灯片背景图片 |
| POST | | 在时间轴中插入图片(每张幻灯片对应一个片段) |
| POST | | 添加幻灯片文字叠加层(按时间窗口设置) |
| GET | | 检查时间安排+叠加层位置 |
| POST | | 导出幻灯片 |
Export Slideshow (MP4)
导出幻灯片视频(MP4)
bash
export BLITZREELS_ALLOW_EXPENSIVE=1bash
export BLITZREELS_ALLOW_EXPENSIVE=1Slideshow video
幻灯片视频
bash scripts/blitzreels.sh POST "/projects/${PROJECT_ID}/export" '{"resolution":"1080p","format":"mp4"}'
undefinedbash scripts/blitzreels.sh POST "/projects/${PROJECT_ID}/export" '{"resolution":"1080p","format":"mp4"}'
undefinedMarketing Slide Structure
营销幻灯片结构
Carousels perform best when structured for social media consumption:
3-Slide Formula (TikTok):
- Hook (Slide 1): Attention-grabbing statement or question (e.g., "3 Mistakes Killing Your Startup")
- Value (Slide 2): Core insight or key points
- CTA (Slide 3): Clear next step (e.g., "Save This Post" / "Follow for More")
5-Slide Formula (Instagram Feed):
- Hook: Compelling title/question 2-4. Key Points: 3 actionable insights (one per slide)
- 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
轮播图在社交媒体上的表现最佳,需遵循以下结构:
TikTok 3幻灯片公式:
- 钩子(第1张):吸引注意力的陈述或问题(例如:“3个拖垮你创业公司的错误”)
- 价值(第2张):核心见解或关键点
- 行动号召(第3张):明确的下一步操作(例如:“保存此帖子”/“关注获取更多内容”)
Instagram动态5幻灯片公式:
- 钩子:引人注目的标题/问题 2-4. 关键点:3个可执行的见解(每张幻灯片一个)
- 行动号召+回顾:总结+关注/保存/评论提示
模板模式:
- 教育类:“如何[做某事]”→步骤1-3→回顾
- 清单类:“[N]种方法来[做某事]”→要点1→要点2→要点3→总结
- 故事类:问题→困境→解决方案→结果→行动号召
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
字符与行数限制:
- 每行最多40个字符(符合手机拇指滚动时的可读性)
- 每张幻灯片最多4行(避免视觉杂乱)
- 长文本拆分为多张幻灯片,不要强行堆砌
对比度与易读性:
- 最低WCAG AA标准:4.5:1的对比度(文字与背景)
- 始终启用文字描边:白色文字配6px黑色描边(反之亦然)
- 使用网页对比度检查工具:WebAIM Contrast Checker
字体大小:
- 标题:64-80px(钩子幻灯片、行动号召)
- 正文:48-64px(关键点)
- 最小值:48px(更小的字体在手机上可能难以辨认)
排版最佳实践:
- 使用粗体字(700+字重)提升手机可读性
- 轮播图文字居中对齐(更易浏览)
- 使用无衬线字体(Inter、Montserrat、Poppins)而非衬线字体
Safe Area Positioning (Platform-Specific)
安全区域定位(平台专属)
The API supports , but you must manually position text to respect UI danger zones.
carousel_settings.safe_area_presetAPI支持,但你必须手动定位文字以避开UI危险区域。
carousel_settings.safe_area_presetTikTok Photo Mode (9:16
)
9:16TikTok照片模式(9:16
)
9:16Danger 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: (hook slides)
position_x: 0.5, position_y: 0.18 - Middle-left safe: (body text, avoids right UI)
position_x: 0.35, position_y: 0.5 - Bottom safe: (max safe before captions)
position_x: 0.5, position_y: 0.65
TikTok Best Practices:
- Always offset text slightly left (instead of
position_x: 0.45) to avoid right-side buttons0.5 - Use preset for simplicity
position: "top" - Test with TikTok watermark/UI overlay in mind
危险区域(1080x1920分辨率下的绝对像素):
- 右侧边缘:避开最右侧120px(分享/点赞/评论按钮)
- 底部:避开底部450px(用户名、标题叠加层、声音控件)
- 顶部:避开顶部80px(状态栏、返回按钮)
安全定位(归一化坐标):
- 顶部中央安全区:(钩子幻灯片)
position_x: 0.5, position_y: 0.18 - 中部左侧安全区:(正文,避开右侧UI)
position_x: 0.35, position_y: 0.5 - 底部安全区:(标题前的最大安全位置)
position_x: 0.5, position_y: 0.65
TikTok最佳实践:
- 文字稍微向左偏移(而非
position_x: 0.45)以避开右侧按钮0.5 - 为简化操作,使用预设
position: "top" - 考虑TikTok水印/UI叠加层进行测试
Instagram Feed Carousel (4:5
or 1:1
)
4:51:1Instagram动态轮播图(4:5
或1:1
)
4:51:1Danger 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: (titles)
position_x: 0.5, position_y: 0.15 - Middle-center safe: (body text)
position_x: 0.5, position_y: 0.45 - Bottom safe (max): (before caption zone)
position_x: 0.5, position_y: 0.6
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)
危险区域(4:5比例下1080x1350分辨率的绝对像素):
- 底部:避开底部420px(用户名、标题预览、操作按钮)
- 边缘:文字与所有边缘保持80px距离(安全边距)
安全定位(归一化坐标):
- 顶部中央安全区:(标题)
position_x: 0.5, position_y: 0.15 - 中部中央安全区:(正文)
position_x: 0.5, position_y: 0.45 - 底部最大安全区:(标题区域之前)
position_x: 0.5, position_y: 0.6
Instagram最佳实践:
- 所有文字居中对齐(Instagram动态是对称的)
- 所有幻灯片使用一致的垂直定位(例如始终设置)
position_y: 0.18 - 保留足够的底部边距(用户习惯在下方查看标题)
Square Format (1:1
)
1:1正方形格式(1:1
)
1:1Danger 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
危险区域(1080x1080分辨率的绝对像素):
- 底部:避开底部380px(标题、个人资料链接)
- 边缘:所有边距80px
安全定位:
- 顶部中央:
position_x: 0.5, position_y: 0.15 - 中部中央:
position_x: 0.5, position_y: 0.5
Text Overlay Mandate (CRITICAL)
文字叠加层要求(至关重要)
ALWAYS use for carousel text.
POST /projects/{id}/text-overlaysNEVER 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
}
}'轮播图文字必须始终使用添加。
POST /projects/{id}/text-overlays切勿使用动态图形或动态代码添加幻灯片文字——这些工具适用于:
- 动画下三分之一字幕(视频编辑)
- 动态图表/图形
- 复杂的多层合成
轮播图使用文字叠加层的原因:
- 针对静态文字渲染优化
- 直接控制定位、描边、对齐方式
- 无不必要的动画开销
- 与单张幻灯片时间模型一致
API调用示例:
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)
示例1:TikTok创业主题轮播图(3张幻灯片)
Topic: "3 Mistakes Killing Your Startup"
Slide 1 (Hook):
- Text: "3 Mistakes Killing\nYour Startup"
- Duration: 3s
- Position: (top-left-of-center)
position_x: 0.45, position_y: 0.18 - 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"主题:“3个拖垮你创业公司的错误”
第1张(钩子):
- 文字:“3个拖垮你\n创业公司的错误”
- 时长:3秒
- 位置:(中央偏左上)
position_x: 0.45, position_y: 0.18 - 样式:72px、粗体、白色文字、6px黑色描边
第2张(价值):
- 文字:“1. 无用户基础就开发\n2. 忽视数据指标\n3. 完美主义”
- 时长:3秒
- 位置:
position_x: 0.35, position_y: 0.5 - 样式:56px、粗体
第3张(行动号召):
- 文字:“↓ 保存以备后用\n关注获取更多技巧”
- 时长:3秒
- 位置:
position_x: 0.45, position_y: 0.18 - 样式:64px、粗体
脚本:
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个拖垮你\n创业公司的错误|1. 无用户基础就开发\n2. 忽视数据指标\n3. 完美主义|↓ 保存以备后用\n关注获取更多技巧"Example 2: Instagram Educational Carousel (5 Slides)
示例2:Instagram教育主题轮播图(5张幻灯片)
Topic: "How Photosynthesis Works"
Slide 1 (Hook):
- Text: "How Photosynthesis\nWorks (Explained)"
- Position: (top-center)
position_x: 0.5, position_y: 0.15
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!"主题:“光合作用的原理”
第1张(钩子):
- 文字:“光合作用的\n原理(详解)”
- 位置:(顶部中央)
position_x: 0.5, position_y: 0.15
第2-4张(步骤):
- 第2张:“步骤1:吸收光能\n叶绿体捕获阳光”
- 第3张:“步骤2:分解水\nH2O分解为H + O2”
- 第4张:“步骤3:生成糖类\nCO2 + H → 葡萄糖”
第5张(回顾):
- 文字:“光能 → 水 → 糖类\n保存用于生物课!”
脚本:
bash
bash scripts/instagram.sh \
--aspect 4:5 \
--name "Photosynthesis Explained" \
--slide-duration 3 \
--images "url1|url2|url3|url4|url5" \
--titles "光合作用的\n原理(详解)|步骤1:吸收光能\n叶绿体捕获阳光|步骤2:分解水\nH2O分解为H + O2|步骤3:生成糖类\nCO2 + H → 葡萄糖|光能 → 水 → 糖类\n保存用于生物课!"API Validation & Drift Prevention
API验证与漂移预防
Before starting carousel work, validate that required endpoints exist:
bash
undefined开始轮播图工作前,请验证所需端点是否存在:
bash
undefinedValidate API endpoints
验证API端点
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 availabilitybash scripts/validate-api.sh
**必需端点:**
- `POST /projects`(创建轮播项目)
- `POST /projects/{id}/media`(上传幻灯片背景)
- `POST /projects/{id}/timeline/media`(幻灯片排序)
- `POST /projects/{id}/text-overlays`(文字定位)
- `GET /projects/{id}/context`(布局检查)
- `POST /projects/{id}/export`(导出mp4幻灯片视频)
**OpenAPI规范参考:**
- 在线规范:`https://www.blitzreels.com/api/openapi.json`
- 假设端点可用前,请始终检查规范Safe Area Guidance (Practical)
安全区域指南(实用版)
The API supports , but the preset is metadata today.
To "respect safe areas" in practice:
carousel_settings.safe_area_preset- Keep critical text away from the extreme edges.
- On TikTok, avoid the right side (UI buttons) and the bottom (captions/CTA overlays).
- Prefer using or
position: "top"for text overlays, or set normalizedposition: "center"/position_x(0..1) conservatively.position_y
API支持,但目前该预设仅为元数据。
实际操作中要“遵守安全区域”:
carousel_settings.safe_area_preset- 关键文字远离极端边缘。
- 在TikTok上,避开右侧(UI按钮)和底部(标题/行动号召叠加层)。
- 优先为文字叠加层设置或
position: "top",或保守设置归一化position: "center"/position_x(0..1)。position_y