youtube-thumbnail-generator 2.2.4

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)
• ✅ YouTube API Ready: Built-in optimization for YouTube API v3 thumbnail upload compliance

🎨 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)
10. youtube_ready - Generate YouTube API v3 compliant output (boolean, default: True)

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

youtube_ready (bool) - Optimize for YouTube API v3 compliance

youtube_ready=True     # Default: Generate 1280x720 YouTube-compliant thumbnail (2MB max, JPEG, sRGB)
youtube_ready=False    # Generate 1600x900 high-resolution thumbnail

📦 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
• ✅ Auto Template Creation: If templates are missing, they're automatically generated in your project directory

Smart Fallback System: If bundled templates can't be found (rare edge case), the system automatically creates default templates in your current directory.

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

🚀 Usage Methods

1. Use as Python Library

Dark Theme (Default - YouTube Ready)

from youtube_thumbnail_generator import FinalThumbnailGenerator, get_default_template

# Initialize generator with bundled template
generator = FinalThumbnailGenerator(get_default_template())

# Generate YouTube-ready thumbnail (1280x720, <2MB, optimized for API upload)
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_youtube.jpg",
    theme="dark"  # Default theme, youtube_ready=True by default
)

Light Theme (YouTube Ready)

# Generate Light theme YouTube-ready 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_youtube.jpg",
    theme="light",
    title_color="#000000",  # Black text for white background
    author_color="#666666"  # Dark gray author
    # youtube_ready=True by default - 1280x720 YouTube API ready
)

Custom Theme (YouTube Ready)

# Generate Custom theme YouTube-ready thumbnail
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_youtube.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
    # youtube_ready=True by default - optimized for YouTube API
)

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. YouTube API v3 Ready Thumbnails

Generate thumbnails that are fully compliant with YouTube API v3 upload requirements:

from youtube_thumbnail_generator import FinalThumbnailGenerator, get_default_template

generator = FinalThumbnailGenerator(get_default_template())

# Generate YouTube API v3 compliant thumbnail (default behavior)
result = generator.generate_final_thumbnail(
    title="My YouTube Video Title",
    author="Channel Name", 
    logo_path="my_logo.png",
    right_image_path="video_frame.jpg",
    output_path="my_video_thumbnail.jpg",
    theme="dark"
    # youtube_ready=True by default - outputs 1280x720 JPEG, sRGB, <2MB
)
# Output: Ready for direct YouTube API upload!

Manual YouTube Optimization

from youtube_thumbnail_generator import optimize_for_youtube_api

# Optimize existing thumbnail for YouTube API
youtube_ready_path = optimize_for_youtube_api(
    input_path="my_large_thumbnail.jpg",
    output_path="my_thumbnail_youtube_ready.jpg"  # Optional
)
# Automatically converts to 1280x720 JPEG, ensures <2MB size

YouTube API v3 Compliance Features

• ✅ Perfect Dimensions: 1280x720 pixels (16:9 aspect ratio)
• ✅ Optimal Format: JPEG with baseline encoding
• ✅ File Size Control: Automatic compression to stay under 2MB limit
• ✅ Color Space: sRGB color profile for consistent display
• ✅ Smart Cropping: Maintains aspect ratio with center cropping
• ✅ Quality Optimization: Multi-level quality testing (95→90→85→80→75→70)

4. Use in Other Python Projects

# In your Python projects
from youtube_thumbnail_generator import FinalThumbnailGenerator, get_default_template, create_text_png

# Quick YouTube-ready thumbnail generation with bundled template
generator = FinalThumbnailGenerator(get_default_template())
result = generator.generate_final_thumbnail(
    title="Your Video Title",
    output_path="output/thumbnail_youtube.jpg"
    # Outputs 1280x720 YouTube API compliant thumbnail by default
)

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

5. 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

6. 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

Manual Template Creation

If you need to manually create templates in your project directory:

from youtube_thumbnail_generator import init_templates

# This creates a 'templates/' directory with all required files:
# - professional_template.jpg (1600x900 black background)
# - light_template.png (1600x900 white background) 
# - triangle_black.png (200x900 opaque black triangle)
# - triangle_white.png (200x900 opaque white triangle)
init_templates()

Advanced Triangle Customization

For advanced users who want custom triangle effects:

from youtube_thumbnail_generator import generate_triangle_template

