dvcrn/tiktok-carousel-creator

TikTok Carousel Creator (Pexels + FFmpeg + PostBridge)

Custom implementation for BerkahKarya - Creates TikTok carousels with professional text overlays.

Architecture

Flow:

Topic Research → Pexels Image Search → FFmpeg Text Overlay → PostBridge Upload → TikTok Carousel

Stack:

• Image Search: Pexels API (high-quality stock photos/videos)
• Text Overlay: FFmpeg (professional text rendering)
• Upload: PostBridge API (multi-platform posting)
• Format: TikTok Carousel 1080×1920px (9:16 vertical)

---

Prerequisites

1. Pexels API Key

Get FREE API key at: https://www.pexels.com/api/

Set environment variable:

export PEXELS_API_KEY="your_pexels_api_key_here"

Important: You need this key to search images. Without it, the script will fail.

2. PostBridge API Key

Already configured in PostBridge Client:

export POST_BRIDGE_API_KEY="pb_live_Kyc2gafDF7Qc8c2ALELtEC"
export POST_BRIDGE_BASE_URL="https://api.post-bridge.com/v1"

3. Python PIL (Pillow)

Check if installed:

python3 -c "from PIL import Image; print('PIL available')"

Install:

pip3 install Pillow

4. FFmpeg (for optional resizing)

Check if installed:

ffmpeg -version

Install (optional - PIL handles most tasks):

# Debian/Ubuntu
sudo apt update && sudo apt install ffmpeg

# macOS
brew install ffmpeg

4. ImgBB API Key (OPTIONAL - for auto-hosting)

Get FREE API key at: https://api.imgbb.com/

Set environment variable (optional - for auto-upload to ImgBB):

export IMGBB_API_KEY="your_imgbb_api_key_here"

Why ImgBB?

• Free tier: 32MB per image upload
• No strict rate limit for free tier
• Simple REST API
• Permanent image hosting
• Public URLs for social media platforms

5. Directory Structure

Skill will create:

~/.tiktok-slideshow/
├── images/          # Downloaded from Pexels
├── rendered/        # FFmpeg rendered slides
├── scripts/         # Helper scripts
└── projects/        # Project metadata

---

TikTok Carousel Best Practices (2026)

Algorithm Metrics (from latest research):

• Swipe-through rate: Percentage of users who swipe all slides
• Dwell time: Time spent viewing each slide
• Reverse swipes: Users swiping back to re-view

Optimal Format:

Resolution: 1080 × 1920px (9:16 vertical)
Slides: 5-10 images (best engagement)
Image size: < 100KB per slide (fast loading)
Aspect ratio: 9:16 (native TikTok)

Engagement Tips:

1. Hook in first slide: Bold, attention-grabbing text
2. Storytelling progression: Each slide builds on previous
3. CTA on last slide: Follow, save, share, or link
4. Consistent visual style: Same font, color palette
5. High-quality images: Use high-res Pexels images

Text Overlay Best Practices:

• Font size: 32-48px for titles, 24-32px for subtitles
• Position: Centered with margins
• Color: White text with black outline (high contrast)
• Background: Semi-transparent dark box for readability
• Length: Max 2-3 lines per slide

---

Usage

Create Slideshow

python3 tiktok_slideshow.py create "morning routine" "Your routine is broken" 5

Parameters:

• topic: Search theme for Pexels images
• hook: Hook text for first slide (attention-grabbing)
• num_slides: Number of slides (5-10 recommended)

Example:

python3 tiktok_slideshow.py create "productivity tips" "You're doing productivity wrong" 7

List Projects

python3 tiktok_slideshow.py list

Shows all existing projects with metadata.

Host Images Only (ImgBB)

Upload all carousel images to ImgBB hosting:

# Requires IMGBB_API_KEY
export IMGBB_API_KEY="your_imgbb_api_key"

python3 tiktok_slideshow.py host <project_id>

Outputs public URLs for all slides:

🖼️  Uploading 5 slides to ImgBB hosting...
✅ Uploaded to ImgBB: slide_1.jpg
✅ Uploaded to ImgBB: slide_2.jpg
✅ Uploaded to ImgBB: slide_3.jpg
✅ Uploaded to ImgBB: slide_4.jpg
✅ Uploaded to ImgBB: slide_5.jpg

✅ Uploaded 5 slides to ImgBB!

Media URLs:
  1. https://i.ibb.co/xxx/slide-1.jpg
  2. https://i.ibb.co/yyy/slide-2.jpg
  3. https://i.ibb.co/zzz/slide-3.jpg
  4. https://i.ibb.co/aaa/slide-4.jpg
  5. https://i.ibb.co/bbb/slide-5.jpg

📝 URLs saved to: /home/openclaw/.tiktok-slideshow/projects/project_id_urls.txt

Upload to TikTok

Option 1: Auto-host + upload (recommended)

Automatically uploads images to ImgBB, then posts to TikTok via PostBridge.

Option 2: Manual hosting + upload

# Step 1: Host images manually (use ImgBB, S3, Cloudinary, etc.)
python3 tiktok_slideshow.py host <project_id>

