# Visual Generation Services Reference

## Service Catalog

### SOTA Recommended Models

| Service | Type | Cost | Best For | API Key |
|---------|------|------|----------|---------|
| Gemini 3.0 Pro Image ("Nano Banana") | Image | $0.02 | Fast, diagrams, general use | `GEMINI_API_KEY` or `GOOGLE_API_KEY` |
| GPT Image 1.5 | Image | $0.02-$0.19 | Best text rendering, highest quality | `OPENAI_API_KEY` |

### Additional Models

| Service | Type | Cost | Best For | API Key |
|---------|------|------|----------|---------|
| Imagen 3 | Image | $0.03 | Premium quality heroes | `GEMINI_API_KEY` |
| GPT Image 1 | Image | $0.19 | High quality images | `OPENAI_API_KEY` |
| GPT Image 1 Mini | Image | $0.02 | Budget option, high volume | `OPENAI_API_KEY` |
| Nano Banana Pro | Image | $0.15 | High-quality branded visuals | `FAL_KEY` |
| FLUX 2 Pro | Image | $0.05 | Detailed illustrations, multi-ref | `FAL_KEY` |
| FLUX 2 Flex | Image | $0.04 | Developer-controlled params | `FAL_KEY` |
| FLUX 2 Dev | Image | $0.025 | 32B open-weight model | `FAL_KEY` |
| Veo 3 | Video | $0.40/sec | Product demos, tutorials | `FAL_KEY` |

### GPT Image 1.5 Quality Tiers

| Quality | Cost | Tokens |
|---------|------|--------|
| low | $0.02 | ~272 |
| medium | $0.07 | ~1056 |
| high | $0.19 | ~4160 |

## Service Selection Logic

Route based on visual type and text requirements:

| Scenario | Recommended Service |
|----------|-------------------|
| Hero image, artistic | FLUX 2 Pro or Imagen |
| Text-heavy visuals (exact numbers, labels) | GPT Image 1.5 or HTML Conversion |
| Fast/cheap general image | Gemini 3.0 Pro Image |
| Technical diagrams | Gemini or Mermaid render path |
| Video content | Veo 3 |
| Specialized models | fal.ai MCP discovery |

### HTML Conversion Alternative

For data-driven visuals requiring pixel-perfect text accuracy, use HTML-to-screenshot instead of AI generation:

| Use Case | Tool |
|----------|------|
| Exact numbers/data | HTML Conversion (Playwright) |
| Precise text labels | HTML/D2 Conversion |
| Charts and graphs | HTML Conversion |
| Creative/artistic | AI Generation |

When text fidelity is critical and the user explicitly says "perfectly legible" or similar, prefer HTML conversion even when AI services are available.

## fal.ai MCP Tools (When FAL_KEY is configured)

The fal.ai MCP server provides capabilities beyond the built-in SDK:

| Tool | Purpose |
|------|---------|
| Model search/discovery | Find specialized models across 600+ fal.ai models |
| Schema inspection | Understand model parameters before generation |
| Real-time pricing | Accurate cost estimation from live pricing data |
| File upload | Upload reference images to fal.ai CDN for FLUX 2 multi-ref |
| Request status/cancel | Monitor or cancel long-running generation requests |

### When to Use MCP vs SDK

| Scenario | Approach |
|----------|----------|
| Standard generation (FLUX 2, Veo 3) | SDK (`visual-generation-utils.js`) |
| Discover new/specialized models | MCP (model search tools) |
| Check real-time pricing | MCP (pricing tools) |
| Upload reference images for multi-ref | MCP (upload tool) then SDK |
| Generate with non-standard fal.ai models | MCP (generate/result tools) |
| Cancel or monitor long-running requests | MCP (status/cancel tools) |

## Budget Defaults

- Daily budget: $5.00 (`VISUAL_DAILY_BUDGET`)
- Monthly budget: $50.00 (`VISUAL_MONTHLY_BUDGET`)

## API Key Priority

The SDK supports both `GEMINI_API_KEY` (preferred) and `GOOGLE_API_KEY` (legacy). See `validateAPIKeys()` in the bundled script for the full resolution logic.