# YouTube Thumbnail Generator 🎨
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://www.docker.com/)
[](https://ai.google.dev/)
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
```bash
# 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
```python
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
```bash
# 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
```bash
# 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
```python
# 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](docs/DOCUMENTATION.md)
For usage examples, see [examples/example_usage.py](examples/example_usage.py)
## 🐳 Docker
```bash
# 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.
```json
{
"text": "Amazing Tutorial",
"enable_ai_optimization": true,
"target_language": "en",
"background_type": "gradient",
"font_size": 80
}
```
### POST /batch
Generate multiple thumbnails in one request.
```json
{
"texts": ["Tutorial 1", "Tutorial 2"],
"enable_ai_optimization": false,
"target_language": "zh"
}
```
### POST /optimize-text
Optimize text using AI (requires API key).
```json
{
"text": "Basic Python Tutorial",
"target_language": "en",
"style": "engaging"
}
```
### POST /detect-language
Detect the language of text.
```json
{
"text": "Python编程教程"
}
```
## 🔧 Configuration
Create a `.env` file:
```env
# 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](LICENSE) file for details
## 🤝 Contributing
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## 📧 Support
For issues and questions, please use the [GitHub Issues](https://github.com/preangelleo/youtube-thumbnail-generator/issues) page.
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.9",
"maintainer_email": null,
"keywords": "youtube, thumbnail, generator, ai, gemini, image, processing",
"author": "preangelleo",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ed/c0/768cd8bb180df0faf3af5956646ef2a03303d529b78b81ea4df2c20c3892/youtube_thumbnail_generator-2.6.4.tar.gz",
"platform": null,
"description": "# YouTube Thumbnail Generator \ud83c\udfa8\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n[](https://www.docker.com/)\n[](https://ai.google.dev/)\n\nA 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.\n\n## \u2728 Features\n\n- **Customizable Backgrounds**: Solid colors, gradients, or image backgrounds\n- **Multiple Font Support**: Various fonts and styles\n- **AI Text Optimization**: Optional Gemini AI integration for better text\n- **Multi-Language Support**: Automatic language detection or manual specification (supports `en`/`english`, `zh`/`chinese`)\n- **Flexible Layouts**: Multiple text positions and sizes\n- **High Quality Output**: 1280x720 HD thumbnails\n- **Docker Support**: Easy deployment with Docker\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/preangelleo/youtube-thumbnail-generator.git\ncd youtube-thumbnail-generator\n\n# Install dependencies\npip install -r requirements.txt\n\n# Or install from PyPI\npip install youtube-thumbnail-generator\n```\n\n### Basic Usage\n\n#### Python Library\n\n```python\nfrom src.thumbnail_generator import ThumbnailGenerator\n\n# Create generator instance\ngenerator = ThumbnailGenerator()\n\n# Generate a simple thumbnail\nthumbnail = generator.generate(\n text=\"Amazing Python Tutorial\",\n output_path=\"thumbnail.png\"\n)\n```\n\n#### CLI Usage\n\n```bash\n# Basic thumbnail\nyoutube-thumbnail \"Amazing Python Tutorial\" -o thumbnail.png\n\n# With AI optimization\nyoutube-thumbnail \"Python Tutorial\" --enable-ai --source-language en\n\n# With translation (Chinese to English)\nyoutube-thumbnail \"Python\u7f16\u7a0b\" --enable-ai --source-language zh --target-language en\n\n# Custom styling\nyoutube-thumbnail \"Tutorial\" --font-size 100 --bg-color1 \"#FF0000\"\n```\n\n#### REST API\n\n```bash\n# Start the API server\npython -m src.api\n\n# Generate thumbnail via API\ncurl -X POST http://localhost:5000/generate \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"text\": \"Amazing Tutorial\",\n \"enable_ai_optimization\": true,\n \"source_language\": \"en\" // Skip auto-detection\n }'\n```\n\n### With AI Optimization\n\n```python\n# Enable AI optimization with explicit control\ngenerator = ThumbnailGenerator(\n gemini_api_key=\"your-api-key\",\n enable_ai_optimization=True # Explicit toggle\n)\n\n# Generate with explicit source language (skip detection)\n# Supports both ISO codes and full names\nthumbnail = generator.generate(\n text=\"Python Tutorial for Beginners\",\n source_language=\"en\", # or \"english\" - Skip detection, specify it's English\n enable_ai_optimization=True,\n output_path=\"ai_thumbnail.png\"\n)\n\n# Generate with translation (requires AI)\nthumbnail = generator.generate(\n text=\"Python\u7f16\u7a0b\u6559\u7a0b\",\n source_language=\"chinese\", # or \"zh\" - Input is Chinese\n target_language=\"english\", # or \"en\" - Translate to English\n enable_ai_optimization=True, # Required for translation\n output_path=\"translated_thumbnail.png\"\n)\n```\n\n## \ud83d\udcda Documentation\n\nFor detailed documentation, see [docs/DOCUMENTATION.md](docs/DOCUMENTATION.md)\n\nFor usage examples, see [examples/example_usage.py](examples/example_usage.py)\n\n## \ud83d\udc33 Docker\n\n```bash\n# Pull from Docker Hub\ndocker pull preangelleo/youtube-thumbnail-generator:latest\n\n# Run the API server\ndocker run -p 5000:5000 \\\n -e GEMINI_API_KEY=your-key \\\n -e ENABLE_AI_OPTIMIZATION=true \\\n preangelleo/youtube-thumbnail-generator\n\n# Or build locally\ndocker build -t youtube-thumbnail-generator .\ndocker run -p 5000:5000 youtube-thumbnail-generator\n```\n\n## \ud83c\udf10 API Endpoints\n\n### POST /generate\nGenerate a single thumbnail with full parameter control.\n\n```json\n{\n \"text\": \"Amazing Tutorial\",\n \"enable_ai_optimization\": true,\n \"target_language\": \"en\",\n \"background_type\": \"gradient\",\n \"font_size\": 80\n}\n```\n\n### POST /batch\nGenerate multiple thumbnails in one request.\n\n```json\n{\n \"texts\": [\"Tutorial 1\", \"Tutorial 2\"],\n \"enable_ai_optimization\": false,\n \"target_language\": \"zh\"\n}\n```\n\n### POST /optimize-text\nOptimize text using AI (requires API key).\n\n```json\n{\n \"text\": \"Basic Python Tutorial\",\n \"target_language\": \"en\",\n \"style\": \"engaging\"\n}\n```\n\n### POST /detect-language\nDetect the language of text.\n\n```json\n{\n \"text\": \"Python\u7f16\u7a0b\u6559\u7a0b\"\n}\n```\n\n## \ud83d\udd27 Configuration\n\nCreate a `.env` file:\n\n```env\n# Optional: Gemini AI API Key\nGEMINI_API_KEY=your-api-key-here\n\n# Optional: Enable AI by default\nENABLE_AI_OPTIMIZATION=true\n\n# Optional: Default language\nDEFAULT_LANGUAGE=en\n```\n\n## \ud83d\udcdd License\n\nMIT License - see [LICENSE](LICENSE) file for details\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## \ud83d\udce7 Support\n\nFor issues and questions, please use the [GitHub Issues](https://github.com/preangelleo/youtube-thumbnail-generator/issues) page.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A powerful YouTube thumbnail generator with AI text optimization and multi-language support",
"version": "2.6.4",
"project_urls": {
"Bug Reports": "https://github.com/preangelleo/youtube-thumbnail-generator/issues",
"Documentation": "https://github.com/preangelleo/youtube-thumbnail-generator/docs",
"Homepage": "https://github.com/preangelleo/youtube-thumbnail-generator",
"Source": "https://github.com/preangelleo/youtube-thumbnail-generator"
},
"split_keywords": [
"youtube",
" thumbnail",
" generator",
" ai",
" gemini",
" image",
" processing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f22baa23a91b6516ab6c511d402ee400608984572f7de2848c117009cf5c0f39",
"md5": "2d66fb1329f151e60edfa2ce7369e8e7",
"sha256": "6a10118c6f728bcbe92b9392ef16329b380d2ff76bc8f486fe84c50e8ea652e1"
},
"downloads": -1,
"filename": "youtube_thumbnail_generator-2.6.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2d66fb1329f151e60edfa2ce7369e8e7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 44656,
"upload_time": "2025-08-23T08:16:04",
"upload_time_iso_8601": "2025-08-23T08:16:04.634349Z",
"url": "https://files.pythonhosted.org/packages/f2/2b/aa23a91b6516ab6c511d402ee400608984572f7de2848c117009cf5c0f39/youtube_thumbnail_generator-2.6.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "edc0768cd8bb180df0faf3af5956646ef2a03303d529b78b81ea4df2c20c3892",
"md5": "b8bced98d9918b9aba1638976f58f618",
"sha256": "cf558d181a02a70a38eee878af077c7ae52947ed7fb29381596c55e2c76b5129"
},
"downloads": -1,
"filename": "youtube_thumbnail_generator-2.6.4.tar.gz",
"has_sig": false,
"md5_digest": "b8bced98d9918b9aba1638976f58f618",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 46251,
"upload_time": "2025-08-23T08:16:05",
"upload_time_iso_8601": "2025-08-23T08:16:05.842663Z",
"url": "https://files.pythonhosted.org/packages/ed/c0/768cd8bb180df0faf3af5956646ef2a03303d529b78b81ea4df2c20c3892/youtube_thumbnail_generator-2.6.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-23 08:16:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "preangelleo",
"github_project": "youtube-thumbnail-generator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "Pillow",
"specs": [
[
">=",
"10.0.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.24.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "Flask",
"specs": [
[
">=",
"2.3.0"
]
]
},
{
"name": "flask-cors",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "google-generativeai",
"specs": [
[
">=",
"0.3.0"
]
]
},
{
"name": "langdetect",
"specs": [
[
">=",
"1.0.9"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.4.0"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
">=",
"4.1.0"
]
]
},
{
"name": "black",
"specs": [
[
">=",
"23.7.0"
]
]
},
{
"name": "flake8",
"specs": [
[
">=",
"6.1.0"
]
]
},
{
"name": "mypy",
"specs": [
[
">=",
"1.5.0"
]
]
}
],
"lcname": "youtube-thumbnail-generator"
}
JSON
