🎨 imgpt v0.3.0 Release Notes

🎨 imgpt v0.3.0 Release Notes

Release Date: December 26, 2024
Repository: https://github.com/JacobFV/imgpt

🚀 Major New Features

🔧 Persistent Configuration System

We've added a comprehensive persistent configuration system that allows you to save your preferences and avoid repeating command-line options:

• API Key Storage - Store your OpenAI API key securely in configuration
• Default Settings - Set default models, sizes, quality, and other generation parameters
• Directory Preferences - Configure default prompt and output directories
• Cross-Platform - Configuration stored in appropriate OS-specific directories

# Set your API key once
imgpt config set openai_api_key "your-key-here"

# Set default preferences
imgpt config set default_model "dall-e-3"
imgpt config set default_size "1024x1024"
imgpt config set default_quality "hd"
imgpt config set default_output_dir "/path/to/images"

# View current configuration
imgpt config show

# Reset to defaults
imgpt config reset

🎨 Enhanced CLI with Typer

Complete rewrite of the CLI using Typer for a better user experience:

• Rich Output - Beautiful colored output with progress indicators
• Better Help - Comprehensive help system with examples
• Subcommands - Organized command structure (imgpt generate, imgpt config)
• Auto-completion - Shell completion support for commands and options
• Validation - Better input validation with helpful error messages

# New command structure
imgpt generate "A beautiful sunset"           # Direct prompt
imgpt generate --dir ./prompts               # Batch processing
imgpt config show                            # Configuration management
imgpt version                                 # Version information

📁 Smart Configuration Management

The configuration system intelligently handles defaults and overrides:

• Precedence Order: Command-line options → Configuration file → Built-in defaults
• Validation: All configuration values are validated before saving
• Platform-Aware: Uses OS-appropriate configuration directories
  • macOS: ~/Library/Application Support/imgpt/
  • Linux: ~/.config/imgpt/
  • Windows: %APPDATA%/imgpt/

🛡️ Enhanced Validation & Error Handling

Smart Input Validation

• Model-Size Compatibility: Automatic validation of size/model combinations
• Configuration Validation: Pydantic-based validation for all settings
• Directory Validation: Checks for directory existence and permissions
• API Key Handling: Secure storage and retrieval with fallback to environment

Better Error Messages

$ imgpt generate "test" --model dall-e-2 --size 2048x2048
❌ Error: Size '2048x2048' is not valid for model 'dall-e-2'
Valid sizes for dall-e-2: 256x256, 512x512, 1024x1024

📖 Configuration Options

API Settings

• openai_api_key - Your OpenAI API key

Generation Settings

• default_model - Default model (gpt-image-1, dall-e-2, dall-e-3)
• default_size - Default image size (e.g., 1024x1024, 1536x1024)
• default_quality - Default quality (auto, high, medium, low, hd, standard)
• default_style - Default style for DALL-E 3 (vivid, natural)
• default_format - Default output format (png, jpeg, webp)

Directory Settings

• default_prompts_dir - Default directory for prompt files
• default_output_dir - Default directory for generated images

Processing Settings

• default_delay - Default delay between API calls (seconds)
• skip_existing - Default setting for skipping existing images

🔄 Breaking Changes

Command Structure Changes

The CLI now uses subcommands for better organization:

Old (v0.2.0):

imgpt "A sunset" --output sunset.png
imgpt --dir ./prompts --output ./images

New (v0.3.0):

imgpt generate "A sunset" --output sunset.png
imgpt generate --dir ./prompts --output ./images

Removed Options

• --version flag moved to imgpt version command
• Direct execution requires generate subcommand

🔧 Technical Improvements

Dependencies

• Added: typer[all] for enhanced CLI experience
• Added: pydantic for configuration validation
• Added: rich for beautiful terminal output
• Added: tomli-w for TOML configuration file writing

Code Quality

• Type Safety: Enhanced type hints throughout codebase
• Validation: Pydantic models for configuration validation
• Testing: Comprehensive test suite for configuration system
• Documentation: Extensive inline documentation and examples

