YouTube Thumbnail Generator 🎨

A powerful YouTube thumbnail generator with optional AI text optimization and multi-language support. Create eye-catching thumbnails with customizable backgrounds, fonts, and AI-enhanced text.

✨ Features

• Customizable Backgrounds: Solid colors, gradients, or image backgrounds
• Multiple Font Support: Various fonts and styles
• AI Text Optimization: Optional Gemini AI integration for better text
• Multi-Language Support: Automatic language detection or manual specification (supports en/english, zh/chinese)
• Flexible Layouts: Multiple text positions and sizes
• High Quality Output: 1280x720 HD thumbnails
• Docker Support: Easy deployment with Docker

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/preangelleo/youtube-thumbnail-generator.git
cd youtube-thumbnail-generator

# Install dependencies
pip install -r requirements.txt

# Or install from PyPI
pip install youtube-thumbnail-generator

Basic Usage

Python Library

from src.thumbnail_generator import ThumbnailGenerator

# Create generator instance
generator = ThumbnailGenerator()

# Generate a simple thumbnail
thumbnail = generator.generate(
    text="Amazing Python Tutorial",
    output_path="thumbnail.png"
)

CLI Usage

# Basic thumbnail
youtube-thumbnail "Amazing Python Tutorial" -o thumbnail.png

# With AI optimization
youtube-thumbnail "Python Tutorial" --enable-ai --source-language en

# With translation (Chinese to English)
youtube-thumbnail "Python编程" --enable-ai --source-language zh --target-language en

# Custom styling
youtube-thumbnail "Tutorial" --font-size 100 --bg-color1 "#FF0000"

REST API

# Start the API server
python -m src.api

# Generate thumbnail via API
curl -X POST http://localhost:5000/generate \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Amazing Tutorial",
    "enable_ai_optimization": true,
    "source_language": "en"  // Skip auto-detection
  }'

With AI Optimization

# Enable AI optimization with explicit control
generator = ThumbnailGenerator(
    gemini_api_key="your-api-key",
    enable_ai_optimization=True  # Explicit toggle
)

# Generate with explicit source language (skip detection)
# Supports both ISO codes and full names
thumbnail = generator.generate(
    text="Python Tutorial for Beginners",
    source_language="en",  # or "english" - Skip detection, specify it's English
    enable_ai_optimization=True,
    output_path="ai_thumbnail.png"
)

# Generate with translation (requires AI)
thumbnail = generator.generate(
    text="Python编程教程",
    source_language="chinese",  # or "zh" - Input is Chinese
    target_language="english",  # or "en" - Translate to English
    enable_ai_optimization=True,  # Required for translation
    output_path="translated_thumbnail.png"
)

📚 Documentation

For detailed documentation, see docs/DOCUMENTATION.md

For usage examples, see examples/example_usage.py

🐳 Docker

# Pull from Docker Hub
docker pull preangelleo/youtube-thumbnail-generator:latest

# Run the API server
docker run -p 5000:5000 \
  -e GEMINI_API_KEY=your-key \
  -e ENABLE_AI_OPTIMIZATION=true \
  preangelleo/youtube-thumbnail-generator

# Or build locally
docker build -t youtube-thumbnail-generator .
docker run -p 5000:5000 youtube-thumbnail-generator

🌐 API Endpoints

POST /generate

Generate a single thumbnail with full parameter control.

{
  "text": "Amazing Tutorial",
  "enable_ai_optimization": true,
  "target_language": "en",
  "background_type": "gradient",
  "font_size": 80
}

POST /batch

Generate multiple thumbnails in one request.

{
  "texts": ["Tutorial 1", "Tutorial 2"],
  "enable_ai_optimization": false,
  "target_language": "zh"
}

POST /optimize-text

Optimize text using AI (requires API key).

{
  "text": "Basic Python Tutorial",
  "target_language": "en",
  "style": "engaging"
}

POST /detect-language

Detect the language of text.

{
  "text": "Python编程教程"
}

🔧 Configuration

Create a .env file:

# Optional: Gemini AI API Key
GEMINI_API_KEY=your-api-key-here

# Optional: Enable AI by default
ENABLE_AI_OPTIMIZATION=true

# Optional: Default language
DEFAULT_LANGUAGE=en

📝 License

MIT License - see LICENSE file for details

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

📧 Support

For issues and questions, please use the GitHub Issues page.