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.
🎯 Choose Your Setup Method
| Method | Best For | Example Files | Documentation Section |
|---|---|---|---|
| 🐳 Docker API | Production deployment, quick testing | example_usage_API.js |
Docker Deployment |
| 🐍 Python Package | Python developers, scripting | example_usage.py |
Python Package |
| 🌐 Local API | Development, customization | example_usage_API.js |
Local API Setup |
| 📦 PyPI Install | Simple Python integration | example_usage.py |
PyPI Installation |
📖 Table of Contents
🚀 Getting Started
- 🎯 Choose Your Setup Method
- 🐳 Docker Deployment
- 🐍 Python Package Usage
- 📦 PyPI Installation
- 🌐 Local API Development
📚 Usage Examples
📖 Documentation
🐳 Docker Deployment
Recommended for: Production environments, quick testing, isolation
Example File:
example_usage_API.js(Node.js client for REST API)
Quick Start
# 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
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.jsfor Node.js integration - Follow Node.js API Examples section
🐍 Python Package Usage
Recommended for: Python developers, scripting, direct integration
Example File:
example_usage.py(Pure Python usage)
Installation
pip install ghost-blog-smart
Basic Usage
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 section
📦 PyPI Installation
Recommended for: Simple Python projects, minimal setup
# 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:
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
# 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.jsto test your local API - Follow Node.js API Examples 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)
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
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
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
🌐 Node.js API Examples (example_usage_API.js)
For: Docker deployment, local API server, REST API integration
Prerequisites
npm install axios # HTTP client for API calls
Key Examples from example_usage_API.js:
Configuration
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
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
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
# 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
✨ 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:
curl -H "X-API-Key: your_api_key" http://localhost:5000/api/posts
Standard Response Format
{
"success": true,
"timestamp": "2024-01-01T00:00:00.000000Z",
"data": {
// Response data here
}
}
⚠️ TIMEOUT CONFIGURATION NOTICE
- Image Generation Endpoints:
/api/posts(withuse_generated_feature_image: true) and/api/posts/{id}/imagerequire 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
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)
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
GET /api/posts?limit=5&status=published&featured=true
X-API-Key: your_api_key
Update Post Image ⚠️ High Timeout Required
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
// 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
# Set test mode to avoid actual posting
python example_usage.py # Uses is_test=True by default
API Testing (Docker/Local)
# 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 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) - Default1:1- Square (1024x1024) - Great for social media9:16- Portrait (1080x1920) - Mobile-optimized4:3- Traditional (1024x768) - Classic photo ratio3: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!
Metadata
Release files for ghost-blog-smart 1.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ghost_blog_smart-1.1.3-py3-none-any.whl | Python 3 | none | any | Details for ghost_blog_smart-1.1.3-py3-none-any.whl |
Release files / ghost_blog_smart-1.1.3-py3-none-any.whl
| Download URL | ghost_blog_smart-1.1.3-py3-none-any.whl |
|---|---|
| Size | 58.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
95affe8c99749b07745e377a3f3a4ba51b0ecf9ea04a0a40abd001b87a084f65
|
|
BLAKE2b-256 checksum How to use checksums |
e633efc7f8f00cc1fa976d13a9b2538ea73b93308f3327467c0fc49b574886e3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.10.18
|
Security for ghost-blog-smart 1.1.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.