# Step 2: Upload to TikTok (skip hosting)
python3 tiktok_slideshow.py upload <project_id> --no-host

Note: ImgBB hosting is FREE and recommended for social media uploads.

---

Complete Example

# 1. Set your Pexels API key
export PEXELS_API_KEY="563492ad6f91700001000001234567890"

# 2. Create a slideshow
python3 tiktok_slideshow.py create "fitness motivation" "Stop making this mistake" 5

# Output:
# ==================================================
# 📱 Creating TikTok Slideshow
# ==================================================
# 🎯 Topic: fitness motivation
# 🪝 Hook: Stop making this mistake
# 📊 Slides: 5
# ==================================================
#
# 🔍 Searching images on Pexels...
# 📸 Found 5 images for: fitness motivation
# ✅ Downloaded: temp_0.jpg
# ✅ Rendered: slide_1.jpg
# ✅ Downloaded: temp_1.jpg
# ✅ Rendered: slide_2.jpg
# ...
#
# ==================================================
# ✅ Slideshow Created Successfully!
# ==================================================
# 📦 Project ID: fitness_motivation_20260306_044512
# 📁 Slides: 5
# 📂 Location: /home/openclaw/.tiktok-slideshow/rendered/
# 💾 Metadata: /home/openclaw/.tiktok-slideshow/projects/fitness_motivation_20260306_044512.json
# ==================================================

# 3. Review slides
ls /home/openclaw/.tiktok-slideshow/rendered/

# 4. Upload to TikTok (requires image hosting setup)
python3 tiktok_slideshow.py upload fitness_motivation_20260306_044512

---

How It Works

Step 1: Search Images with Pexels API

POST https://api.pexels.com/v1/search
Authorization: {PEXELS_API_KEY}

Query Parameters:
- query: "fitness motivation"
- orientation: "vertical"  # For TikTok 9:16
- size: "large"
- per_page: 5

Response:
{
  "photos": [
    {
      "id": 123456,
      "src": {
        "large": "https://images.pexels.com/photos/123456/large.jpg"
      },
      "photographer": "Joe Smith"
    }
  ]
}

Step 2: Download & Resize with FFmpeg

Resize to TikTok format and add professional text overlay:

ffmpeg -i input.jpg \
  -vf "scale=1080:1920,drawtext=text='Your Text Here':fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf:fontsize=48:fontcolor=white:x=(w-text_w)/2:y=(h-text_h)/2:borderw=4:bordercolor=black:box=1:[email protected]:boxborderw=10" \
  -q:v 2 \
  output.jpg

FFmpeg parameters explained:

• scale=1080:1920: Resize to TikTok format
• fontsize=48: Title font size
• fontcolor=white: Text color
• borderw=4:bordercolor=black: Text outline
• box=1:[email protected]: Semi-transparent background
• boxborderw=10: Box padding
• -q:v 2: JPEG quality (2-5 recommended)

Step 3: Upload via PostBridge

from skills_1ai_skills.marketing.post_bridge_client import PostBridgeClient

client = PostBridgeClient(api_key=POST_BRIDGE_API_KEY)
tiktok_accounts = client.get_accounts_by_platform("tiktok")

client.create_post(
    caption="Here's my carousel...",
    account_ids=[tiktok_accounts[0]['id']],
    media_urls=[...your hosted image URLs...]
)

---

Publishing to ClawHub

After publishing this skill:

GITHUB_TOKEN="clh_Nf4OK9akiUsJe4mKeVaCJiupZILjii6g35bxs9LX5-w"

clawhub publish \
  ~/.openclaw/workspace/skills/tiktok-carousel-creator \
  --slug tiktok-carousel-creator \
  --name "TikTok Carousel Creator (Pexels + FFmpeg + PostBridge)" \
  --version 1.0.0 \
  --changelog "Initial release. Custom TikTok carousel creator using Pexels API + FFmpeg + PostBridge. Designed for BerkahKarya workflow." \
  --tags latest,tiktok,carousel,slideshow,pexels,ffmpeg,postbridge

Learn more: https://www.tip.md/oyi77

---

Resources

• Pexels API: https://www.pexels.com/api/
• FFmpeg Documentation: https://ffmpeg.org/documentation.html
• PostBridge Documentation: Check local skill docs
• TikTok Carousel Best Practices: Regularly research algorithm changes (meta updates frequently)
• Publishing Help: https://docs.openclaw.ai/tools/clawhub

---

Troubleshooting

Pexels API Key Not Set

Error: PEXELS_API_KEY not set

Solution:

export PEXELS_API_KEY="your_key_here"

Get free key at: https://www.pexels.com/api/

FFmpeg Not Found

Error: ffmpeg not found

Solution:

sudo apt update && sudo apt install ffmpeg

No Images Found

Error: No images found for topic: xyz

Solution:

• Try different search terms
• Check Pexels API key is valid
• Use more generic terms

---

BerkahKarya Custom Implementation - 2026 Learn more: https://www.tip.md/oyi77