# Ghost Blog Smart
🚀 **A comprehensive solution for Ghost CMS blog management with AI-powered features**
Available as both a **Python Package** and **REST API** with multiple deployment options including Docker, local installation, and PyPI package.
[](https://badge.fury.io/py/ghost-blog-smart)
[](https://hub.docker.com/r/betashow/ghost-blog-smart-api)
[](https://github.com/preangelleo/ghost-blog-smart/actions)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
## 🎯 **Choose Your Setup Method**
| Method | Best For | Example Files | Documentation Section |
|--------|----------|---------------|----------------------|
| **🐳 Docker API** | Production deployment, quick testing | `example_usage_API.js` | [Docker Deployment](#-docker-deployment) |
| **🐍 Python Package** | Python developers, scripting | `example_usage.py` | [Python Package](#-python-package-usage) |
| **🌐 Local API** | Development, customization | `example_usage_API.js` | [Local API Setup](#-local-api-development) |
| **📦 PyPI Install** | Simple Python integration | `example_usage.py` | [PyPI Installation](#-pypi-installation) |
## 📖 **Table of Contents**
### 🚀 **Getting Started**
- [🎯 Choose Your Setup Method](#-choose-your-setup-method)
- [🐳 Docker Deployment](#-docker-deployment)
- [🐍 Python Package Usage](#-python-package-usage)
- [📦 PyPI Installation](#-pypi-installation)
- [🌐 Local API Development](#-local-api-development)
### 📚 **Usage Examples**
- [💻 Python Examples (example_usage.py)](#-python-examples-example_usagepy)
- [🌐 Node.js API Examples (example_usage_API.js)](#-nodejs-api-examples-example_usage_apijs)
### 📖 **Documentation**
- [✨ Features](#-features)
- [🔧 REST API Reference](#-rest-api-reference)
- [⏱️ Performance & Timeout Guidelines](#️-performance--timeout-guidelines)
- [🧪 Testing](#-testing)
---
## 🐳 **Docker Deployment**
> **Recommended for:** Production environments, quick testing, isolation
>
> **Example File:** `example_usage_API.js` (Node.js client for REST API)
### Quick Start
```bash
# Pull and run the pre-built Docker image
docker pull betashow/ghost-blog-smart-api:latest
# Run with your credentials
docker run -d \
-p 5000:5000 \
-e GHOST_ADMIN_API_KEY="your_key_id:your_secret_key" \
-e GHOST_API_URL="https://your-ghost-site.com" \
-e GEMINI_API_KEY="your_gemini_key" \
-e REPLICATE_API_TOKEN="r8_your_replicate_token" \
-e FLASK_API_KEY="your_secure_api_key" \
--name ghost-blog-api \
betashow/ghost-blog-smart-api:latest
# Test the API
curl http://localhost:5000/health
```
### Docker Compose
```yaml
version: '3.8'
services:
ghost-blog-smart-api:
image: betashow/ghost-blog-smart-api:latest
ports:
- "5000:5000"
environment:
- GHOST_ADMIN_API_KEY=your_key_id:your_secret_key
- GHOST_API_URL=https://your-ghost-site.com
- GEMINI_API_KEY=your_gemini_key
- REPLICATE_API_TOKEN=r8_your_replicate_token
- FLASK_API_KEY=your_secure_api_key
```
**Next Steps:**
- Use `example_usage_API.js` for Node.js integration
- Follow [Node.js API Examples](#-nodejs-api-examples-example_usage_apijs) section
---
## 🐍 **Python Package Usage**
> **Recommended for:** Python developers, scripting, direct integration
>
> **Example File:** `example_usage.py` (Pure Python usage)
### Installation
```bash
pip install ghost-blog-smart
```
### Basic Usage
```python
from ghost_blog_smart import smart_blog_gateway
# Smart Gateway Method (Recommended)
result = smart_blog_gateway(
"AI healthcare benefits: faster diagnosis, better accuracy, cost reduction",
status="published"
)
if result['success']:
print(f"Post created: {result['url']}")
```
**Next Steps:**
- Follow examples in `example_usage.py`
- See [Python Examples](#-python-examples-example_usagepy) section
---
## 📦 **PyPI Installation**
> **Recommended for:** Simple Python projects, minimal setup
```bash
# Install from PyPI
pip install ghost-blog-smart
# Use directly in your Python code
from ghost_blog_smart import create_ghost_blog_post, smart_blog_gateway
```
Create `.env` file with your credentials:
```env
GHOST_ADMIN_API_KEY=your_admin_api_key_id:your_secret_key_here
GHOST_API_URL=https://your-ghost-site.com
GEMINI_API_KEY=your_gemini_api_key_here
REPLICATE_API_TOKEN=r8_your_replicate_api_token_here
```
---
## 🌐 **Local API Development**
> **Recommended for:** Development, customization, testing
>
> **Example Files:** `example_usage_API.js` (Node.js client) + Local Flask API
### Setup
```bash
# Clone the repository
git clone https://github.com/preangelleo/ghost_blog_smart.git
cd ghost_blog_smart
# Install dependencies
pip install -r requirements.txt
pip install -r requirements-api.txt
pip install -e .
# Set up environment variables
cp .env.example .env
# Edit .env with your credentials
# Run the Flask API
python app.py
```
**API runs on:** `http://localhost:5000`
**Next Steps:**
- Use `example_usage_API.js` to test your local API
- Follow [Node.js API Examples](#-nodejs-api-examples-example_usage_apijs) section
---
## 💻 **Python Examples (example_usage.py)**
**For:** Python Package usage, PyPI installation, direct Python integration
### Key Examples from `example_usage.py`:
#### Smart Gateway (AI-Enhanced Creation)
```python
from ghost_blog_smart import smart_blog_gateway
result = smart_blog_gateway(
"Write about AI benefits in healthcare: faster diagnosis, better accuracy",
status="published",
preferred_language="English"
)
```
#### Traditional Method
```python
from ghost_blog_smart import create_ghost_blog_post
result = create_ghost_blog_post(
title="My Blog Post",
content="Post content in **Markdown**",
excerpt="Brief summary",
tags=["Tutorial", "AI"],
status="published",
use_generated_feature_image=True,
prefer_flux=True
)
```
#### Blog Management
```python
from ghost_blog_smart import get_ghost_posts, update_ghost_post, delete_ghost_post
# Get posts
posts = get_ghost_posts(limit=5, status='published')
# Update post
update_ghost_post(post_id="abc123", featured=True)
# Delete post
delete_ghost_post(post_id="abc123")
```
**📁 Complete examples available in:** [`example_usage.py`](./example_usage.py)
---
## 🌐 **Node.js API Examples (example_usage_API.js)**
**For:** Docker deployment, local API server, REST API integration
### Prerequisites
```bash
npm install axios # HTTP client for API calls
```
### Key Examples from `example_usage_API.js`:
#### Configuration
```javascript
const CONFIG = {
baseUrl: 'http://localhost:5000',
apiKey: 'your_secure_api_key',
timeout: 300000, // 5 minutes for image generation
imageTimeout: 300000, // Extended timeout for image endpoints
standardTimeout: 30000, // Standard timeout for other endpoints
};
```
#### Create Blog Post via API
```javascript
const postData = {
title: "My API Blog Post",
content: "Post content in **Markdown**",
excerpt: "Brief summary",
tags: ["API", "Node.js"],
status: "published",
use_generated_feature_image: true,
prefer_flux: true,
image_aspect_ratio: "16:9"
};
const response = await api.post('/api/posts', postData);
```
#### Smart Create via API
```javascript
const smartData = {
user_input: "Write about JavaScript testing frameworks: Jest vs Mocha vs Cypress",
status: "draft",
preferred_language: "English"
};
const response = await api.post('/api/smart-create', smartData);
```
#### Running Tests
```bash
# Run all endpoint tests
node example_usage_API.js
# Run specific test
node example_usage_API.js health
# Run with custom timeout (5 minutes for image generation)
node example_usage_API.js --timeout 300000
# Production mode (creates real posts)
node example_usage_API.js --production
```
**📁 Complete examples available in:** [`example_usage_API.js`](./example_usage_API.js)
---
## ✨ **Features**
### 🤖 **Smart AI Gateway**
- **Intelligent Routing** - Automatically determines if content needs rewriting
- **Structured Output** - Uses Gemini's structured output for consistent formatting
- **Function Calling** - Leverages Gemini function calling for smart decision making
- **Auto Enhancement** - Transforms scattered ideas into complete blog posts
- **Missing Component Detection** - Automatically generates titles, excerpts, and tags
### 🎨 **Dual AI Image Generation**
- **🔥 Replicate Flux-dev**: Ultra-fast generation (3-7 seconds), photorealistic images, WebP format
- **🏔️ Google Imagen-4**: Professional quality, advanced prompt understanding, PNG format
- **Automatic Fallback System**: Intelligent provider switching for maximum reliability
- **Provider Selection**: Choose your preferred provider or let the system decide
- **Multiple Aspect Ratios**: 16:9, 1:1, 9:16, 4:3, 3:2 support
### 📝 **Content Management**
- **Smart Content Formatting** - Auto-format plain text to beautiful Markdown with Gemini AI
- **YouTube-Style Slugs** - Generate 11-character slugs like YouTube video IDs
- **Multi-language Support** - Chinese to Pinyin conversion for slugs
- **Language Translation** - Auto-translate content to any target language
- **Flexible Image Handling** - Support for URLs, local files, base64 data
### 📊 **Blog Management**
- **Advanced Listing** - Get posts with powerful filtering options
- **Search & Query** - Full-text search across all posts
- **Date Range Filtering** - Find posts by publication/creation date
- **Update & Delete** - Modify or remove posts with comprehensive options
- **Batch Operations** - Process multiple posts efficiently
- **Detailed Analytics** - Get complete post details and summaries
---
## 🔧 **REST API Reference**
### **Base URL Structure**
```
http://localhost:5000/ # API information
http://localhost:5000/health # Health check
http://localhost:5000/api/ # All blog endpoints
```
### **Authentication**
All API endpoints (except `/` and `/health`) require authentication:
```bash
curl -H "X-API-Key: your_api_key" http://localhost:5000/api/posts
```
### **Standard Response Format**
```json
{
"success": true,
"timestamp": "2024-01-01T00:00:00.000000Z",
"data": {
// Response data here
}
}
```
### **⚠️ TIMEOUT CONFIGURATION NOTICE**
- **Image Generation Endpoints**: `/api/posts` (with `use_generated_feature_image: true`) and `/api/posts/{id}/image` require extended timeouts
- **Recommended Client Timeout**: **5 minutes (300 seconds)** minimum
- **Typical Response Times**: 60-300 seconds for image generation
- **Without Images**: Standard 30-second timeout is sufficient
### **📝 Core Endpoints**
#### Create Blog Post ⚠️ **Extended Timeout for Images**
```bash
POST /api/posts
Content-Type: application/json
X-API-Key: your_api_key
{
"title": "My Blog Post",
"content": "Post content in **Markdown**",
"excerpt": "Brief summary",
"tags": ["Tag1", "Tag2"],
"status": "published",
"use_generated_feature_image": true,
"prefer_flux": true,
"image_aspect_ratio": "16:9"
}
```
**⏱️ Important:** When `use_generated_feature_image: true` is used, generation can take 60-300 seconds. Set client timeout to at least **5 minutes (300 seconds)**.
#### Smart Create (AI-Enhanced)
```bash
POST /api/smart-create
Content-Type: application/json
X-API-Key: your_api_key
{
"user_input": "Write about AI benefits in healthcare",
"status": "draft",
"preferred_language": "English"
}
```
#### Get Posts
```bash
GET /api/posts?limit=5&status=published&featured=true
X-API-Key: your_api_key
```
#### Update Post Image ⚠️ **High Timeout Required**
```bash
PUT /api/posts/{post_id}/image
Content-Type: application/json
X-API-Key: your_api_key
{
"use_generated_feature_image": true,
"prefer_imagen": true,
"image_aspect_ratio": "16:9"
}
```
**⏱️ Important:** Image generation endpoints can take 60-300 seconds to complete. Set client timeout to at least **5 minutes (300 seconds)** for reliable operation.
### **📋 Complete Endpoint List**
| Endpoint | Method | Description | Auth Required | Timeout |
|----------|--------|-------------|---------------|---------|
| `/` | GET | API information | ❌ | Standard |
| `/health` | GET | Health check | ❌ | Standard |
| `/api/posts` | POST | Create blog post | ✅ | **Extended*** |
| `/api/smart-create` | POST | AI-enhanced creation | ✅ | Standard |
| `/api/posts` | GET | List posts | ✅ | Standard |
| `/api/posts/advanced` | GET | Advanced search | ✅ | Standard |
| `/api/posts/{id}` | GET | Get post details | ✅ | Standard |
| `/api/posts/{id}` | PUT/PATCH | Update post | ✅ | Standard |
| `/api/posts/{id}` | DELETE | Delete post | ✅ | Standard |
| `/api/posts/{id}/image` | PUT | Update post image | ✅ | **Extended*** |
| `/api/posts/summary` | GET | Posts summary | ✅ | Standard |
| `/api/posts/batch-details` | POST | Batch get details | ✅ | Standard |
| `/api/posts/search/by-date-pattern` | GET | Date search | ✅ | Standard |
**\*Extended = 5 minutes (300 seconds) for image generation**
---
## ⏱️ **Performance & Timeout Guidelines**
### **Image Generation Performance**
- **Replicate Flux**: 3-7 seconds (ultra-fast)
- **Google Imagen**: 10-15 seconds (professional quality)
- **Upload & Processing**: Additional 45-60 seconds
- **Total Time**: 60-300 seconds for complete image generation
### **Recommended Client Timeouts**
```javascript
// For endpoints WITH image generation
const imageApiTimeout = 300000; // 5 minutes
// For endpoints WITHOUT image generation
const standardTimeout = 30000; // 30 seconds
```
### **Production Testing Results**
✅ **All endpoints functional**
⚠️ **Image generation requires extended timeout**
💡 **Recommendation**: Always set 5-minute timeout for image endpoints
---
## 🧪 **Testing**
### **Python Package Testing**
```bash
# Set test mode to avoid actual posting
python example_usage.py # Uses is_test=True by default
```
### **API Testing (Docker/Local)**
```bash
# Comprehensive test suite
node example_usage_API.js
# Individual endpoint tests
node example_usage_API.js health
node example_usage_API.js create
node example_usage_API.js smart
# Production mode (creates real posts)
node example_usage_API.js --production
# Extended timeout for image generation
node example_usage_API.js --timeout 300000
```
### **Docker Testing Guide**
See [`TESTING_GUIDE.md`](./TESTING_GUIDE.md) for comprehensive Docker testing instructions.
---
## 📁 **Project Structure**
```
ghost-blog-smart/
├── ghost_blog_smart/ # Main Python package
│ ├── __init__.py # Package exports
│ ├── main_functions.py # Core API functions
│ ├── smart_gateway.py # AI-powered routing
│ ├── post_management.py # Advanced management
│ └── *.py # Other modules
├── example_usage.py # 🐍 Python package examples
├── example_usage_API.js # 🌐 Node.js API client examples
├── app.py # 🚀 Flask REST API server
├── Dockerfile # 🐳 Docker configuration
├── docker-compose.yml # 🐳 Docker Compose setup
├── requirements.txt # Python dependencies
├── setup.py # PyPI package setup
├── TESTING_GUIDE.md # 🧪 Docker testing instructions
└── README.md # 📖 This documentation
```
---
## 🎨 **Image Generation Comparison**
| Feature | Replicate Flux-dev | Google Imagen-4 |
|---------|-------------------|-----------------|
| **Speed** | ⚡ Ultra-fast (3-7s) | 🐢 Moderate (10-15s) |
| **Quality** | 🔥 Photorealistic | 🏔️ Professional |
| **Format** | 📁 WebP (smaller) | 📁 PNG (lossless) |
| **Cost** | 💰 Pay-per-use | 💰 API quota based |
| **Best For** | Realistic scenes, portraits | Abstract concepts, artistic |
**Supported Aspect Ratios:**
- `16:9` - Widescreen (1920x1080) - **Default**
- `1:1` - Square (1024x1024) - Great for social media
- `9:16` - Portrait (1080x1920) - Mobile-optimized
- `4:3` - Traditional (1024x768) - Classic photo ratio
- `3:2` - DSLR (1536x1024) - Professional photography
---
## 📋 **Prerequisites**
- Python 3.8+
- Ghost CMS instance with Admin API access
- **Image Generation** (choose one or both):
- Google Gemini API key (for Imagen-4 generation)
- Replicate API token (for Flux-dev generation)
---
## 🤝 **Contributing**
Contributions are welcome! Please feel free to submit a Pull Request.
---
## 📄 **License**
MIT License - see LICENSE file for details
---
## 🙏 **Acknowledgments**
- Ghost CMS for the excellent blogging platform
- Google Gemini & Imagen for AI capabilities
- Replicate for ultra-fast Flux generation
- The open-source community
---
## 📞 **Support**
For issues or questions, please open an issue on GitHub.
---
**Made with ❤️ for the Ghost CMS community**
✨ **Available as both Python Package and REST API with comprehensive Docker support!**
<!-- Docker Hub sync: Wed Aug 27 17:55:51 JST 2025 -->
Raw data
{
"_id": null,
"home_page": "https://github.com/preangelleo/ghost-blog-smart",
"name": "ghost-blog-smart",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "ghost cms blog ai gemini imagen markdown jwt api content-management",
"author": "leowang.net",
"author_email": "me@leowang.net",
"download_url": null,
"platform": null,
"description": "# Ghost Blog Smart\n\n\ud83d\ude80 **A comprehensive solution for Ghost CMS blog management with AI-powered features**\n\nAvailable as both a **Python Package** and **REST API** with multiple deployment options including Docker, local installation, and PyPI package.\n\n[](https://badge.fury.io/py/ghost-blog-smart)\n[](https://hub.docker.com/r/betashow/ghost-blog-smart-api)\n[](https://github.com/preangelleo/ghost-blog-smart/actions)\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n\n## \ud83c\udfaf **Choose Your Setup Method**\n\n| Method | Best For | Example Files | Documentation Section |\n|--------|----------|---------------|----------------------|\n| **\ud83d\udc33 Docker API** | Production deployment, quick testing | `example_usage_API.js` | [Docker Deployment](#-docker-deployment) |\n| **\ud83d\udc0d Python Package** | Python developers, scripting | `example_usage.py` | [Python Package](#-python-package-usage) |\n| **\ud83c\udf10 Local API** | Development, customization | `example_usage_API.js` | [Local API Setup](#-local-api-development) |\n| **\ud83d\udce6 PyPI Install** | Simple Python integration | `example_usage.py` | [PyPI Installation](#-pypi-installation) |\n\n## \ud83d\udcd6 **Table of Contents**\n\n### \ud83d\ude80 **Getting Started**\n- [\ud83c\udfaf Choose Your Setup Method](#-choose-your-setup-method)\n- [\ud83d\udc33 Docker Deployment](#-docker-deployment)\n- [\ud83d\udc0d Python Package Usage](#-python-package-usage)\n- [\ud83d\udce6 PyPI Installation](#-pypi-installation)\n- [\ud83c\udf10 Local API Development](#-local-api-development)\n\n### \ud83d\udcda **Usage Examples**\n- [\ud83d\udcbb Python Examples (example_usage.py)](#-python-examples-example_usagepy)\n- [\ud83c\udf10 Node.js API Examples (example_usage_API.js)](#-nodejs-api-examples-example_usage_apijs)\n\n### \ud83d\udcd6 **Documentation**\n- [\u2728 Features](#-features)\n- [\ud83d\udd27 REST API Reference](#-rest-api-reference)\n- [\u23f1\ufe0f Performance & Timeout Guidelines](#\ufe0f-performance--timeout-guidelines)\n- [\ud83e\uddea Testing](#-testing)\n\n---\n\n## \ud83d\udc33 **Docker Deployment**\n\n> **Recommended for:** Production environments, quick testing, isolation\n> \n> **Example File:** `example_usage_API.js` (Node.js client for REST API)\n\n### Quick Start\n```bash\n# Pull and run the pre-built Docker image\ndocker pull betashow/ghost-blog-smart-api:latest\n\n# Run with your credentials\ndocker run -d \\\n -p 5000:5000 \\\n -e GHOST_ADMIN_API_KEY=\"your_key_id:your_secret_key\" \\\n -e GHOST_API_URL=\"https://your-ghost-site.com\" \\\n -e GEMINI_API_KEY=\"your_gemini_key\" \\\n -e REPLICATE_API_TOKEN=\"r8_your_replicate_token\" \\\n -e FLASK_API_KEY=\"your_secure_api_key\" \\\n --name ghost-blog-api \\\n betashow/ghost-blog-smart-api:latest\n\n# Test the API\ncurl http://localhost:5000/health\n```\n\n### Docker Compose\n```yaml\nversion: '3.8'\nservices:\n ghost-blog-smart-api:\n image: betashow/ghost-blog-smart-api:latest\n ports:\n - \"5000:5000\"\n environment:\n - GHOST_ADMIN_API_KEY=your_key_id:your_secret_key\n - GHOST_API_URL=https://your-ghost-site.com\n - GEMINI_API_KEY=your_gemini_key\n - REPLICATE_API_TOKEN=r8_your_replicate_token\n - FLASK_API_KEY=your_secure_api_key\n```\n\n**Next Steps:**\n- Use `example_usage_API.js` for Node.js integration\n- Follow [Node.js API Examples](#-nodejs-api-examples-example_usage_apijs) section\n\n---\n\n## \ud83d\udc0d **Python Package Usage**\n\n> **Recommended for:** Python developers, scripting, direct integration\n>\n> **Example File:** `example_usage.py` (Pure Python usage)\n\n### Installation\n```bash\npip install ghost-blog-smart\n```\n\n### Basic Usage\n```python\nfrom ghost_blog_smart import smart_blog_gateway\n\n# Smart Gateway Method (Recommended)\nresult = smart_blog_gateway(\n \"AI healthcare benefits: faster diagnosis, better accuracy, cost reduction\",\n status=\"published\"\n)\n\nif result['success']:\n print(f\"Post created: {result['url']}\")\n```\n\n**Next Steps:**\n- Follow examples in `example_usage.py`\n- See [Python Examples](#-python-examples-example_usagepy) section\n\n---\n\n## \ud83d\udce6 **PyPI Installation**\n\n> **Recommended for:** Simple Python projects, minimal setup\n\n```bash\n# Install from PyPI\npip install ghost-blog-smart\n\n# Use directly in your Python code\nfrom ghost_blog_smart import create_ghost_blog_post, smart_blog_gateway\n```\n\nCreate `.env` file with your credentials:\n```env\nGHOST_ADMIN_API_KEY=your_admin_api_key_id:your_secret_key_here\nGHOST_API_URL=https://your-ghost-site.com\nGEMINI_API_KEY=your_gemini_api_key_here\nREPLICATE_API_TOKEN=r8_your_replicate_api_token_here\n```\n\n---\n\n## \ud83c\udf10 **Local API Development**\n\n> **Recommended for:** Development, customization, testing\n>\n> **Example Files:** `example_usage_API.js` (Node.js client) + Local Flask API\n\n### Setup\n```bash\n# Clone the repository\ngit clone https://github.com/preangelleo/ghost_blog_smart.git\ncd ghost_blog_smart\n\n# Install dependencies\npip install -r requirements.txt\npip install -r requirements-api.txt\npip install -e .\n\n# Set up environment variables\ncp .env.example .env\n# Edit .env with your credentials\n\n# Run the Flask API\npython app.py\n```\n\n**API runs on:** `http://localhost:5000`\n\n**Next Steps:**\n- Use `example_usage_API.js` to test your local API\n- Follow [Node.js API Examples](#-nodejs-api-examples-example_usage_apijs) section\n\n---\n\n## \ud83d\udcbb **Python Examples (example_usage.py)**\n\n**For:** Python Package usage, PyPI installation, direct Python integration\n\n### Key Examples from `example_usage.py`:\n\n#### Smart Gateway (AI-Enhanced Creation)\n```python\nfrom ghost_blog_smart import smart_blog_gateway\n\nresult = smart_blog_gateway(\n \"Write about AI benefits in healthcare: faster diagnosis, better accuracy\",\n status=\"published\",\n preferred_language=\"English\"\n)\n```\n\n#### Traditional Method\n```python\nfrom ghost_blog_smart import create_ghost_blog_post\n\nresult = create_ghost_blog_post(\n title=\"My Blog Post\",\n content=\"Post content in **Markdown**\",\n excerpt=\"Brief summary\",\n tags=[\"Tutorial\", \"AI\"],\n status=\"published\",\n use_generated_feature_image=True,\n prefer_flux=True\n)\n```\n\n#### Blog Management\n```python\nfrom ghost_blog_smart import get_ghost_posts, update_ghost_post, delete_ghost_post\n\n# Get posts\nposts = get_ghost_posts(limit=5, status='published')\n\n# Update post\nupdate_ghost_post(post_id=\"abc123\", featured=True)\n\n# Delete post\ndelete_ghost_post(post_id=\"abc123\")\n```\n\n**\ud83d\udcc1 Complete examples available in:** [`example_usage.py`](./example_usage.py)\n\n---\n\n## \ud83c\udf10 **Node.js API Examples (example_usage_API.js)**\n\n**For:** Docker deployment, local API server, REST API integration\n\n### Prerequisites\n```bash\nnpm install axios # HTTP client for API calls\n```\n\n### Key Examples from `example_usage_API.js`:\n\n#### Configuration\n```javascript\nconst CONFIG = {\n baseUrl: 'http://localhost:5000',\n apiKey: 'your_secure_api_key',\n timeout: 300000, // 5 minutes for image generation\n imageTimeout: 300000, // Extended timeout for image endpoints\n standardTimeout: 30000, // Standard timeout for other endpoints\n};\n```\n\n#### Create Blog Post via API\n```javascript\nconst postData = {\n title: \"My API Blog Post\",\n content: \"Post content in **Markdown**\",\n excerpt: \"Brief summary\",\n tags: [\"API\", \"Node.js\"],\n status: \"published\",\n use_generated_feature_image: true,\n prefer_flux: true,\n image_aspect_ratio: \"16:9\"\n};\n\nconst response = await api.post('/api/posts', postData);\n```\n\n#### Smart Create via API\n```javascript\nconst smartData = {\n user_input: \"Write about JavaScript testing frameworks: Jest vs Mocha vs Cypress\",\n status: \"draft\",\n preferred_language: \"English\"\n};\n\nconst response = await api.post('/api/smart-create', smartData);\n```\n\n#### Running Tests\n```bash\n# Run all endpoint tests\nnode example_usage_API.js\n\n# Run specific test\nnode example_usage_API.js health\n\n# Run with custom timeout (5 minutes for image generation)\nnode example_usage_API.js --timeout 300000\n\n# Production mode (creates real posts)\nnode example_usage_API.js --production\n```\n\n**\ud83d\udcc1 Complete examples available in:** [`example_usage_API.js`](./example_usage_API.js)\n\n---\n\n## \u2728 **Features**\n\n### \ud83e\udd16 **Smart AI Gateway**\n- **Intelligent Routing** - Automatically determines if content needs rewriting\n- **Structured Output** - Uses Gemini's structured output for consistent formatting\n- **Function Calling** - Leverages Gemini function calling for smart decision making\n- **Auto Enhancement** - Transforms scattered ideas into complete blog posts\n- **Missing Component Detection** - Automatically generates titles, excerpts, and tags\n\n### \ud83c\udfa8 **Dual AI Image Generation**\n- **\ud83d\udd25 Replicate Flux-dev**: Ultra-fast generation (3-7 seconds), photorealistic images, WebP format\n- **\ud83c\udfd4\ufe0f Google Imagen-4**: Professional quality, advanced prompt understanding, PNG format\n- **Automatic Fallback System**: Intelligent provider switching for maximum reliability\n- **Provider Selection**: Choose your preferred provider or let the system decide\n- **Multiple Aspect Ratios**: 16:9, 1:1, 9:16, 4:3, 3:2 support\n\n### \ud83d\udcdd **Content Management**\n- **Smart Content Formatting** - Auto-format plain text to beautiful Markdown with Gemini AI\n- **YouTube-Style Slugs** - Generate 11-character slugs like YouTube video IDs\n- **Multi-language Support** - Chinese to Pinyin conversion for slugs\n- **Language Translation** - Auto-translate content to any target language\n- **Flexible Image Handling** - Support for URLs, local files, base64 data\n\n### \ud83d\udcca **Blog Management**\n- **Advanced Listing** - Get posts with powerful filtering options\n- **Search & Query** - Full-text search across all posts\n- **Date Range Filtering** - Find posts by publication/creation date\n- **Update & Delete** - Modify or remove posts with comprehensive options\n- **Batch Operations** - Process multiple posts efficiently\n- **Detailed Analytics** - Get complete post details and summaries\n\n---\n\n## \ud83d\udd27 **REST API Reference**\n\n### **Base URL Structure**\n```\nhttp://localhost:5000/ # API information\nhttp://localhost:5000/health # Health check\nhttp://localhost:5000/api/ # All blog endpoints\n```\n\n### **Authentication**\nAll API endpoints (except `/` and `/health`) require authentication:\n\n```bash\ncurl -H \"X-API-Key: your_api_key\" http://localhost:5000/api/posts\n```\n\n### **Standard Response Format**\n```json\n{\n \"success\": true,\n \"timestamp\": \"2024-01-01T00:00:00.000000Z\",\n \"data\": {\n // Response data here\n }\n}\n```\n\n### **\u26a0\ufe0f TIMEOUT CONFIGURATION NOTICE**\n- **Image Generation Endpoints**: `/api/posts` (with `use_generated_feature_image: true`) and `/api/posts/{id}/image` require extended timeouts\n- **Recommended Client Timeout**: **5 minutes (300 seconds)** minimum\n- **Typical Response Times**: 60-300 seconds for image generation\n- **Without Images**: Standard 30-second timeout is sufficient\n\n### **\ud83d\udcdd Core Endpoints**\n\n#### Create Blog Post \u26a0\ufe0f **Extended Timeout for Images**\n```bash\nPOST /api/posts\nContent-Type: application/json\nX-API-Key: your_api_key\n\n{\n \"title\": \"My Blog Post\",\n \"content\": \"Post content in **Markdown**\",\n \"excerpt\": \"Brief summary\",\n \"tags\": [\"Tag1\", \"Tag2\"],\n \"status\": \"published\",\n \"use_generated_feature_image\": true,\n \"prefer_flux\": true,\n \"image_aspect_ratio\": \"16:9\"\n}\n```\n\n**\u23f1\ufe0f Important:** When `use_generated_feature_image: true` is used, generation can take 60-300 seconds. Set client timeout to at least **5 minutes (300 seconds)**.\n\n#### Smart Create (AI-Enhanced)\n```bash\nPOST /api/smart-create\nContent-Type: application/json\nX-API-Key: your_api_key\n\n{\n \"user_input\": \"Write about AI benefits in healthcare\",\n \"status\": \"draft\",\n \"preferred_language\": \"English\"\n}\n```\n\n#### Get Posts\n```bash\nGET /api/posts?limit=5&status=published&featured=true\nX-API-Key: your_api_key\n```\n\n#### Update Post Image \u26a0\ufe0f **High Timeout Required**\n```bash\nPUT /api/posts/{post_id}/image\nContent-Type: application/json\nX-API-Key: your_api_key\n\n{\n \"use_generated_feature_image\": true,\n \"prefer_imagen\": true,\n \"image_aspect_ratio\": \"16:9\"\n}\n```\n\n**\u23f1\ufe0f Important:** Image generation endpoints can take 60-300 seconds to complete. Set client timeout to at least **5 minutes (300 seconds)** for reliable operation.\n\n### **\ud83d\udccb Complete Endpoint List**\n\n| Endpoint | Method | Description | Auth Required | Timeout |\n|----------|--------|-------------|---------------|---------|\n| `/` | GET | API information | \u274c | Standard |\n| `/health` | GET | Health check | \u274c | Standard |\n| `/api/posts` | POST | Create blog post | \u2705 | **Extended*** |\n| `/api/smart-create` | POST | AI-enhanced creation | \u2705 | Standard |\n| `/api/posts` | GET | List posts | \u2705 | Standard |\n| `/api/posts/advanced` | GET | Advanced search | \u2705 | Standard |\n| `/api/posts/{id}` | GET | Get post details | \u2705 | Standard |\n| `/api/posts/{id}` | PUT/PATCH | Update post | \u2705 | Standard |\n| `/api/posts/{id}` | DELETE | Delete post | \u2705 | Standard |\n| `/api/posts/{id}/image` | PUT | Update post image | \u2705 | **Extended*** |\n| `/api/posts/summary` | GET | Posts summary | \u2705 | Standard |\n| `/api/posts/batch-details` | POST | Batch get details | \u2705 | Standard |\n| `/api/posts/search/by-date-pattern` | GET | Date search | \u2705 | Standard |\n\n**\\*Extended = 5 minutes (300 seconds) for image generation**\n\n---\n\n## \u23f1\ufe0f **Performance & Timeout Guidelines**\n\n### **Image Generation Performance**\n- **Replicate Flux**: 3-7 seconds (ultra-fast)\n- **Google Imagen**: 10-15 seconds (professional quality)\n- **Upload & Processing**: Additional 45-60 seconds\n- **Total Time**: 60-300 seconds for complete image generation\n\n### **Recommended Client Timeouts**\n```javascript\n// For endpoints WITH image generation\nconst imageApiTimeout = 300000; // 5 minutes\n\n// For endpoints WITHOUT image generation \nconst standardTimeout = 30000; // 30 seconds\n```\n\n### **Production Testing Results**\n\u2705 **All endpoints functional** \n\u26a0\ufe0f **Image generation requires extended timeout** \n\ud83d\udca1 **Recommendation**: Always set 5-minute timeout for image endpoints\n\n---\n\n## \ud83e\uddea **Testing**\n\n### **Python Package Testing**\n```bash\n# Set test mode to avoid actual posting\npython example_usage.py # Uses is_test=True by default\n```\n\n### **API Testing (Docker/Local)**\n```bash\n# Comprehensive test suite\nnode example_usage_API.js\n\n# Individual endpoint tests\nnode example_usage_API.js health\nnode example_usage_API.js create\nnode example_usage_API.js smart\n\n# Production mode (creates real posts)\nnode example_usage_API.js --production\n\n# Extended timeout for image generation\nnode example_usage_API.js --timeout 300000\n```\n\n### **Docker Testing Guide**\nSee [`TESTING_GUIDE.md`](./TESTING_GUIDE.md) for comprehensive Docker testing instructions.\n\n---\n\n## \ud83d\udcc1 **Project Structure**\n\n```\nghost-blog-smart/\n\u251c\u2500\u2500 ghost_blog_smart/ # Main Python package\n\u2502 \u251c\u2500\u2500 __init__.py # Package exports\n\u2502 \u251c\u2500\u2500 main_functions.py # Core API functions\n\u2502 \u251c\u2500\u2500 smart_gateway.py # AI-powered routing\n\u2502 \u251c\u2500\u2500 post_management.py # Advanced management\n\u2502 \u2514\u2500\u2500 *.py # Other modules\n\u251c\u2500\u2500 example_usage.py # \ud83d\udc0d Python package examples\n\u251c\u2500\u2500 example_usage_API.js # \ud83c\udf10 Node.js API client examples \n\u251c\u2500\u2500 app.py # \ud83d\ude80 Flask REST API server\n\u251c\u2500\u2500 Dockerfile # \ud83d\udc33 Docker configuration\n\u251c\u2500\u2500 docker-compose.yml # \ud83d\udc33 Docker Compose setup\n\u251c\u2500\u2500 requirements.txt # Python dependencies\n\u251c\u2500\u2500 setup.py # PyPI package setup\n\u251c\u2500\u2500 TESTING_GUIDE.md # \ud83e\uddea Docker testing instructions\n\u2514\u2500\u2500 README.md # \ud83d\udcd6 This documentation\n```\n\n---\n\n## \ud83c\udfa8 **Image Generation Comparison**\n\n| Feature | Replicate Flux-dev | Google Imagen-4 |\n|---------|-------------------|-----------------| \n| **Speed** | \u26a1 Ultra-fast (3-7s) | \ud83d\udc22 Moderate (10-15s) |\n| **Quality** | \ud83d\udd25 Photorealistic | \ud83c\udfd4\ufe0f Professional |\n| **Format** | \ud83d\udcc1 WebP (smaller) | \ud83d\udcc1 PNG (lossless) |\n| **Cost** | \ud83d\udcb0 Pay-per-use | \ud83d\udcb0 API quota based |\n| **Best For** | Realistic scenes, portraits | Abstract concepts, artistic |\n\n**Supported Aspect Ratios:**\n- `16:9` - Widescreen (1920x1080) - **Default**\n- `1:1` - Square (1024x1024) - Great for social media\n- `9:16` - Portrait (1080x1920) - Mobile-optimized\n- `4:3` - Traditional (1024x768) - Classic photo ratio\n- `3:2` - DSLR (1536x1024) - Professional photography\n\n---\n\n## \ud83d\udccb **Prerequisites**\n\n- Python 3.8+\n- Ghost CMS instance with Admin API access\n- **Image Generation** (choose one or both):\n - Google Gemini API key (for Imagen-4 generation)\n - Replicate API token (for Flux-dev generation)\n\n---\n\n## \ud83e\udd1d **Contributing**\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n---\n\n## \ud83d\udcc4 **License**\n\nMIT License - see LICENSE file for details\n\n---\n\n## \ud83d\ude4f **Acknowledgments**\n\n- Ghost CMS for the excellent blogging platform\n- Google Gemini & Imagen for AI capabilities \n- Replicate for ultra-fast Flux generation\n- The open-source community\n\n---\n\n## \ud83d\udcde **Support**\n\nFor issues or questions, please open an issue on GitHub.\n\n---\n\n**Made with \u2764\ufe0f for the Ghost CMS community**\n\n\u2728 **Available as both Python Package and REST API with comprehensive Docker support!**\n<!-- Docker Hub sync: Wed Aug 27 17:55:51 JST 2025 -->\n",
"bugtrack_url": null,
"license": null,
"summary": "A powerful Python library and REST API for creating Ghost CMS blog posts with AI-powered features including Flask API and Docker deployment",
"version": "1.1.3",
"project_urls": {
"Bug Reports": "https://github.com/preangelleo/ghost-blog-smart/issues",
"Documentation": "https://github.com/preangelleo/ghost-blog-smart#readme",
"Homepage": "https://github.com/preangelleo/ghost-blog-smart",
"Source": "https://github.com/preangelleo/ghost-blog-smart"
},
"split_keywords": [
"ghost",
"cms",
"blog",
"ai",
"gemini",
"imagen",
"markdown",
"jwt",
"api",
"content-management"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e633efc7f8f00cc1fa976d13a9b2538ea73b93308f3327467c0fc49b574886e3",
"md5": "90855ba4e2644ba6ee4f79d1b5e5bee4",
"sha256": "95affe8c99749b07745e377a3f3a4ba51b0ecf9ea04a0a40abd001b87a084f65"
},
"downloads": -1,
"filename": "ghost_blog_smart-1.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "90855ba4e2644ba6ee4f79d1b5e5bee4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 58464,
"upload_time": "2025-08-27T09:01:24",
"upload_time_iso_8601": "2025-08-27T09:01:24.915375Z",
"url": "https://files.pythonhosted.org/packages/e6/33/efc7f8f00cc1fa976d13a9b2538ea73b93308f3327467c0fc49b574886e3/ghost_blog_smart-1.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-27 09:01:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "preangelleo",
"github_project": "ghost-blog-smart",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pypinyin",
"specs": [
[
">=",
"0.50.0"
]
]
},
{
"name": "google-generativeai",
"specs": [
[
">=",
"0.8.0"
]
]
},
{
"name": "markdownify",
"specs": [
[
">=",
"0.11.6"
]
]
},
{
"name": "markdown-it-py",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "markdown",
"specs": [
[
">=",
"3.5.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
},
{
"name": "PyJWT",
"specs": [
[
">=",
"2.8.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "google-genai",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "Pillow",
"specs": [
[
">=",
"10.0.0"
]
]
},
{
"name": "replicate",
"specs": [
[
">=",
"1.0.0"
]
]
}
],
"lcname": "ghost-blog-smart"
}
JSON
