levibes 0.1.1

Motivational Image Caption Generator - Create inspiring social media content with AI-generated captions

LeVibes

Generate motivational social media posts with AI and LeBron James

Features

• Generate beautiful motivational images with AI-powered captions
• Upload images as draft slideshows to TikTok
• Cloudflare R2 integration for image hosting
• Interactive CLI interface

Installation

# Clone the repository
git clone https://github.com/makors/levibes
cd levibes

# Install dependencies using uv
uv sync

# Or with pip
pip install -e .

Configuration

Create a .env file in the project root with the following variables:

Complete Example .env File

# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here

# TikTok API Configuration
TIKTOK_CLIENT_ID=your_tiktok_client_id
TIKTOK_CLIENT_SECRET=your_tiktok_client_secret

# Cloudflare R2 Configuration
CLOUDFLARE_R2_ENDPOINT_URL=https://abc123def456.r2.cloudflarestorage.com
CLOUDFLARE_R2_ACCESS_KEY_ID=your_r2_access_key_id
CLOUDFLARE_R2_SECRET_ACCESS_KEY=your_r2_secret_access_key
CLOUDFLARE_R2_BUCKET_NAME=my-levibes-bucket

# R2 Public URL (r2.dev subdomain - recommended)
CLOUDFLARE_R2_PUBLIC_URL_BASE=https://my-levibes-bucket.r2.dev

Environment Variables Breakdown

OpenAI Configuration

OPENAI_API_KEY=your_openai_api_key_here

TikTok API Configuration

TIKTOK_CLIENT_ID=your_tiktok_client_id
TIKTOK_CLIENT_SECRET=your_tiktok_client_secret

Cloudflare R2 Configuration

# Required R2 variables
CLOUDFLARE_R2_ENDPOINT_URL=https://your-account-id.r2.cloudflarestorage.com
CLOUDFLARE_R2_ACCESS_KEY_ID=your_r2_access_key_id
CLOUDFLARE_R2_SECRET_ACCESS_KEY=your_r2_secret_access_key
CLOUDFLARE_R2_BUCKET_NAME=your_r2_bucket_name

# Optional: Public URL base for accessing files
# Use r2.dev subdomain: https://your-bucket-name.r2.dev
# Or custom domain: https://your-custom-domain.com
CLOUDFLARE_R2_PUBLIC_URL_BASE=https://your-bucket-name.r2.dev

Setting up Cloudflare R2

1. Create a Cloudflare R2 Bucket:

   • Go to Cloudflare Dashboard
   • Navigate to R2 Object Storage
   • Create a new bucket with a unique name
   • Note the bucket name for your .env file

2. Create R2 API Token:

   • Go to "Manage R2 API Tokens"
   • Create a new API token with read/write permissions
   • Note the Access Key ID and Secret Access Key

3. Configure Public Access:

   • In your bucket settings, enable public access
   • This will give you an r2.dev subdomain: https://your-bucket-name.r2.dev
   • Set CLOUDFLARE_R2_PUBLIC_URL_BASE=https://your-bucket-name.r2.dev
   • Alternatively, configure a custom domain if desired

💡 Using r2.dev Subdomain

If you're using an r2.dev subdomain (like https://my-bucket.r2.dev), this is the recommended and simplest approach:

1. Enable public access on your R2 bucket
2. Use the provided r2.dev URL as your CLOUDFLARE_R2_PUBLIC_URL_BASE
3. The app will upload via the R2 API and serve files via the r2.dev subdomain

Example configuration:

CLOUDFLARE_R2_PUBLIC_URL_BASE=https://my-levibes-bucket.r2.dev

4. Set R2 Endpoint URL:
   • Format: https://your-account-id.r2.cloudflarestorage.com
   • Replace your-account-id with your actual Cloudflare account ID
   • This is used for uploads via API, not for public access

Setting up TikTok API

1. Create TikTok Developer Account:

   • Go to TikTok for Developers
   • Create a developer account
   • Create a new app

2. Configure App Settings:

   • Set redirect URI to: https://tiktoklocal.com:8080/callback
   • Enable the following scopes:
     • user.info.basic
     • user.info.profile
     • video.upload
   • Note the Client ID and Client Secret

3. Domain Configuration:

   • Add tiktoklocal.com to your hosts file pointing to 127.0.0.1
   • On macOS/Linux: echo "127.0.0.1 tiktoklocal.com" | sudo tee -a /etc/hosts
   • On Windows: Add to C:\Windows\System32\drivers\etc\hosts

Usage

Basic Usage

# Run the application
python main.py

# Or use the CLI directly
levibes

Command Line Options

# Generate images only
python main.py --no-upload

# Upload existing images
python main.py --upload-only

# Specify custom output directory
python main.py --output-dir ./my-images

# Set custom caption
python main.py --caption "Follow for more motivation!"

TikTok Upload Process

1. Authentication:

   • The app will open a browser for TikTok OAuth
   • You may see a security warning (SSL certificate)
   • Click "Advanced" and "Proceed to tiktoklocal.com"
   • Authorize the app

2. Image Upload:

   • Images are first uploaded to Cloudflare R2
   • R2 URLs are then used to create TikTok draft
   • Draft appears in your TikTok app inbox

3. Publishing:

   • Open TikTok app on your phone
   • Go to inbox and find the draft
   • Edit and publish as desired

File Structure

levibes/
├── src/levibes/
│   ├── caption_generation.py  # AI caption generation
│   ├── generate_images.py     # Image creation
│   ├── upload.py             # TikTok/R2 upload
│   ├── cli.py                # Command line interface
│   └── config.py             # Configuration management
├── output/                   # Generated images
├── main.py                   # Entry point
└── .env                      # Environment variables

API Limits

• TikTok API: 6 requests per minute per user
• R2 Storage: Check your Cloudflare plan limits
• OpenAI API: Based on your plan and usage

Troubleshooting

Common Issues

1. "Missing required environment variables"

   • Ensure all required variables are set in .env
   • Check for typos in variable names

2. "Authorization failed"

   • Verify TikTok Client ID and Secret
   • Check that redirect URI is correctly configured
   • Ensure tiktoklocal.com is in your hosts file

3. "Failed to upload to R2"

   • Verify R2 credentials and bucket name
   • Check bucket permissions
   • Ensure endpoint URL is correct
   • If using r2.dev subdomain, make sure public access is enabled on the bucket

4. SSL Certificate Warning

   • This is normal for local development
   • Click "Advanced" and "Proceed to tiktoklocal.com"

Debug Mode

Set DEBUG=1 in your .env file for detailed logging:

DEBUG=1

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

MIT License - see LICENSE file for details.