# Epic 7: AI-Powered Image Generation

## Epic Goal
To automatically generate and insert high-quality images into generated articles, including hero images for all tiers and content images for T1 articles, using AI-powered image generation via fal.ai FLUX.1 schnell API.

## Status
- **Story 7.1**: 📋 PLANNING (TBD story points)

## Stories

### Story 7.1: Generate and Insert Images into Articles
**Status:** 📋 PLANNING  
**Document:** [story-7.1-image-generation.md](../stories/story-7.1-image-generation.md)

**As a developer**, I want to automatically generate hero images for all article tiers and content images for T1 articles, so that articles are visually enhanced without manual image creation.

**Acceptance Criteria**
* Hero images generated for all tiers (configurable per tier in job JSON)
* Content images generated for T1 articles (1-3 images by default, configurable)
* Images generated using fal.ai FLUX.1 schnell API
* Theme prompt generated once per project using AI, reused for all images
* Images uploaded to storage zone `images/` subdirectory
* Images inserted into HTML content (hero after H1, content images after H2s)
* Alt text includes 3 entities and 2 related searches
* Graceful failure handling (continue without images if generation fails)
* Job JSON configuration for image sizes and counts per tier

**Implementation Notes**
* Hero images: 1280x720 default, title truncated to 3-4 words, uppercase
* Content images: 512x512 default, named with entity + related_search
* Max 5 concurrent fal.ai API calls (same pattern as OpenRouter)
* Images are optional enhancements (failures don't block article generation)
* Theme prompt cached in Project model for reuse

## Notes
- Images enhance SEO and user engagement
- fal.ai API provides fast generation (<3 seconds per image)
- Theme consistency across project ensures visual coherence
- Job JSON allows fine-grained control per tier
- Technical debt: Image optimization, CDN caching, format conversion deferred