Performance

• Configuration Caching: Configuration loaded once and cached
• Lazy Loading: Configuration only loaded when needed
• Efficient Validation: Fast validation with detailed error messages

📋 Usage Examples

First-Time Setup

# Install imgpt
pipx install imgpt

# Set up your API key
imgpt config set openai_api_key "your-openai-api-key"

# Set your preferences
imgpt config set default_model "dall-e-3"
imgpt config set default_quality "hd"
imgpt config set default_output_dir "~/Pictures/AI-Generated"

# Generate your first image
imgpt generate "A majestic dragon flying over a medieval castle"

Advanced Configuration

# Set up for batch processing
imgpt config set default_prompts_dir "~/Documents/Prompts"
imgpt config set default_output_dir "~/Pictures/Generated"
imgpt config set default_delay 1.0
imgpt config set skip_existing true

# Now batch processing is simple
imgpt generate --dir ~/Documents/Prompts

Configuration Management

# View all settings
imgpt config show

# Update specific settings
imgpt config set default_model "gpt-image-1"
imgpt config set default_size "1536x1024"

# Reset everything to defaults
imgpt config reset

# Find your config file
imgpt config path

🐛 Bug Fixes

• Fixed output format handling for different models
• Improved prompt length validation and truncation
• Enhanced file extension handling for custom output formats
• Better error handling for configuration file corruption

🚀 Performance Improvements

• Reduced startup time through lazy configuration loading
• Optimized validation pipeline
• Improved memory usage for large batch operations
• Better error recovery and retry logic

📦 Installation & Upgrade

New Installation

# Install with pipx (recommended)
pipx install imgpt

# Install with pip
pip install imgpt

Upgrade from v0.2.0

# Upgrade with pipx
pipx upgrade imgpt

# Upgrade with pip
pip install --upgrade imgpt

# Note: First run will create new configuration file
imgpt config show

🔮 Migration Guide

From v0.2.0 to v0.3.0

1. Update Commands: Add generate subcommand to existing scripts
2. Set Configuration: Use imgpt config set to save frequently used options
3. Update Scripts: Replace --version with imgpt version

Example Migration:

# Old
imgpt "A sunset" --model dall-e-3 --quality hd --output sunset.png

# New - one-time setup
imgpt config set default_model "dall-e-3"
imgpt config set default_quality "hd"

# New - simplified usage
imgpt generate "A sunset" --output sunset.png

🙏 Acknowledgments

• Typer team for the excellent CLI framework
• Pydantic team for robust data validation
• Rich team for beautiful terminal output
• Community feedback that drove these improvements

🔮 What's Next?

• Configuration profiles for different use cases
• Batch operation optimization
• Integration with popular design tools
• Advanced prompt templating system
• Configuration import/export functionality

---

Full Changelog: v0.2.0...v0.3.0
Download: https://github.com/JacobFV/imgpt/releases/tag/v0.3.0

Made with ❤️ by Jacob Valdez

---

🎨 imgpt v0.2.0 Release Notes

Release Date: May 26, 2025
Repository: https://github.com/JacobFV/imgpt

🚀 Major New Features

🤖 Multi-Model Support

We've added support for all OpenAI image generation models:

• gpt-image-1 (default) - OpenAI's latest and most advanced image model
• dall-e-3 - High-quality artistic images with style controls
• dall-e-2 - Fast and cost-effective image generation

# Use different models
imgpt "A sunset" --model dall-e-3
imgpt "Quick sketch" --model dall-e-2

📐 Multiple Image Dimensions

Generate images in various aspect ratios and sizes:

gpt-image-1:

• Square: 1024x1024
• Landscape: 1536x1024
• Portrait: 1024x1536

dall-e-3:

• Square: 1024x1024
• Landscape: 1792x1024
• Portrait: 1024x1792

dall-e-2:

• Small: 256x256
• Medium: 512x512
• Large: 1024x1024

