ghost-blog-smart 1.1.3

A powerful Python library and REST API for creating Ghost CMS blog posts with AI-powered features including Flask API and Docker deployment

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

• 💻 Python Examples (example_usage.py)
• 🌐 Node.js API Examples (example_usage_API.js)

📖 Documentation

• ✨ Features
• 🔧 REST API Reference
• ⏱️ Performance & Timeout Guidelines
• 🧪 Testing

---

🐳 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.js for 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.js to 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 (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

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) - 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!