# YouTube Thumbnail Generator v2.4.8
Professional YouTube thumbnail generator with enhanced Chinese font bold rendering, AI-powered title optimization, and intelligent text layout system.
**Author**: Leo Wang (https://leowang.net)
[](https://badge.fury.io/py/youtube-thumbnail-generator)
๐ฆ [](https://pypi.org/project/youtube-thumbnail-generator/)
[](https://opensource.org/licenses/MIT)
**๐ 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
- โ
**Enhanced Chinese Font Bold**: STHeiti Medium priority + intelligent stroke effects for perfect bold rendering
- โ
**Professional Visual Effects**: Triangle transition integrated into images, text always on top layer
- โ
**Intelligent Image Processing**: Auto square conversion + 900x900 filling with smart resize/crop
- โ
**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
- ๐ **AI Title Optimization**: Google Gemini-powered mixed-language title optimization (optional)
- ๐ฒ **Random Template Generation**: One-click thumbnail creation with 12 random template combinations
- ๐ค **AI Agent Documentation**: Built-in `readme()` and `readme_api()` methods for AI code assistants
## ๐จ Template Examples
### Professional Dark Theme with Triangle
**Perfect for**: Tech content, gaming, serious topics
**Features**: Enhanced Chinese bold rendering with intelligent stroke effects
**Examples Available:**
- **English Example**: Professional dark theme with triangle overlay - perfect for tech content
- **Chinese Example**: Enhanced Chinese bold rendering with intelligent stroke effects
**[๐จ View Live Examples โ](https://github.com/preangelleo/youtube-thumbnail-generator/blob/main/EXAMPLES.md)**
#### ๐ **[View Complete Examples Gallery โ](https://github.com/preangelleo/youtube-thumbnail-generator/blob/main/EXAMPLES.md)**
**More Examples Available:**
- **12 Template Combinations**: Professional, Standard, Triangle themes ร Dark/Light ร With/Without triangle overlays
- **Mixed Language Support**: Chinese and English title examples
- **Enhanced Stroke Effects**: Perfect bold rendering for both dark and light backgrounds
- **CDN-Hosted**: All examples hosted on fast public CDN for worldwide access
## ๐ก Optimal Length Recommendations
### ๐ฏ Best Results Guidelines
For the most professional and visually appealing thumbnails:
#### โ ๏ธ **IMPORTANT: Single Language Only**
**Our system is optimized for single-language titles. Mixed languages may cause formatting issues.**
๐ซ **Avoid Mixed Languages**:
- โ "AIๆๆฏๆๅ Complete Guide" - English words may be improperly split in Chinese mode
- โ "Complete AI ๆๆฏๆๅ" - Chinese characters may break English word spacing
โ
**Use Single Languages**:
- โ
"AIๆๆฏๆๅๅฎๆดๆ็จ" - Pure Chinese
- โ
"Complete AI Technology Guide" - Pure English
#### ๐จ๐ณ Chinese Titles
**Optimal Length: 10-12 characters**
- **10 characters**: Perfect balance, excellent readability
- **12 characters**: Maximum recommended, maintains clarity
- **Pure Chinese Only**: Avoid mixing English words for best results
#### ๐บ๐ธ English Titles
**Optimal Length: 7 words**
- **7 words**: Perfect for 3-line layout without truncation
- **Pure English Only**: Avoid mixing Chinese characters for best results
## ๐ฆ Installation
### Quick Install (Recommended)
```bash
pip install youtube-thumbnail-generator
```
### With API Service Support
```bash
pip install "youtube-thumbnail-generator[api]"
```
## ๐ Quick Start
### 1. Simple Python Usage (Recommended)
```python
from youtube_thumbnail_generator import create_generator
# Create generator with zero configuration (recommended)
generator = create_generator()
# Generate YouTube-ready thumbnail (1280x720, <2MB, optimized for API upload)
result = generator.generate_final_thumbnail(
title="Complete AI Technology Guide",
author="Leo Wang",
logo_path="logos/your_logo.png", # โ ๏ธ Use square logo (1:1 ratio) for best results
right_image_path="assets/image.jpg", # Any size - auto-processed to 900x900
output_path="outputs/thumbnail.jpg"
)
```
### ๐จ Color Customization
Customize text colors for any theme using hex color codes:
```python
# Example 1: Custom colors with dark theme
result = generator.generate_final_thumbnail(
title="Your Title Here",
author="Your Name",
theme="dark",
title_color="#FF6B35", # Orange title
author_color="#4ECDC4", # Teal author name
output_path="custom_colors.jpg"
)
# Example 2: Custom colors with light theme
result = generator.generate_final_thumbnail(
title="Another Title",
author="Creator Name",
theme="light",
title_color="#2E86AB", # Blue title
author_color="#A23B72", # Purple author name
output_path="light_custom.jpg"
)
# Example 3: Custom template with custom colors
result = generator.generate_final_thumbnail(
title="Custom Everything",
author="Your Brand",
theme="custom",
custom_template="my_template.jpg",
title_color="#FFFFFF", # White text
author_color="#FFD93D", # Yellow author
enable_triangle=False, # Disable triangle overlay
output_path="fully_custom.jpg"
)
```
#### ๐จ Color Parameter Guide:
- **`title_color`**: Hex color code for the main title text (e.g., "#FF0000" for red)
- **`author_color`**: Hex color code for the author name text (e.g., "#00FF00" for green)
- **Format**: Must use hex format with # prefix (e.g., "#FFFFFF", "#000000")
- **Default Colors**:
- Dark theme: White title (#FFFFFF), Light gray author (#CCCCCC)
- Light theme: Black title (#000000), Dark gray author (#666666)
- Custom theme: Uses provided colors or defaults to theme colors
### Alternative Usage (Advanced)
```python
from youtube_thumbnail_generator import FinalThumbnailGenerator
# Direct class instantiation (for advanced users)
generator = FinalThumbnailGenerator()
# ... same usage as above
```
## ๐ค AI Agent Support (New in v2.5.0)
Special methods designed for AI code assistants and LLMs to quickly understand the library:
```python
from youtube_thumbnail_generator import create_generator
generator = create_generator()
# Get complete usage documentation
docs = generator.readme()
print(docs) # Full library documentation for AI agents
# Get API documentation
api_docs = generator.readme_api()
print(api_docs) # Complete REST API documentation
```
**Perfect for**:
- AI-powered development workflows
- Code generation assistants (GitHub Copilot, Cursor, etc.)
- LLM-based automation tools
- No need to search for external documentation
## ๐ฒ Random Template Generation
Generate thumbnails with random themes, triangle variations, and layouts for creative inspiration!
### Method 1: Using theme="random" (Recommended)
```python
from youtube_thumbnail_generator import create_generator
generator = create_generator()
# Generate with completely random settings
result = generator.generate_final_thumbnail(
title="Your Amazing Title",
author="Your Name",
theme="random", # โจ Magic happens here!
output_path="random_thumbnail.jpg"
)
```
### Method 2: Using theme=None
```python
# Omit theme parameter or set to None - same as theme="random"
result = generator.generate_final_thumbnail(
title="Another Great Title",
author="Creator Name",
theme=None, # Also triggers random generation
output_path="another_random.jpg"
)
```
### Method 3: Direct Random Function
```python
from youtube_thumbnail_generator import generate_random_thumbnail
# Call random function directly (most flexible)
result = generate_random_thumbnail(
title="Direct Random Call",
author="Your Name",
logo_path="logos/logo.png",
right_image_path="images/image.jpg",
output_path="direct_random.jpg"
)
```
### ๐ฏ What Gets Randomized?
- **Theme**: Dark or Light background
- **Triangle**: Enabled/Disabled + Top/Bottom direction
- **Layout**: Normal or Flipped layout
- **Result**: 12 possible combinations for endless variety!
### 2. Interactive Testing Tool
```bash
python initial_test.py
# Enter your title, then press Enter through the defaults for quick testing
```
### 3. API Service
```bash
youtube-thumbnail-api
# Starts service at http://localhost:5002
```
**๐ [Complete API Documentation โ](https://github.com/preangelleo/youtube-thumbnail-generator/blob/main/README_API.md)**
## ๐ Key Parameters
### Logo Requirements
- **Target Size**: 100x100 pixels (automatically processed)
- **โ ๏ธ Important**: For best results, provide a **square logo** (1:1 aspect ratio). Non-square logos will be center-cropped, which may cut off important parts
### Image Processing
- **Input**: Any size image (PNG/JPG)
- **Processing**: Smart resize + center crop
- **Output**: Perfect 900x900 pixels
- **Algorithm**: If min dimension < 900px โ scale up โ center crop
### Theme Options
- **Dark Theme**: Black background + white text + black triangle (default)
- **Light Theme**: White background + black text + white triangle
- **Custom Theme**: Your background + custom colors + optional triangle
- **Random Theme**: `theme="random"` or `theme=None` - automatically picks random combinations! ๐ฒ
### Color Parameters
- **`title_color`** (optional): Hex color code for title text
- Format: `"#RRGGBB"` (e.g., `"#FF6B35"` for orange)
- Default: `"#FFFFFF"` (white) for dark theme, `"#000000"` (black) for light theme
- **`author_color`** (optional): Hex color code for author name text
- Format: `"#RRGGBB"` (e.g., `"#4ECDC4"` for teal)
- Default: `"#CCCCCC"` (light gray) for dark theme, `"#666666"` (dark gray) for light theme
- **Works with all themes**: Colors can be customized for dark, light, custom, or random themes
### Additional Parameters
- **`enable_triangle`** (optional): Control triangle overlay display
- `True`: Force show triangle
- `False`: Force hide triangle
- `None`: Use theme default (default)
## ๐ค AI Title Optimization (Optional)
Fix mixed-language titles automatically with Google Gemini API:
```python
from youtube_thumbnail_generator import create_generator
# Method 1: Pass API key directly
generator = create_generator(gemini_api_key="your_gemini_api_key_here")
# Method 2: Set environment variable (recommended)
# export GEMINI_API_KEY="your_gemini_api_key_here"
generator = create_generator() # Auto-detects from environment
# Optimization happens automatically during generation
result = generator.generate_final_thumbnail(title="Your title", ...)
```
**Examples:**
- โ "AIๆๆฏๆๅ Complete Guide" โ โ
"AIๆๆฏๅฎๆด\nๆๅๆ็จ" (clean Chinese)
- โ "Learn Python็ผ็จ" โ โ
"Learn Python\nProgramming\nComplete Guide" (clean English)
## โจ What's New in v2.4.7
- ๐จ **CRITICAL BUG FIX**: Fixed AI title optimization import error
- ๐ค **AI Feature Working**: Google Gemini title optimization now properly detects installed packages
- โ
**Correct Error Messages**: No more false "google-generativeai package not installed" warnings
- ๐ง **Import Path Fixed**: Corrected relative import path for title_optimizer module
## What's New in v2.4.6
- ๐ฏ **Unified API Experience**: `create_generator()` now promoted as the recommended method
- ๐ **Improved Documentation**: Clear distinction between simple and advanced usage patterns
- ๐ **Better User Experience**: Zero-configuration setup with `create_generator()`
- ๐ **Backward Compatibility**: `FinalThumbnailGenerator()` still available for advanced users
## What's New in v2.4.5
- ๐จ **CRITICAL FIX**: Fixed PyPI package structure - Python modules now properly included
- ๐ฆ **Package Structure Fixed**: Users can now successfully import `from youtube_thumbnail_generator import FinalThumbnailGenerator`
- ๐ง **Proper Package Directory**: All Python files now correctly packaged in `youtube_thumbnail_generator/` directory
- โ
**Import Issues Resolved**: Fixed the critical issue where users couldn't import the library after pip install
## What's New in v2.4.4
- ๐ **Fixed PyPI Documentation Links**: All documentation links now work properly from both GitHub and PyPI
- ๐ **PyPI-Compatible README**: Removed external CDN images that caused broken image icons on PyPI
- ๐ฏ **Better User Navigation**: Clear links to GitHub-hosted documentation from any platform
## What's New in v2.4.3
- ๐ง **Smart Image Processing**: Intelligent resize and center-crop algorithm for perfect 900x900 thumbnails
- ๐ **Configurable Logo Size**: Logo size controlled by LOGO_SIZE constant (100x100px)
- ๐ **CDN-Hosted Examples**: All example images hosted on public CDN (dramatically reduced package size)
- ๐ **Simplified Documentation**: Removed duplicate guides, streamlined user experience
- โ ๏ธ **Logo Recommendations**: Clear guidance for square logo usage
**๐ [Complete Version History โ](https://github.com/preangelleo/youtube-thumbnail-generator/blob/main/CHANGELOG.md)**
## ๐ Documentation
- **[Examples Gallery](https://github.com/preangelleo/youtube-thumbnail-generator/blob/main/EXAMPLES.md)** - All 24 template combinations with CDN-hosted examples
- **[API Documentation](https://github.com/preangelleo/youtube-thumbnail-generator/blob/main/README_API.md)** - Complete REST API reference
- **[Version History](https://github.com/preangelleo/youtube-thumbnail-generator/blob/main/CHANGELOG.md)** - Detailed changelog and feature updates
- **[PyPI Package](https://pypi.org/project/youtube-thumbnail-generator/)** - Install via pip
## ๐จ Important Notes
### Logo Recommendations
- **Best Practice**: Provide square logos (1:1 aspect ratio) to prevent cropping
- **Processing**: All logos automatically converted to 100x100px
- **Non-square handling**: Center-cropped (may cut off important parts)
### Image Processing
- **Any Input Size**: Accepts images of any dimensions
- **Smart Algorithm**: Auto scale-up if needed, then center-crop to 900x900
- **Quality**: High-quality Lanczos resampling for best results
### Language Support
- **Single Language Only**: Use either pure Chinese OR pure English titles
- **Mixed Language Issues**: May cause formatting problems due to different text processing rules
---
## ๐ฏ Best Practices
1. **Use square logos** (1:1 ratio) for optimal results
2. **Single language titles** for best formatting
3. **10-12 Chinese characters** or **7 English words** for optimal length
4. **High-resolution images** for better quality after processing
**Start creating professional YouTube thumbnails now!** ๐ฌโจ
---
**Generated with YouTube Thumbnail Generator v2.4.8** ๐
Raw data
{
"_id": null,
"home_page": "https://github.com/preangelleo/youtube-thumbnail-generator",
"name": "youtube-thumbnail-generator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "youtube, thumbnail, generator, ai, chinese, english, text-processing, image-generation, PIL, graphics, automation",
"author": "Leo Wang",
"author_email": "Leo Wang <me@leowang.net>",
"download_url": "https://files.pythonhosted.org/packages/cf/fb/80e36157e0f443083dcbda40956b7553554c891aa39e9dddeefcd7c1329b/youtube_thumbnail_generator-2.5.2.tar.gz",
"platform": null,
"description": "# YouTube Thumbnail Generator v2.4.8\n\nProfessional YouTube thumbnail generator with enhanced Chinese font bold rendering, AI-powered title optimization, and intelligent text layout system.\n\n**Author**: Leo Wang (https://leowang.net)\n\n[](https://badge.fury.io/py/youtube-thumbnail-generator)\n\ud83d\udce6 [](https://pypi.org/project/youtube-thumbnail-generator/)\n[](https://opensource.org/licenses/MIT)\n\n**\ud83c\udf0d Available on PyPI**: https://pypi.org/project/youtube-thumbnail-generator/ \n**\ud83d\udcc2 GitHub Repository**: https://github.com/preangelleo/youtube-thumbnail-generator\n\n## \ud83d\udccb Core Features\n\n- \u2705 **Intelligent Chinese/English System**: PNG overlay technology, perfect Chinese/English text mixing\n- \u2705 **Smart Line-breaking Algorithm**: Chinese 9 character limits, English 3-line truncation \n- \u2705 **Enhanced Chinese Font Bold**: STHeiti Medium priority + intelligent stroke effects for perfect bold rendering\n- \u2705 **Professional Visual Effects**: Triangle transition integrated into images, text always on top layer\n- \u2705 **Intelligent Image Processing**: Auto square conversion + 900x900 filling with smart resize/crop\n- \u2705 **Multi-endpoint API Support**: Flask RESTful API + Chapter functionality\n- \u2705 **Smart Font Selection**: Chinese PingFang/Founder, English Lexend Bold\n- \u2705 **Three Theme Modes**: Dark (black bg), Light (white bg), Custom (user template)\n- \u2705 **Full Color Customization**: Title color, author color, triangle toggle - all parameterized\n- \u2705 **Dynamic Font Scaling**: Auto font size adjustment based on text length (1-17 characters)\n- \u2705 **YouTube API Ready**: Built-in optimization for YouTube API v3 thumbnail upload compliance\n- \ud83c\udd95 **AI Title Optimization**: Google Gemini-powered mixed-language title optimization (optional)\n- \ud83c\udfb2 **Random Template Generation**: One-click thumbnail creation with 12 random template combinations\n- \ud83e\udd16 **AI Agent Documentation**: Built-in `readme()` and `readme_api()` methods for AI code assistants\n\n## \ud83c\udfa8 Template Examples\n\n### Professional Dark Theme with Triangle\n**Perfect for**: Tech content, gaming, serious topics \n**Features**: Enhanced Chinese bold rendering with intelligent stroke effects\n\n**Examples Available:**\n- **English Example**: Professional dark theme with triangle overlay - perfect for tech content\n- **Chinese Example**: Enhanced Chinese bold rendering with intelligent stroke effects\n\n**[\ud83c\udfa8 View Live Examples \u2192](https://github.com/preangelleo/youtube-thumbnail-generator/blob/main/EXAMPLES.md)**\n\n#### \ud83d\udcd6 **[View Complete Examples Gallery \u2192](https://github.com/preangelleo/youtube-thumbnail-generator/blob/main/EXAMPLES.md)**\n\n**More Examples Available:**\n- **12 Template Combinations**: Professional, Standard, Triangle themes \u00d7 Dark/Light \u00d7 With/Without triangle overlays\n- **Mixed Language Support**: Chinese and English title examples \n- **Enhanced Stroke Effects**: Perfect bold rendering for both dark and light backgrounds\n- **CDN-Hosted**: All examples hosted on fast public CDN for worldwide access\n\n## \ud83d\udca1 Optimal Length Recommendations\n\n### \ud83c\udfaf Best Results Guidelines\nFor the most professional and visually appealing thumbnails:\n\n#### \u26a0\ufe0f **IMPORTANT: Single Language Only**\n**Our system is optimized for single-language titles. Mixed languages may cause formatting issues.**\n\n\ud83d\udeab **Avoid Mixed Languages**:\n- \u274c \"AI\u6280\u672f\u6307\u5357 Complete Guide\" - English words may be improperly split in Chinese mode\n- \u274c \"Complete AI \u6280\u672f\u6307\u5357\" - Chinese characters may break English word spacing\n\n\u2705 **Use Single Languages**:\n- \u2705 \"AI\u6280\u672f\u6307\u5357\u5b8c\u6574\u6559\u7a0b\" - Pure Chinese\n- \u2705 \"Complete AI Technology Guide\" - Pure English\n\n#### \ud83c\udde8\ud83c\uddf3 Chinese Titles\n**Optimal Length: 10-12 characters**\n- **10 characters**: Perfect balance, excellent readability\n- **12 characters**: Maximum recommended, maintains clarity\n- **Pure Chinese Only**: Avoid mixing English words for best results\n\n#### \ud83c\uddfa\ud83c\uddf8 English Titles \n**Optimal Length: 7 words**\n- **7 words**: Perfect for 3-line layout without truncation\n- **Pure English Only**: Avoid mixing Chinese characters for best results\n\n## \ud83d\udce6 Installation\n\n### Quick Install (Recommended)\n```bash\npip install youtube-thumbnail-generator\n```\n\n### With API Service Support\n```bash\npip install \"youtube-thumbnail-generator[api]\"\n```\n\n## \ud83d\ude80 Quick Start\n\n### 1. Simple Python Usage (Recommended)\n```python\nfrom youtube_thumbnail_generator import create_generator\n\n# Create generator with zero configuration (recommended)\ngenerator = create_generator()\n\n# Generate YouTube-ready thumbnail (1280x720, <2MB, optimized for API upload) \nresult = generator.generate_final_thumbnail(\n title=\"Complete AI Technology Guide\",\n author=\"Leo Wang\",\n logo_path=\"logos/your_logo.png\", # \u26a0\ufe0f Use square logo (1:1 ratio) for best results\n right_image_path=\"assets/image.jpg\", # Any size - auto-processed to 900x900\n output_path=\"outputs/thumbnail.jpg\"\n)\n```\n\n### \ud83c\udfa8 Color Customization\n\nCustomize text colors for any theme using hex color codes:\n\n```python\n# Example 1: Custom colors with dark theme\nresult = generator.generate_final_thumbnail(\n title=\"Your Title Here\",\n author=\"Your Name\",\n theme=\"dark\",\n title_color=\"#FF6B35\", # Orange title\n author_color=\"#4ECDC4\", # Teal author name\n output_path=\"custom_colors.jpg\"\n)\n\n# Example 2: Custom colors with light theme\nresult = generator.generate_final_thumbnail(\n title=\"Another Title\",\n author=\"Creator Name\",\n theme=\"light\",\n title_color=\"#2E86AB\", # Blue title\n author_color=\"#A23B72\", # Purple author name\n output_path=\"light_custom.jpg\"\n)\n\n# Example 3: Custom template with custom colors\nresult = generator.generate_final_thumbnail(\n title=\"Custom Everything\",\n author=\"Your Brand\",\n theme=\"custom\",\n custom_template=\"my_template.jpg\",\n title_color=\"#FFFFFF\", # White text\n author_color=\"#FFD93D\", # Yellow author\n enable_triangle=False, # Disable triangle overlay\n output_path=\"fully_custom.jpg\"\n)\n```\n\n#### \ud83c\udfa8 Color Parameter Guide:\n- **`title_color`**: Hex color code for the main title text (e.g., \"#FF0000\" for red)\n- **`author_color`**: Hex color code for the author name text (e.g., \"#00FF00\" for green)\n- **Format**: Must use hex format with # prefix (e.g., \"#FFFFFF\", \"#000000\")\n- **Default Colors**:\n - Dark theme: White title (#FFFFFF), Light gray author (#CCCCCC)\n - Light theme: Black title (#000000), Dark gray author (#666666)\n - Custom theme: Uses provided colors or defaults to theme colors\n\n### Alternative Usage (Advanced)\n```python\nfrom youtube_thumbnail_generator import FinalThumbnailGenerator\n\n# Direct class instantiation (for advanced users)\ngenerator = FinalThumbnailGenerator()\n# ... same usage as above\n```\n\n## \ud83e\udd16 AI Agent Support (New in v2.5.0)\n\nSpecial methods designed for AI code assistants and LLMs to quickly understand the library:\n\n```python\nfrom youtube_thumbnail_generator import create_generator\n\ngenerator = create_generator()\n\n# Get complete usage documentation\ndocs = generator.readme()\nprint(docs) # Full library documentation for AI agents\n\n# Get API documentation\napi_docs = generator.readme_api()\nprint(api_docs) # Complete REST API documentation\n```\n\n**Perfect for**: \n- AI-powered development workflows\n- Code generation assistants (GitHub Copilot, Cursor, etc.)\n- LLM-based automation tools\n- No need to search for external documentation\n\n## \ud83c\udfb2 Random Template Generation\n\nGenerate thumbnails with random themes, triangle variations, and layouts for creative inspiration!\n\n### Method 1: Using theme=\"random\" (Recommended)\n```python\nfrom youtube_thumbnail_generator import create_generator\n\ngenerator = create_generator()\n\n# Generate with completely random settings\nresult = generator.generate_final_thumbnail(\n title=\"Your Amazing Title\",\n author=\"Your Name\",\n theme=\"random\", # \u2728 Magic happens here!\n output_path=\"random_thumbnail.jpg\"\n)\n```\n\n### Method 2: Using theme=None\n```python\n# Omit theme parameter or set to None - same as theme=\"random\"\nresult = generator.generate_final_thumbnail(\n title=\"Another Great Title\",\n author=\"Creator Name\",\n theme=None, # Also triggers random generation\n output_path=\"another_random.jpg\"\n)\n```\n\n### Method 3: Direct Random Function\n```python\nfrom youtube_thumbnail_generator import generate_random_thumbnail\n\n# Call random function directly (most flexible)\nresult = generate_random_thumbnail(\n title=\"Direct Random Call\",\n author=\"Your Name\",\n logo_path=\"logos/logo.png\",\n right_image_path=\"images/image.jpg\", \n output_path=\"direct_random.jpg\"\n)\n```\n\n### \ud83c\udfaf What Gets Randomized?\n- **Theme**: Dark or Light background\n- **Triangle**: Enabled/Disabled + Top/Bottom direction \n- **Layout**: Normal or Flipped layout\n- **Result**: 12 possible combinations for endless variety!\n\n### 2. Interactive Testing Tool\n```bash\npython initial_test.py\n# Enter your title, then press Enter through the defaults for quick testing\n```\n\n### 3. API Service\n```bash\nyoutube-thumbnail-api\n# Starts service at http://localhost:5002\n```\n\n**\ud83d\udcd6 [Complete API Documentation \u2192](https://github.com/preangelleo/youtube-thumbnail-generator/blob/main/README_API.md)**\n\n## \ud83d\udcdd Key Parameters\n\n### Logo Requirements\n- **Target Size**: 100x100 pixels (automatically processed)\n- **\u26a0\ufe0f Important**: For best results, provide a **square logo** (1:1 aspect ratio). Non-square logos will be center-cropped, which may cut off important parts\n\n### Image Processing \n- **Input**: Any size image (PNG/JPG)\n- **Processing**: Smart resize + center crop\n- **Output**: Perfect 900x900 pixels\n- **Algorithm**: If min dimension < 900px \u2192 scale up \u2192 center crop\n\n### Theme Options\n- **Dark Theme**: Black background + white text + black triangle (default)\n- **Light Theme**: White background + black text + white triangle \n- **Custom Theme**: Your background + custom colors + optional triangle\n- **Random Theme**: `theme=\"random\"` or `theme=None` - automatically picks random combinations! \ud83c\udfb2\n\n### Color Parameters\n- **`title_color`** (optional): Hex color code for title text\n - Format: `\"#RRGGBB\"` (e.g., `\"#FF6B35\"` for orange)\n - Default: `\"#FFFFFF\"` (white) for dark theme, `\"#000000\"` (black) for light theme\n- **`author_color`** (optional): Hex color code for author name text\n - Format: `\"#RRGGBB\"` (e.g., `\"#4ECDC4\"` for teal)\n - Default: `\"#CCCCCC\"` (light gray) for dark theme, `\"#666666\"` (dark gray) for light theme\n- **Works with all themes**: Colors can be customized for dark, light, custom, or random themes\n\n### Additional Parameters\n- **`enable_triangle`** (optional): Control triangle overlay display\n - `True`: Force show triangle\n - `False`: Force hide triangle\n - `None`: Use theme default (default)\n\n## \ud83e\udd16 AI Title Optimization (Optional)\n\nFix mixed-language titles automatically with Google Gemini API:\n\n```python\nfrom youtube_thumbnail_generator import create_generator\n\n# Method 1: Pass API key directly\ngenerator = create_generator(gemini_api_key=\"your_gemini_api_key_here\")\n\n# Method 2: Set environment variable (recommended)\n# export GEMINI_API_KEY=\"your_gemini_api_key_here\"\ngenerator = create_generator() # Auto-detects from environment\n\n# Optimization happens automatically during generation\nresult = generator.generate_final_thumbnail(title=\"Your title\", ...)\n```\n\n**Examples:**\n- \u274c \"AI\u6280\u672f\u6307\u5357 Complete Guide\" \u2192 \u2705 \"AI\u6280\u672f\u5b8c\u6574\\n\u6307\u5357\u6559\u7a0b\" (clean Chinese)\n- \u274c \"Learn Python\u7f16\u7a0b\" \u2192 \u2705 \"Learn Python\\nProgramming\\nComplete Guide\" (clean English)\n\n## \u2728 What's New in v2.4.7\n\n- \ud83d\udea8 **CRITICAL BUG FIX**: Fixed AI title optimization import error\n- \ud83e\udd16 **AI Feature Working**: Google Gemini title optimization now properly detects installed packages\n- \u2705 **Correct Error Messages**: No more false \"google-generativeai package not installed\" warnings \n- \ud83d\udd27 **Import Path Fixed**: Corrected relative import path for title_optimizer module\n\n## What's New in v2.4.6\n\n- \ud83c\udfaf **Unified API Experience**: `create_generator()` now promoted as the recommended method\n- \ud83d\udcda **Improved Documentation**: Clear distinction between simple and advanced usage patterns\n- \ud83d\ude80 **Better User Experience**: Zero-configuration setup with `create_generator()` \n- \ud83d\udd04 **Backward Compatibility**: `FinalThumbnailGenerator()` still available for advanced users\n\n## What's New in v2.4.5\n\n- \ud83d\udea8 **CRITICAL FIX**: Fixed PyPI package structure - Python modules now properly included\n- \ud83d\udce6 **Package Structure Fixed**: Users can now successfully import `from youtube_thumbnail_generator import FinalThumbnailGenerator`\n- \ud83d\udd27 **Proper Package Directory**: All Python files now correctly packaged in `youtube_thumbnail_generator/` directory\n- \u2705 **Import Issues Resolved**: Fixed the critical issue where users couldn't import the library after pip install\n\n## What's New in v2.4.4\n\n- \ud83d\udd17 **Fixed PyPI Documentation Links**: All documentation links now work properly from both GitHub and PyPI\n- \ud83d\udcd6 **PyPI-Compatible README**: Removed external CDN images that caused broken image icons on PyPI\n- \ud83c\udfaf **Better User Navigation**: Clear links to GitHub-hosted documentation from any platform\n\n## What's New in v2.4.3\n\n- \ud83e\udde0 **Smart Image Processing**: Intelligent resize and center-crop algorithm for perfect 900x900 thumbnails\n- \ud83d\udccf **Configurable Logo Size**: Logo size controlled by LOGO_SIZE constant (100x100px) \n- \ud83c\udf10 **CDN-Hosted Examples**: All example images hosted on public CDN (dramatically reduced package size)\n- \ud83d\udcd6 **Simplified Documentation**: Removed duplicate guides, streamlined user experience\n- \u26a0\ufe0f **Logo Recommendations**: Clear guidance for square logo usage\n\n**\ud83d\udccb [Complete Version History \u2192](https://github.com/preangelleo/youtube-thumbnail-generator/blob/main/CHANGELOG.md)**\n\n## \ud83d\udcd6 Documentation\n\n- **[Examples Gallery](https://github.com/preangelleo/youtube-thumbnail-generator/blob/main/EXAMPLES.md)** - All 24 template combinations with CDN-hosted examples\n- **[API Documentation](https://github.com/preangelleo/youtube-thumbnail-generator/blob/main/README_API.md)** - Complete REST API reference \n- **[Version History](https://github.com/preangelleo/youtube-thumbnail-generator/blob/main/CHANGELOG.md)** - Detailed changelog and feature updates\n- **[PyPI Package](https://pypi.org/project/youtube-thumbnail-generator/)** - Install via pip\n\n## \ud83d\udea8 Important Notes\n\n### Logo Recommendations\n- **Best Practice**: Provide square logos (1:1 aspect ratio) to prevent cropping\n- **Processing**: All logos automatically converted to 100x100px\n- **Non-square handling**: Center-cropped (may cut off important parts)\n\n### Image Processing \n- **Any Input Size**: Accepts images of any dimensions\n- **Smart Algorithm**: Auto scale-up if needed, then center-crop to 900x900\n- **Quality**: High-quality Lanczos resampling for best results\n\n### Language Support\n- **Single Language Only**: Use either pure Chinese OR pure English titles\n- **Mixed Language Issues**: May cause formatting problems due to different text processing rules\n\n---\n\n## \ud83c\udfaf Best Practices\n\n1. **Use square logos** (1:1 ratio) for optimal results\n2. **Single language titles** for best formatting\n3. **10-12 Chinese characters** or **7 English words** for optimal length\n4. **High-resolution images** for better quality after processing\n\n**Start creating professional YouTube thumbnails now!** \ud83c\udfac\u2728\n\n---\n\n**Generated with YouTube Thumbnail Generator v2.4.8** \ud83d\ude80\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Professional YouTube thumbnail generator with enhanced Chinese font bold rendering and intelligent text processing",
"version": "2.5.2",
"project_urls": {
"Bug Reports": "https://github.com/preangelleo/youtube-thumbnail-generator/issues",
"Documentation": "https://github.com/preangelleo/youtube-thumbnail-generator#readme",
"Homepage": "https://github.com/preangelleo/youtube-thumbnail-generator",
"Repository": "https://github.com/preangelleo/youtube-thumbnail-generator"
},
"split_keywords": [
"youtube",
" thumbnail",
" generator",
" ai",
" chinese",
" english",
" text-processing",
" image-generation",
" pil",
" graphics",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c76c1b16d3584d510ac70f4a15f4651f750c8fa74e3de5628fe4ce9ca531762d",
"md5": "d72c969a4cb6854a7ca076645e876f94",
"sha256": "81129f7130a4797b88d932eb1fc34fb86c9f6e30486cddfec66c76cc5f2252e5"
},
"downloads": -1,
"filename": "youtube_thumbnail_generator-2.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d72c969a4cb6854a7ca076645e876f94",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 66565,
"upload_time": "2025-08-09T12:04:37",
"upload_time_iso_8601": "2025-08-09T12:04:37.520175Z",
"url": "https://files.pythonhosted.org/packages/c7/6c/1b16d3584d510ac70f4a15f4651f750c8fa74e3de5628fe4ce9ca531762d/youtube_thumbnail_generator-2.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cffb80e36157e0f443083dcbda40956b7553554c891aa39e9dddeefcd7c1329b",
"md5": "6009567e2a9e7a776e04d672bca6786b",
"sha256": "5253dc16a41df4c4770b05b3e0ec04cd1c5ec0468fc2d68430b2a9349213668d"
},
"downloads": -1,
"filename": "youtube_thumbnail_generator-2.5.2.tar.gz",
"has_sig": false,
"md5_digest": "6009567e2a9e7a776e04d672bca6786b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 77153,
"upload_time": "2025-08-09T12:04:38",
"upload_time_iso_8601": "2025-08-09T12:04:38.855891Z",
"url": "https://files.pythonhosted.org/packages/cf/fb/80e36157e0f443083dcbda40956b7553554c891aa39e9dddeefcd7c1329b/youtube_thumbnail_generator-2.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-09 12:04:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "preangelleo",
"github_project": "youtube-thumbnail-generator",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "Flask",
"specs": [
[
"==",
"2.3.3"
]
]
},
{
"name": "Flask-CORS",
"specs": [
[
"==",
"4.0.0"
]
]
},
{
"name": "Pillow",
"specs": [
[
"==",
"10.0.1"
]
]
},
{
"name": "google-generativeai",
"specs": [
[
">=",
"0.3.0"
]
]
}
],
"lcname": "youtube-thumbnail-generator"
}
JSON