# Generate in different orientations
imgpt "Landscape photo" --size 1792x1024
imgpt "Portrait painting" --size 1024x1536
imgpt "Thumbnail" --model dall-e-2 --size 256x256

🎨 Quality & Style Controls

Fine-tune your image generation:

• Quality levels: auto, high, medium, low, hd, standard
• Style options: vivid, natural (DALL-E 3 only)
• Output formats: PNG, JPEG, WebP (gpt-image-1 only)

# High-quality artistic image
imgpt "Abstract art" --model dall-e-3 --quality hd --style vivid

# Web-optimized JPEG
imgpt "Website banner" --format jpeg --quality medium

🛡️ Enhanced Validation & Intelligence

Smart Model Validation

• Automatic validation of size compatibility with each model
• Model-specific prompt length limits (32K for gpt-image-1, 4K for dall-e-3, 1K for dall-e-2)
• Intelligent default sizes based on selected model

Better Error Messages

$ imgpt "test" --model dall-e-2 --size 2048x2048
❌ Error: Size '2048x2048' is not valid for model 'dall-e-2'
Valid sizes for dall-e-2: 256x256, 512x512, 1024x1024

📖 Comprehensive Documentation Updates

Updated CLI Help

$ imgpt --help
Options:
  --model {gpt-image-1,dall-e-2,dall-e-3}    Model to use (default: gpt-imag...

v0.2.0

🎨 imGPT v0.2.0 Release Notes

Release Date: May 26, 2025
Repository: https://github.com/JacobFV/imgpt

🚀 Major New Features

🤖 Multi-Model Support

We've added support for all OpenAI image generation models:

• gpt-image-1 (default) - OpenAI's latest and most advanced image model
• dall-e-3 - High-quality artistic images with style controls
• dall-e-2 - Fast and cost-effective image generation

# Use different models
imgpt "A sunset" --model dall-e-3
imgpt "Quick sketch" --model dall-e-2

📐 Multiple Image Dimensions

Generate images in various aspect ratios and sizes:

gpt-image-1:

• Square: 1024x1024
• Landscape: 1536x1024
• Portrait: 1024x1536

dall-e-3:

• Square: 1024x1024
• Landscape: 1792x1024
• Portrait: 1024x1792

dall-e-2:

• Small: 256x256
• Medium: 512x512
• Large: 1024x1024

# Generate in different orientations
imgpt "Landscape photo" --size 1792x1024
imgpt "Portrait painting" --size 1024x1536
imgpt "Thumbnail" --model dall-e-2 --size 256x256

🎨 Quality & Style Controls

Fine-tune your image generation:

• Quality levels: auto, high, medium, low, hd, standard
• Style options: vivid, natural (DALL-E 3 only)
• Output formats: PNG, JPEG, WebP (gpt-image-1 only)

# High-quality artistic image
imgpt "Abstract art" --model dall-e-3 --quality hd --style vivid

# Web-optimized JPEG
imgpt "Website banner" --format jpeg --quality medium

🛡️ Enhanced Validation & Intelligence

Smart Model Validation

• Automatic validation of size compatibility with each model
• Model-specific prompt length limits (32K for gpt-image-1, 4K for dall-e-3, 1K for dall-e-2)
• Intelligent default sizes based on selected model

Better Error Messages

$ imgpt "test" --model dall-e-2 --size 2048x2048
❌ Error: Size '2048x2048' is not valid for model 'dall-e-2'
Valid sizes for dall-e-2: 256x256, 512x512, 1024x1024

📖 Comprehensive Documentation Updates

Updated CLI Help

$ imgpt --help
Options:
  --model {gpt-image-1,dall-e-2,dall-e-3}    Model to use (default: gpt-image-1)
  --size SIZE                                 Image dimensions (e.g., 1024x1024)
  --quality {auto,high,medium,low,hd,standard} Image quality (default: high)
  --style {vivid,natural}                     DALL-E 3 style options
  --format {png,jpeg,webp}                    Output format (default: png)

Enhanced README

• Detailed model comparison table
• Comprehensive usage examples
• Best practices for each model
• Cost optimization tips

🔧 Technical Improvements

API Integration

• Full support for OpenAI's latest image generation API parameters
• Model-specific parameter handling
• Proper response format handling for each model

Code Quality

• Enhanced type hints and documentation
• Improved error handling and validation
• Extended test coverage for new features
• Backward compatibility maintained

📋 Usage Examples

Single Image Generation

# Default high-quality generation
imgpt "A majestic eagle in flight"

# Artistic style with DALL-E 3
imgpt "Surreal landscape" --model dall-e-3 --style vivid --quality hd

# Fast generation for prototyping
imgpt "Logo concept" --model dall-e-2 --size 512x512

# Custom format and quality
imgpt "Web image" --format jpeg --quality medium --size 1536x1024

Batch Processing

# High-quality art generation
imgpt --dir ./art_prompts --model dall-e-3 --quality hd --style natural

# Thumbnail generation
imgpt --dir ./thumbnails --model dall-e-2 --size 256x256

# Web-optimized batch processing
imgpt --dir ./web_images --format webp --quality medium

🔄 Breaking Changes

None - This release maintains full backward compatibility. All existing commands will continue to work exactly as before.

🐛 Bug Fixes

• Fixed output format handling for different models
• Improved prompt length validation
• Enhanced file extension handling for custom output formats

🚀 Performance Improvements

• Optimized API parameter building
• Reduced unnecessary API calls through better validation
• Improved error handling reduces retry overhead

📦 Installation & Upgrade

New Installation

# Install with pipx (recommended)
pipx install imgpt

# Install with pip
pip install imgpt

Upgrade from v0.1.0

# Upgrade with pipx
pipx upgrade imgpt

# Upgrade with pip
pip install --upgrade imgpt

🙏 Acknowledgments

• OpenAI for their comprehensive image generation API
• Community feedback that drove these feature requests
• Contributors who helped test the new functionality

🔮 What's Next?

• Batch size optimization for faster processing
• Image editing and variation capabilities
• Integration with popular design tools
• Advanced prompt templating system

---

Full Changelog: v0.1.0...v0.2.0
Download: https://github.com/JacobFV/imgpt/releases/tag/v0.2.0

Made with ❤️ by Jacob Valdez

---

🎨 imGPT v1.0.0 Release Notes

Release Date: May 26, 2025
Repository: https://github.com/JacobFV/imgpt

🚀 Features

• Generate images from text prompts using OpenAI's image-gpt model
• Supports direct prompt input and batch processing of prompt files
• Output images in PNG format
• Simple CLI interface

🐛 Bug Fixes

• Initial release, no known bugs

📦 Installation

pip install imgpt

v0.1.0

imGPT 🎨

A powerful CLI tool for generating images using OpenAI's API. Generate images from text prompts directly or process entire directories of prompt files.

✨ Features

• 🚀 Direct Prompt Generation: Generate images from command-line prompts
• 📁 Batch Processing: Process entire directories of prompt files
• 🎯 Multiple Formats: Support for .prompt, .txt, and .md files
• 🔄 Smart Skipping: Skip existing images to save time and API costs
• ⚡ Rate Limiting: Configurable delays to respect API limits
• 🎨 High Quality: Uses OpenAI's gpt-image-1 model for best results
• 📦 Easy Install: Install globally with pipx

🚀 Quick Start

Install with pipx (Recommended)

pipx install imgpt

Install with pip

pip install imgpt

Set up your API key

export OPENAI_API_KEY="your-api-key-here"

Generate your first image

imgpt "A majestic dragon flying over a medieval castle at sunset"

📖 Usage

Direct Prompt Generation

Generate a single image from a text prompt:

# Basic usage
imgpt "A cute robot playing guitar"

# Save to specific file
imgpt "A space station orbiting Earth" --output space_station.png

# Custom output location
imgpt "Abstract art with vibrant colors" --output ./art/abstract.png

Batch Processing from Directory

Process multiple prompt files at once:

# Process all prompt files in a directory
imgpt --dir ./my_prompts

# Save to different output directory
imgpt --dir ./prompts --output ./generated_images

# Skip existing images and use faster processing
imgpt --dir ./prompts --skip-existing --delay 1

📁 Supported File Formats

.prompt files

A beautiful sunset over snow-capped mountains with a lake reflection

.txt files

A futuristic cityscape with flying cars and neon lights

.md files (with special parsing)

# Image Description

**Description:**
A serene Japanese garden with cherry blossoms, a small bridge over a koi pond, and traditional lanterns. The scene should be peaceful and zen-like.

**Style:** Photorealistic
**Mood:** Tranquil

🛠️ Command Line Options

imgpt [OPTIONS] [PROMPT]

Arguments:
  PROMPT                    Direct prompt text for image generation

Options:
  --dir PATH               Directory containing prompt files
  --output PATH            Output file/directory path
  --delay FLOAT            Delay between API calls in seconds (default: 2.0)
  --skip-existing          Skip generating images that already exist
  --version                Show version and exit
  --help                   Show help message and exit

📋 Examples

Single Image Generation

# Simple prompt
imgpt "A red sports car"

# Complex prompt with details
imgpt "A detailed oil painting of a lighthouse on a rocky cliff during a storm, dramatic lighting, high contrast"

# Save with custom name
imgpt "A minimalist logo design" --output company_logo.png

Batch Processing

# Process directory (saves images alongside prompts)
imgpt --dir ./product_descriptions

# Separate input/output directories
imgpt --dir ./marketing_prompts --output ./marketing_images

# Production settings (skip existing, faster processing)
imgpt --dir ./prompts --output ./images --skip-existing --delay 0.5

🔧 Configuration

Environment Variables

Variable	Required	Description
OPENAI_API_KEY	✅	Your OpenAI API key

Image Settings

The tool generates images with these settings:

• Model: gpt-image-1 (OpenAI's latest image model)
• Size: 1536x1024 (landscape format)
• Quality: High
• Format: PNG

📦 Installation Methods

Method 1: pipx (Recommended)

# Install globally without affecting system Python
pipx install imgpt

# Upgrade
pipx upgrade imgpt

# Uninstall
pipx uninstall imgpt

Method 2: pip

# Install globally
pip install imgpt

# Install in virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install imgpt

Method 3: Development Install

git clone https://github.com/humanrobots-ai/imgpt.git
cd imgpt
poetry install
poetry run imgpt "test prompt"

🧪 Development

Running Tests

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=imgpt

# Run specific test
poetry run pytest tests/test_cli.py::test_read_prompt_file_simple

Code Quality

# Format code
poetry run black src/

# Lint code
poetry run flake8 src/

🚨 Error Handling

The tool gracefully handles various error conditions:

• Missing API Key: Clear instructions for setting up authentication
• Empty Prompts: Skips empty files with warnings
• API Errors: Continues processing other files if one fails
• Network Issues: Retries with exponential backoff
• Invalid Paths: Validates input/output directories

💡 Tips & Best Practices

Writing Better Prompts

1. Be Specific: Include details about style, lighting, composition
2. Use Descriptive Language: "vibrant", "detailed", "photorealistic"
3. Specify Art Style: "oil painting", "digital art", "photograph"
4. Include Mood: "serene", "dramatic", "whimsical"

Batch Processing

1. Organize Prompts: Use descriptive filenames for easy identification
2. Use Skip Existing: Avoid regenerating images unnecessarily
3. Adjust Delays: Balance speed vs. API rate limits
4. Separate Outputs: Keep generated images organized

Cost Management

1. Preview Prompts: Review prompts before batch processing
2. Use Skip Existing: Avoid duplicate generations
3. Test Single Images: Verify prompts work before batch runs
4. Monitor Usage: Track API usage in OpenAI dashboard

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 📧 Email: jacobfv123@gmail.com
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

🙏 Acknowledgments

• OpenAI for providing the amazing image generation API
• The Python community for excellent tooling and libraries
• All contributors and users of this tool

---

Made with ❤️ by Jacob Valdez