Add cloud sprite providers and browser demos

README.md

@@ -13,6 +13,7 @@ MCP server for generating pixel-art sprites with transparent backgrounds. Bring
 - **Reproducible** — optional seed for consistent results
 - **Batch generation** — generate multiple sprites in one call
 - **MCP integration** — works with any MCP-compatible client (opencode, Claude, etc.)
+- **Cloud image models** — Polza.ai Media API, including image references and multi-image variations
 - **Feedback loop** — rate generated sprites, AI uses high-rated ones as reference
 
 ## Quick Start
@@ -64,6 +65,52 @@ export IMAGEGEN_LORA_DIR=/path/to/your/lora        # optional, set empty to disa
 export IMAGEGEN_OUTPUT_DIR=/path/to/output
 ```
 
+### Cloud generation with Polza.ai
+
+No local GPU or model download is required when using the `polza` provider. Create
+an API key in Polza.ai and expose it only to the MCP server process. The server
+also loads a local `.env` file automatically; create it from the safe template:
+
+```bash
+cp .env.example .env
+# Edit .env and set POLZA_API_KEY=your_key
+
+# Or provide variables directly when starting the MCP server:
+export POLZA_API_KEY=your_key
+# Optional default; pass model per tool call to override it.
+export POLZA_IMAGE_MODEL=openai/gpt-image-1.5
+```
+
+Use `generate_sprite` with `provider="polza"` for one image, or
+`generate_images` for up to ten coherent variations in one API request. Both
+accept `reference_images`: HTTPS URLs, data URIs, or local files. References are
+sent to the provider so an LLM can retain a game's palette, outline treatment,
+proportions, and character style across new sprites.
+
+```json
+{
+  "prompt": "a forest ranger facing left, idle game sprite",
+  "output_path": "rangers/idle.png",
+  "count": 4,
+  "model": "openai/gpt-image-1.5",
+  "reference_images": ["/assets/style-guide.png", "https://example.com/hero.png"],
+  "aspect_ratio": "1:1",
+  "remove_bg": true,
+  "pixel_size": 4
+}
+```
+
+Set `wait=false` for a long-running generation and query its returned ID using
+`get_generation_status`.
+
+### Native pixel art with PixelLab
+
+Set `PIXELLAB_API_KEY` in `.env` and pass `provider="pixellab"`. PixelLab is
+specialised in game-ready pixel art; with `reference_images` it uses up to four
+style references and generates style-consistent sprites. `generate_images` will
+create one background job per requested variant, so `count` is reliable even
+when a model does not offer a multi-image parameter.
+
 ### 4. Run as MCP server
 
 ```bash
@@ -123,6 +170,20 @@ Returns: `output_path`, `db_id`, `generation_time`, and other metadata.
 
 Generate multiple sprites in one call. Each is saved to the feedback DB.
 
+Each spec may also set `provider: "polza"`, `model`, `reference_images`,
+`aspect_ratio`, `quality`, `count`, and `wait`.
+
+#### `generate_images`
+
+Generate 1–10 variants from one prompt through Polza.ai. It accepts the same
+style-reference fields as cloud `generate_sprite` and saves every finished
+variant to the feedback DB.
+
+#### `get_generation_status`
+
+Check a non-blocking Polza generation by its `generation_id` and retrieve its
+status, output sources, usage, warnings, or error.
+
 ### Feedback
 
 #### `rate_sprite`
@@ -167,6 +228,9 @@ Get database statistics: total sprites, rated, unrated, average rating.
 | `IMAGEGEN_MODEL_DIR` | `~/models/flux2-klein-4b` | Path to base model |
 | `IMAGEGEN_LORA_DIR` | `~/models/pixel-art-lora` | Path to LoRA adapter |
 | `IMAGEGEN_OUTPUT_DIR` | `./output` | Default output directory |
+| `POLZA_API_KEY` | — | Polza.ai API key; required for cloud generation |
+| `POLZA_IMAGE_MODEL` | `openai/gpt-image-1.5` | Default Polza image model |
+| `PIXELLAB_API_KEY` | — | PixelLab API key; required for `pixellab` provider |
 
 ### Swapping models