feat: store async generated images as WebP

docs/API.md

@@ -92,7 +92,7 @@ Success (`200`):
 
 Generation responses also include `generation_id`, `request_intake_sec`, and `total_sec`. `request_intake_sec` covers the request reaching and being parsed by the proxy before the generation is queued; `elapsed_sec` is the upstream call time; `total_sec` runs from request receipt through completion. These measurements help separate slow client uploads from slow model calls.
 
-An image can be returned as `b64_json`, or as a URL when the upstream returns a hosted image. Decode `b64_json` as standard Base64 before saving it. Avoid printing or logging generated image data in an agent script.
+Direct synchronous generation retains its JSON response with image bytes in `b64_json`. For async jobs, request `include_result=false` and use the binary download link described below. The legacy async `include_result=true` response remains supported and reconstructs Base64 from the stored image file.
 
 ## Generate asynchronously and poll
 
@@ -113,10 +113,10 @@ Queued response (`200`):
 {"job_id":"<uuid>","status":"queued","poll_url":"/v1/jobs/<uuid>"}
 ```
 
-Poll every couple of seconds. Include both the `client_id` query parameter and `x-client-secret` header:
+Poll every couple of seconds. To avoid transferring the generated image inside every completed status response, set `include_result=false`. Include both the `client_id` query parameter and `x-client-secret` header:
 
 ```sh
-curl -sS "$BASE_URL/v1/jobs/<uuid>?client_id=booth-01" \
+curl -sS "$BASE_URL/v1/jobs/<uuid>?client_id=booth-01&include_result=false" \
   -H 'x-client-secret: replace-with-a-client-secret'
 ```
 
@@ -126,7 +126,20 @@ While running:
 {"job_id":"<uuid>","status":"processing","created_at":1234567890.0,"updated_at":1234567891.0}
 ```
 
-On success, `status` is `completed` and a `result` field contains the synchronous response object. On failure, `status` is `failed` and `error` contains a sanitized message. Jobs are scoped to the owning `client_id`; an unknown job ID and a job belonging to another client both return `404`.
+On success with `include_result=false`, `status` is `completed` and `result` contains generation metadata plus image descriptors. Each image descriptor includes a `download_url` for binary images, or the upstream `url` when the provider supplies a hosted URL. Download each binary image directly; do not Base64-decode it:
+
+```sh
+curl -sS "$BASE_URL/v1/jobs/<uuid>/images/0?token=<signed-token-from-download_url>" \
+  -o generated.webp
+```
+
+Async generated images are stored as WebP at quality 90 by default (`OUTPUT_WEBP_QUALITY` can be set from 1 to 100). The image endpoint and result descriptor use `image/webp`; save the downloaded bytes with a `.webp` extension. Convert to PNG or JPEG in the client only if a downstream tool requires that format.
+
+`GET /v1/jobs/{job_id}/images/{image_index}?token=...` serves raw image bytes from the proxy's private output directory with the corresponding image MIME type and inline content disposition. Links in the completed-job response are signed, scoped to that job and image, and expire after one hour by default (`IMAGE_LINK_TTL_SECONDS` configures the lifetime). Open the full `download_url` directly in a browser; no client-secret header is needed. Treat the URL like a temporary password: anyone who has it can view that image until it expires. An authenticated client may also call the image route with `client_id` and `x-client-secret` instead of a token. Unknown and cross-client jobs return `404`; an incomplete job returns `409`; expired links or deleted images return `410`.
+
+Async WebP output files are stored under `OUTPUT_DIR` (default `./data/generated`) with directory mode `0700` and file mode `0600`. Image files are automatically deleted after 24 hours by default (`OUTPUT_RETENTION_SECONDS`), with a cleanup pass at startup and every five minutes. Job metadata, timing, and cost history remain in SQLite after image deletion; a deleted image endpoint returns `410`. Completed and failed jobs clear their original prompt and uploaded image payload from SQLite. The database retains only compact result metadata and execution history; startup migrates older completed outputs to WebP and vacuums SQLite to reclaim freed pages.
+
+For compatibility, `include_result` defaults to `true`; that legacy mode includes Base64 image data in the status response. New clients should always request `include_result=false` and download images from their `download_url`. On failure, status is `failed` and `error` contains a sanitized message.
 
 ## Models and parameters