# Generate 4 different triangle variants:
generate_triangle_template("black", "bottom")    # Default: point at bottom-left
generate_triangle_template("black", "top")       # Point at top-left  
generate_triangle_template("white", "bottom")    # White, point at bottom-left
generate_triangle_template("white", "top")       # White, point at top-left

# Custom colors and sizes:
generate_triangle_template("#FF0000", "bottom", "red_triangle.png", 300, 900)
generate_triangle_template("#00FF00", "top", "green_triangle_top.png")

Triangle Options:

• Colors: "black", "white", or hex colors like "#FF0000"
• Directions: "bottom" (point at bottom-left), "top" (point at top-left)
• Custom sizes: width and height in pixels
• Custom paths: specify your own output filename

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 (auto-created if needed)

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.2.2 (Current) - YouTube-Ready by Default

• ✅ Default YouTube Optimization: All thumbnails are YouTube API compliant by default
• ✅ Seamless User Experience: No extra steps needed for YouTube uploads
• ✅ Clean File Management: Optimized files use original filenames
• ✅ High-Resolution Option: Use youtube_ready=False for 1600x900 images

v2.2.1 - YouTube API Integration

• ✅ YouTube API v3 Compliance: Built-in optimization for YouTube thumbnail uploads
• ✅ Smart Resource Management: Package path resolution with automatic fallback template creation
• ✅ Format Optimization: 1280x720 JPEG, sRGB color space, <2MB file size control
• ✅ Quality Control: Multi-level compression testing for optimal file size
• ✅ Cross-Platform: Improved compatibility across Python 3.7+ environments

v2.2.0 - Three Theme Architecture Revolution

• ✅ Complete Theme System: Dark, Light, and Custom modes with full parameterization
• ✅ Color Customization: Hex color support for titles and authors
• ✅ Triangle Control: Configurable overlay effects per theme
• ✅ Custom Backgrounds: User-provided template support

v2.1 - 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.2.2
• 📅 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

🚨 Troubleshooting & Important Notes

🔧 Common Issues & Solutions

Template Files Not Found

If you encounter FileNotFoundError for template files:

Problem: Templates missing after PyPI installation or in development.

Solutions (try in order):

1. Automatic Resolution - The system will automatically create missing templates
2. Manual Creation:

   from youtube_thumbnail_generator import init_templates
   init_templates()  # Creates all required templates
   

3. Resource Path Check:

   from youtube_thumbnail_generator import get_resource_path
   print(get_resource_path("templates/professional_template.jpg"))
   

Custom Triangle Effects Not Working

Problem: Default triangles don't match your design needs.

Solution: Generate custom triangles:

from youtube_thumbnail_generator import generate_triangle_template

# 4 basic variants:
generate_triangle_template("black", "bottom")  # Standard
generate_triangle_template("black", "top")     # Inverted
generate_triangle_template("white", "bottom")  # Light theme
generate_triangle_template("white", "top")     # Light inverted

# Custom colors:
generate_triangle_template("#FF6B35", "bottom", "custom_orange.png")

YouTube API Upload Failures

Problem: Generated thumbnails rejected by YouTube API.

Check: Ensure you're using the YouTube-optimized version:

result = generator.generate_final_thumbnail(
    title="Your Title",
    youtube_ready=True  # This is now default - ensures 1280x720, <2MB, sRGB
)

# Or manually optimize existing thumbnails:
from youtube_thumbnail_generator import optimize_for_youtube_api
youtube_path = optimize_for_youtube_api("your_thumbnail.jpg")

📋 System Requirements & Notes

1. File Paths: All paths are automatically resolved with smart fallbacks
2. Font Dependencies: System will auto-downgrade to available fonts
3. Template Management: Missing templates are auto-created in your project directory
4. Output Format: Default YouTube-ready (1280x720 JPEG), use youtube_ready=False for high-res
5. API Processing: API uses async processing, poll status for completion
6. Memory Usage: Large image processing may use significant memory
7. Cross-Platform: Full compatibility across macOS, Linux, and Windows

---

💡 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, get_default_template
   generator = FinalThumbnailGenerator(get_default_template())
   generator.generate_final_thumbnail(title="Test Title", output_path="test_youtube.jpg")
   # Generates 1280x720 YouTube-ready thumbnail by default
   

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

Start creating professional YouTube thumbnails now! 🎬✨