youtube-thumbnail-generator 2.2.0

AI-powered YouTube thumbnail generator with Chinese/English support and intelligent text processing

YouTube Thumbnail Generator v2.1

Professional YouTube thumbnail automatic generation tool with intelligent Chinese/English text layout, logo, and precise image control with dynamic adaptation.

Author: Leo Wang (https://leowang.net)

🌍 Available on PyPI: https://pypi.org/project/youtube-thumbnail-generator/
📂 GitHub Repository: https://github.com/preangelleo/youtube-thumbnail-generator

📋 Core Features

• ✅ Intelligent Chinese/English System: PNG overlay technology, perfect Chinese/English text mixing
• ✅ Smart Line-breaking Algorithm: Chinese 9 character limits, English 3-line truncation
• ✅ Font Differentiation Optimization: Chinese fonts 30% larger for optimal readability
• ✅ Professional Visual Effects: Triangle transition integrated into images, text always on top layer
• ✅ Intelligent Image Processing: Auto square conversion + 900x900 filling
• ✅ Multi-endpoint API Support: Flask RESTful API + Chapter functionality
• ✅ Smart Font Selection: Chinese PingFang/Founder, English Lexend Bold
• ✅ Three Theme Modes: Dark (black bg), Light (white bg), Custom (user template)
• ✅ Full Color Customization: Title color, author color, triangle toggle - all parameterized
• ✅ Dynamic Font Scaling: Auto font size adjustment based on text length (1-17 characters)

🎨 Three Theme Modes

Canvas Size: 1600x900 pixels

🌑 Dark Theme - Professional Black Background

Perfect for: Tech content, gaming, serious topics
Features: Black background + White bold text + Black triangle overlay + Professional contrast

Chinese Sample (10 characters - optimal length)

English Sample (7 words - optimal length)

🌕 Light Theme - Clean White Background

Perfect for: Educational content, lifestyle, bright topics
Features: White background + Black bold text + White triangle overlay + Clean minimalist look

Chinese Sample (10 characters - optimal length)

English Sample (7 words - optimal length)

🌈 Custom Theme - Your Own Background

Perfect for: Brand content, creative projects, unique aesthetics
Features: Custom 1600x900 background + Customizable text colors + No triangle overlay + Full creative control

Chinese Sample (10 characters - optimal length)

English Sample (7 words - optimal length)

💡 Optimal Length Recommendations

🎯 Best Results Guidelines

For the most professional and visually appealing thumbnails:

🇨🇳 Chinese Titles

Optimal Length: 10-12 characters

• 10 characters: Perfect balance, excellent readability
• 12 characters: Maximum recommended, maintains clarity
• Examples: "AI技术指南教程" (8 chars) ✅ "完整AI技术指南教程系统" (12 chars) ✅

🇺🇸 English Titles

Optimal Length: 7 words

• 7 words: Perfect for 3-line layout without truncation
• Example: "Complete AI Technology Guide Tutorial Series Episode" (7 words) ✅
• Note: Longer titles may be truncated with ellipsis (...)

📦 Supported Parameters

Required Parameters

1. title - Main title text (required)

Optional Parameters

2. author - Author name (optional, auto-capitalized)
3. logo_path - Logo file path (optional)
4. right_image_path - Right-side image path (optional)
5. theme - Theme mode: "dark", "light", "custom" (default: "dark")
6. custom_template - Custom background path for custom theme (required when theme="custom")
7. title_color - Title text color in hex format (e.g., "#FFFFFF")
8. author_color - Author text color in hex format (e.g., "#CCCCCC")
9. enable_triangle - Enable/disable triangle overlay (boolean)

Theme Defaults

• Dark Theme: Black bg + White text (#FFFFFF) + Light gray author (#CCCCCC) + Black triangle
• Light Theme: White bg + Black text (#000000) + Dark gray author (#666666) + White triangle
• Custom Theme: User background + White text (#FFFFFF) + Light gray author (#CCCCCC) + No triangle

🧠 Intelligent Text System

Core Technology: PNG Overlay + Triangle Integration

Instead of drawing text directly on template:

1. Independent Rendering: Generate transparent PNG text images first
2. Smart Adjustment: Dynamically adjust PNG size based on text length
3. Triangle Integration: Paste triangle to right-side image first, then paste combined image to template
4. Text Overlay: PNG text pasted last, ensuring it's always on the top layer

Chinese/English Differentiated Processing

Chinese Optimization

• Font Enlargement: 30% larger than English (54px vs 42px title)
• Smart Line-breaking:
  • Title: Break after 9 characters, divide by 2, odd characters go to second line
• Line Spacing: Title 16px

English Processing

• Space-based Line-breaking: Natural word boundary wrapping
• 3-line Limit: Title max 3 lines, auto-truncate with ellipsis
• Standard Font: Lexend Bold
• Standard Line Spacing: 8px

📝 Input Parameter Details

Required Parameters

title (str) - Main title

title="The Ultimate Complete Guide to Advanced AI Technology"

• Smart Line-breaking: Auto-calculate optimal line-break positions
• Dynamic Height: Adjust PNG height based on line count (55px/line + line spacing)
• Dynamic Font Scaling: Auto font size based on character count (1-17 chars)
• Effects: Clean bold font with theme-based colors
• Position: Starting at (55, 330), dynamically centered

Optional Parameters

author (str) - Author name

author="Leo Wang"  # Auto-converts to "LEO WANG"

• Format: Auto-convert to uppercase
• Position: Fixed bottom (55, 800)
• Font: 36px Lexend Bold, theme-based color

logo_path (str) - Logo file path

logo_path="logos/your_logo.png"

• Position: Top-left corner (50, 50), left margin = top margin
• Area: 240x150 pixels, auto aspect ratio scaling
• Format: Supports PNG/JPG, auto-handle transparency

right_image_path (str) - Right-side image path

right_image_path="assets/your_image.jpg"

• Smart Cropping: Auto-convert to square (center crop)
• Fill Method: Scale to 900x900 pixels to fill right side
• Position: Right area starting at (700, 0)

Theme & Color Parameters

theme (str) - Theme mode: "dark", "light", "custom"

theme="dark"     # Default: Black bg + white text + black triangle
theme="light"    # White bg + black text + white triangle  
theme="custom"   # User-provided template + custom colors

custom_template (str) - Custom template path (required for custom theme)

custom_template="path/to/your_template.png"  # Must be 1600x900 PNG

title_color (str) - Title text color in hex format

title_color="#FFFFFF"  # White (dark theme default)
title_color="#000000"  # Black (light theme default)
title_color="#FF0000"  # Red (custom example)

author_color (str) - Author text color in hex format

author_color="#CCCCCC"  # Light gray (dark theme default)
author_color="#666666"  # Dark gray (light theme default)
author_color="#0000FF"  # Blue (custom example)

enable_triangle (bool) - Enable/disable triangle overlay

enable_triangle=True   # Default for dark/light themes
enable_triangle=False  # Default for custom theme

📦 Installation

The package is officially available on PyPI and can be installed worldwide:

Quick Install (Recommended)

pip install youtube-thumbnail-generator

With API Service Support

pip install "youtube-thumbnail-generator[api]"

Alternative Installation Methods

Method	Command	Use Case
PyPI (Stable)	pip install youtube-thumbnail-generator	Production use, stable releases
PyPI with API	pip install "youtube-thumbnail-generator[api]"	Include Flask API dependencies
GitHub (Latest)	pip install git+https://github.com/preangelleo/youtube-thumbnail-generator.git	Latest development features
Development	git clone ... && pip install -e .	Local development and testing

Package Information

• PyPI Page: https://pypi.org/project/youtube-thumbnail-generator/
• Current Version: 2.2.0
• License: MIT
• Python Support: 3.7+
• Dependencies: Pillow (required), Flask+CORS (optional for API)

📦 What's Included Automatically

When you install via PyPI or GitHub, you get everything you need:

• ✅ All Templates: Dark, Light, and Custom background templates
• ✅ Triangle Assets: Black and white triangle overlays
• ✅ Professional Template: 1600x900 high-quality base template
• ✅ Font Assets: Chinese/English optimized fonts
• ✅ Sample Assets: Testing logo and image files

No additional downloads needed - start generating thumbnails immediately after installation!

🚀 Usage Methods

1. Use as Python Library

Dark Theme (Default)

from youtube_thumbnail_generator import FinalThumbnailGenerator

# Initialize generator
generator = FinalThumbnailGenerator("templates/professional_template.jpg")

# Generate Dark theme thumbnail (recommended: 10-12 Chinese chars or 7 English words)
result = generator.generate_final_thumbnail(
    title="Complete AI Technology Guide",  # 5 words - will be enlarged
    author="Leo Wang",
    logo_path="logos/your_logo.png",
    right_image_path="assets/your_image.jpg",
    output_path="outputs/dark_theme.jpg",
    theme="dark"  # Default theme
)

Light Theme

# Generate Light theme thumbnail  
result = generator.generate_final_thumbnail(
    title="AI技术指南完整教程",  # 10 Chinese characters - optimal
    author="Leo Wang",
    logo_path="logos/your_logo.png", 
    right_image_path="assets/your_image.jpg",
    output_path="outputs/light_theme.jpg",
    theme="light",
    title_color="#000000",  # Black text for white background
    author_color="#666666"  # Dark gray author
)

Custom Theme

# Generate Custom theme with your own background
result = generator.generate_final_thumbnail(
    title="Custom Background Demo",  # 4 words - will be enlarged
    author="Your Name",
    logo_path="logos/your_logo.png",
    right_image_path=None,  # No right image needed
    output_path="outputs/custom_theme.jpg",
    theme="custom",
    custom_template="your_background_1600x900.png",  # Your custom background
    title_color="#FFFFFF",  # White text  
    author_color="#CCCCCC",  # Light gray author
    enable_triangle=False  # No triangle overlay
)

2. Command Line API Service

Launch API directly after installation:

# Start API service directly
youtube-thumbnail-api

# Or use Python module method
python -m youtube_thumbnail_generator.api_server

3. Use in Other Python Projects

# In your Python projects
from youtube_thumbnail_generator import FinalThumbnailGenerator, create_text_png

# Quick thumbnail generation
generator = FinalThumbnailGenerator("path/to/your/template.jpg")
result = generator.generate_final_thumbnail(
    title="Your Video Title",
    output_path="output/thumbnail.jpg"
)

# Or generate text PNG only
success, text_img, height = create_text_png(
    text="Test Text",
    width=600,
    height=200,
    language="chinese"
)

4. API Service Calls

Generate Thumbnail

curl -X POST http://localhost:5002/api/generate/enhanced \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Amazing Tech Reviews 2025",
    "author": "Leo Wang",
    "logo_path": "logos/animagent_logo.png",
    "right_image_path": "assets/testing_image.jpeg"
  }'

Response Example

{
  "task_id": "abc123-def456-ghi789",
  "status": "processing",
  "message": "Thumbnail generation task started"
}

Check Task Status

curl http://localhost:5002/api/status/abc123-def456-ghi789

Download Result

curl -O http://localhost:5002/api/download/final_test.jpg

3. Python API Client Example

import requests
import time
import json

def generate_thumbnail_api(title, author=None, logo_path=None, image_path=None):
    """Generate thumbnail using API"""
    
    # 1. Send generation request
    response = requests.post('http://localhost:5002/api/generate/enhanced', 
        headers={'Content-Type': 'application/json'},
        data=json.dumps({
            "title": title,
            "author": author,
            "logo_path": logo_path,
            "right_image_path": image_path
        })
    )
    
    task_data = response.json()
    task_id = task_data['task_id']
    print(f"Task created: {task_id}")
    
    # 2. Poll status until complete
    while True:
        status_response = requests.get(f'http://localhost:5002/api/status/{task_id}')
        status_data = status_response.json()
        
        print(f"Status: {status_data['status']}")
        
        if status_data['status'] == 'completed':
            print(f"Generation complete! Download: {status_data['download_url']}")
            return status_data['download_url']
        elif status_data['status'] == 'failed':
            print(f"Generation failed: {status_data['error']}")
            return None
        
        time.sleep(1)

# Usage example
download_url = generate_thumbnail_api(
    title="My Amazing YouTube Video Title That Is Really Long",
    author="Your Name",
    logo_path="logos/my_logo.png",
    image_path="assets/thumbnail_image.jpg"
)

🎯 Complete API Endpoint Guide

Thumbnail Generation

POST /api/generate/enhanced

Request Body:

{
  "title": "Required - Main title text",
  "author": "Optional - Author name",
  "logo_path": "Optional - Logo file path",
  "right_image_path": "Optional - Right-side image path"
}

Chapter Image Generation

POST /api/generate/chapter

Request Body:

{
  "text": "Required - Text to display",
  "language": "Optional - english/chinese",
  "font_size": "Optional - Font size",
  "width": "Optional - Image width, default 1600", 
  "height": "Optional - Image height, default 900"
}

Other Endpoints

• GET /api/status/<task_id> - Check task status
• GET /api/download/<filename> - Download generated file
• GET /api/health - Health check
• GET /api/templates - Get available templates
• GET /api/assets - Get resource list

📊 Smart Layout Examples

Short Title Effect

Title: "Tech News 2025" 
→ 1 line, centered layout, clean appearance

Long Title Effect

Title: "The Ultimate Complete Guide to Advanced AI Technology..."
→ Multiple lines with smart line-breaking
Auto-adjust positions for perfect fit

Overlong Content Handling

Title exceeds 3 lines → Auto-truncate with ellipsis
Ensure stable layout, prevent content overflow

🔧 Advanced Configuration

File Path Rules

• Relative Paths: Relative to project root directory
• Logo Directory: logos/ - Store all logo files
• Assets Directory: assets/ - Store background images
• Output Directory: outputs/ - Generated results storage
• Template Directory: templates/ - Template file storage

Supported Image Formats

• Input: PNG, JPG, JPEG (supports transparency)
• Output: JPG (high quality, 95% quality)
• Processing: Auto color mode conversion

Font Priority

English Fonts:
1. Helvetica (Mac system)
2. Lexend Bold (if installed)
3. Ubuntu Bold (Linux)
4. System default font

Chinese Fonts:
1. Noto Sans CJK Bold
2. Source Han Sans
3. WenQuanYi fonts

📁 Project Structure

youtube_thumbnail_generator/
├── youtube_thumbnail_generator/
│   ├── __init__.py                   # Package initialization
│   ├── final_thumbnail_generator.py  # Core generator
│   ├── text_png_generator.py         # PNG text renderer  
│   ├── api_server.py                 # Flask API service
│   └── function_add_chapter.py       # Chapter functionality
├── templates/
│   ├── professional_template.jpg     # 1600x900 professional template
│   └── triangle_template.png         # 200x900 triangle transition
├── template_samples/                 # Template showcase samples
├── setup.py                          # Package setup
├── pyproject.toml                    # Modern Python packaging
├── README.md                         # Project documentation
└── README_API.md                     # Detailed API documentation

📈 Version History

v2.1 (Current) - Smart Layout Revolution

• ✅ PNG Overlay Technology: Text rendering separated from template, perfect control
• ✅ Smart Height Adjustment: Dynamically adjust layout based on content length
• ✅ Line Spacing Optimization: 8px line spacing, improved reading experience
• ✅ Triangle Transition: 200x900 diagonal separation, professional visual effects
• ✅ Truncation Mechanism: Smart truncation for overlong content, stable layout
• ✅ Dual API Support: Thumbnail + Chapter dual-function API
• ✅ Python Package: Installable as pip package, use in any Python project

v1.0 - Basic Functionality

• ✅ Professional template layout design
• ✅ Auto square image conversion
• ✅ 5-parameter input system
• ✅ Smart font selection
• ✅ Complete text effects
• ✅ Flask API integration

🏆 Project Status

PyPI Distribution

• 📦 Live on PyPI: https://pypi.org/project/youtube-thumbnail-generator/
• 🌍 Global Install: pip install youtube-thumbnail-generator
• 📊 Download Stats: Available on PyPI Stats
• 🔖 Latest Version: 2.1.0
• 📅 Published: August 2025

Community & Support

• ⭐ GitHub Stars: https://github.com/preangelleo/youtube-thumbnail-generator
• 🐛 Issue Tracking: https://github.com/preangelleo/youtube-thumbnail-generator/issues
• 📖 Documentation: Complete README and API docs
• 🌐 International: Full English documentation for global users

🎯 Best Practices

Title Text Suggestions

• Length: Recommend 50-100 characters, system auto-optimizes display
• Content: Clearly express video theme, attract viewer clicks
• Keywords: Front-load important keywords, improve search results

Image Selection Principles

• Size: Any size, system auto-converts to square
• Content: Choose visually impactful images
• Quality: Recommend high resolution, ensure clarity after scaling

🚨 Important Notes

1. File Paths: Ensure all file paths are correct and files exist
2. Font Dependencies: System will auto-downgrade to available fonts
3. Output Overwrite: Default output final_test.jpg, will overwrite same-name files
4. API Async: API uses async processing, need to poll status
5. Memory Usage: Large image processing may use significant memory

---

💡 Quick Start

1. Install Package: pip install youtube-thumbnail-generator
2. Prepare Assets: Put logos and images in corresponding directories
3. Direct Test:

   from youtube_thumbnail_generator import FinalThumbnailGenerator
   generator = FinalThumbnailGenerator("templates/professional_template.jpg")
   generator.generate_final_thumbnail(title="Test Title", output_path="test.jpg")
   

4. API Service: youtube-thumbnail-api
5. Check Result: Look at generated file

Start creating professional YouTube thumbnails now! 🎬✨