banatie-service/README.md

# Banatie - Nano Banana Image Generation Service

A REST API service for AI-powered image generation using the Gemini Flash Image model. Banatie provides a simple HTTP interface for generating high-quality images from text prompts with optional reference images.

## 🚀 Quick Start

### Prerequisites

- Node.js >= 18.0.0
- pnpm >= 8.0.0
- Gemini API key from [Google AI Studio](https://aistudio.google.com/)

### Installation

```bash
# Clone the repository
git clone <repository-url>
cd banatie

# Install dependencies
pnpm install

# Setup environment variables
cp .env.example .env
# Edit .env with your Gemini API key
```

### Development

```bash
# Start development server with auto-reload
pnpm dev

# Start production server
pnpm start

# Build for production
pnpm build
```

## 📝 Environment Configuration

Copy `.env.example` to `.env` and configure:

```bash
# Required
GEMINI_API_KEY=your_gemini_api_key_here

# Optional (with defaults)
PORT=3000
NODE_ENV=development
CORS_ORIGIN=*
MAX_FILE_SIZE=5242880  # 5MB
MAX_FILES=3
RESULTS_DIR=./results
UPLOADS_DIR=./uploads/temp
LOG_LEVEL=info
```

## 🔌 API Endpoints

### Health Check
```
GET /health
```
Returns server status and uptime.

### API Information
```
GET /api/info
```
Returns API details and configuration.

### Generate Image
```
POST /api/generate
Content-Type: multipart/form-data
```

**Parameters:**
- `prompt` (string, required): Text description for image generation
- `filename` (string, optional): Custom filename for the generated image
- `referenceImages` (files, optional): Up to 3 reference images (5MB max each)

**Supported formats:** PNG, JPEG, JPG, WebP

## 📖 Usage Examples

### cURL
```bash
# Basic text-to-image
curl -X POST http://localhost:3000/api/generate \
  -F "prompt=A magical forest with glowing mushrooms" \
  -F "filename=magical_forest"

# With reference images
curl -X POST http://localhost:3000/api/generate \
  -F "prompt=Character in medieval armor like the reference" \
  -F "referenceImages=@./reference.jpg"
```

### JavaScript/Fetch
```javascript
const formData = new FormData();
formData.append('prompt', 'A futuristic cityscape at sunset');
formData.append('filename', 'futuristic_city');

const response = await fetch('http://localhost:3000/api/generate', {
  method: 'POST',
  body: formData
});

const result = await response.json();
console.log(result);
```

### Response Format
```json
{
  "success": true,
  "message": "Image generated successfully",
  "data": {
    "filename": "generated_image_123.png",
    "filepath": "./results/generated_image_123.png",
    "description": "Generated image description",
    "model": "gemini-2.0-flash-exp",
    "generatedAt": "2024-01-01T12:00:00.000Z"
  }
}
```

## 🛠️ Development Scripts

```bash
# Development
pnpm dev              # Start with auto-reload
pnpm build            # Build for production
pnpm start            # Start production server

# Code Quality
pnpm typecheck        # TypeScript type checking
pnpm lint             # ESLint code linting
pnpm lint:fix         # Fix ESLint issues
pnpm format           # Format code with Prettier
pnpm format:check     # Check code formatting

# Testing
pnpm test             # Run tests
pnpm test:watch       # Run tests in watch mode
pnpm test:coverage    # Run tests with coverage
```

## 🏗️ Project Structure

```
banatie/
├── src/
│   ├── middleware/          # Express middleware
│   ├── routes/             # API route handlers
│   ├── services/           # Business logic services
│   ├── types/              # TypeScript type definitions
│   ├── utils/              # Utility functions
│   ├── app.ts              # Express app configuration
│   └── server.ts           # Server entry point
├── tests/                  # Test files
├── results/                # Generated images output
├── uploads/                # Temporary file uploads
└── logs/                   # Application logs
```

## 🔧 Configuration

### File Limits
- **Max file size**: 5MB per image (configurable)
- **Max files**: 3 reference images per request (configurable)
- **Request size**: 10MB total request limit

### Supported Image Formats
- PNG
- JPEG/JPG
- WebP

## 🚦 Error Handling

The API provides detailed error responses:

**Validation Errors (400):**
- Missing required parameters
- Invalid file formats
- File size exceeded
- Too many files

**Server Errors (500):**
- Missing API key configuration
- Image generation failures
- Internal processing errors

## 📄 License

MIT License - see LICENSE file for details.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

## 📞 Support

For issues and questions, please open an issue on the GitHub repository.