z-image

README.md

@@ -10,7 +10,7 @@ ESP32-S3 works as a Wi-Fi REST controller and replaces Android App logic:
 ## Features
 
 - Wi-Fi STA-only mode (configured SSID/password; no SoftAP fallback)
-- Built-in web UI at `/` for connect/status, text print, and image upload print
+- Built-in web UI at `/` for connect/status, text print, and Z-Image prompt print
 - BLE central client auto-scan/connect to printer name
 - Async print queue with jobs (`queued/running/success/failed/canceled`)
 - Printer precheck (paper / battery / temperature)
@@ -33,7 +33,7 @@ ESP32-S3 works as a Wi-Fi REST controller and replaces Android App logic:
     - `GET /v1/printer/status`
   - Print:
     - `POST /v1/print/raster`
-    - `POST /v1/print/image` (direct PNG binary upload, no base64)
+    - `POST /v1/print/image` (JSON prompt -> generate image -> print, also compatible with direct PNG binary upload)
     - `POST /v1/print/qr`
     - `POST /v1/print/text`
     - `POST /v1/print/receipt`
@@ -81,6 +81,13 @@ In `menuconfig -> TQ Controller Config`:
 - `TQ_WIFI_PASSWORD`
 - `TQ_HTTP_PORT`
 - `TQ_API_KEY` (optional)
+- Z-Image HTTP auth and model fields:
+  - `TQ_Z_IMAGE_API_KEY` (optional, empty means fallback to `TQ_VOICE_API_KEY`)
+  - `TQ_Z_IMAGE_API_ENDPOINT`
+  - `TQ_Z_IMAGE_MODEL`
+  - `TQ_Z_IMAGE_DEFAULT_SIZE`
+  - `TQ_Z_IMAGE_TIMEOUT_MS`
+  - `TQ_Z_IMAGE_DOWNLOAD_TIMEOUT_MS`
 - Voice WebSocket auth and app fields:
   - `TQ_VOICE_API_KEY`
   - `TQ_VOICE_WORKSPACE_ID`
@@ -121,7 +128,7 @@ The page provides:
 - health/status check
 - connect/disconnect printer
 - submit a simple text print job
-- upload a PNG image (binary payload) and let ESP32-S3 decode/threshold/scale/raster conversion
+- input an image prompt, then let ESP32-S3 call DashScope Z-Image, download PNG, decode/threshold/scale/raster conversion, and print
 - view jobs list
 
 If API key is enabled, input it in the page before invoking actions.
@@ -163,7 +170,25 @@ curl -X POST http://<esp-ip>/v1/print/raster \
   }'
 ```
 
-### Image print (direct PNG upload, no base64)
+### Image print (generate with prompt, then print)
+```bash
+curl -X POST http://<esp-ip>/v1/print/image \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "prompt":"一只坐在窗边的橘猫，午后阳光，胶片质感，写实风格。",
+    "size":"1120*1440",
+    "prompt_extend":false,
+    "threshold":160,
+    "max_height":2200,
+    "scale_to_width":true,
+    "invert":false,
+    "density":"中等",
+    "timeout_ms":45000,
+    "fetch_timeout_ms":15000
+  }'
+```
+
+### Image print (direct PNG upload, backward-compatible)
 ```bash
 curl -X POST 'http://<esp-ip>/v1/print/image?scale_to_width=1&threshold=160&invert=0&max_height=2200&density=medium' \
   -H 'Content-Type: image/png' \
@@ -172,7 +197,7 @@ curl -X POST 'http://<esp-ip>/v1/print/image?scale_to_width=1&threshold=160&inve
 
 Request constraints:
 - Request body limit: 4 MB
-- Suggested image size: <= 3 MB when using built-in Web UI uploader
+- Suggested image size: <= 3 MB when using direct PNG upload compatibility mode
 
 ### QR print
 ```bash
@@ -305,8 +330,9 @@ curl -X POST http://<esp-ip>/v1/voice/session/stop
 
 - BLE side is central/client role, not printer peripheral role.
 - `base64_msb_1bpp` uses Android-compatible bit order (MSB first).
-- `/v1/print/image` accepts raw `image/png` bytes directly (no base64 wrapper).
+- `/v1/print/image` supports two modes: JSON prompt generation (DashScope Z-Image) and raw `image/png` upload (no base64 wrapper).
 - Large buffers for image upload/decode prefer PSRAM first, then fallback to internal RAM.
+- Partition table uses `partitions.csv` with a 4MB `factory` app partition on 16MB flash modules.
 - `/v1/print/text` and `/v1/print/receipt` now support UTF-8 Chinese via embedded 16x16 GB2312 glyphs.
 - Characters outside embedded glyph set are rendered as square fallback boxes.
 - QR encoding uses embedded `qrcodegen` (Project Nayuki C implementation).