kiapi 0.1.0__py3-none-any.whl

kiapi/capabilities/flux2/README.ja.md

@@ -0,0 +1,260 @@
+# flux2
+
+[English](README.md) | **日本語**
+
+[mflux FLUX.2 Klein](https://github.com/filipstrand/mflux/blob/main/src/mflux/models/flux2/README.md) で、画像生成・画像編集・LoRA 学習機能を提供します。
+
+- **generate**:
+  - txt2img / img2img
+- **edit**:
+  - Files API の 1 枚以上の参照画像を使う複数参照編集
+- **train**:
+  - 自前データセット ZIP から LoRA アダプタを学習
+
+## API
+
+| Endpoint | Name | Description |
+|---|---|---|
+| `POST /v1/image/flux2/generate` | 画像生成 | プロンプトから画像を生成。`init_image` FileRef がある場合は img2img。 |
+| `POST /v1/image/flux2/edit` | 画像編集 | Files API の `images` FileRef 配列を参照画像として編集。 |
+| `POST /v1/image/flux2/train` | LoRA 学習 | データセット ZIP から LoRA アダプタを学習。**常に async**。 |
+| `GET /v1/image/flux2/models` | モデル一覧 | 利用可能なモデルの一覧を返す。 |
+| `GET /v1/image/flux2/openapi.json` | OpenAPI | 詳細な入出力仕様、使い方、TIPS を返す。 |
+
+## API Docs
+
+- [OpenAPI JSON](https://kiarina.github.io/kiapi/v1/image/flux2/openapi.json)
+- [Swagger UI](https://kiarina.github.io/kiapi/v1/image/flux2/docs.html)
+- [ReDoc](https://kiarina.github.io/kiapi/v1/image/flux2/redoc.html)
+
+## Dependencies
+
+| Package | License | Description |
+|---|---|---|
+| [mflux](https://github.com/filipstrand/mflux) | MIT | FLUX.2 Klein の生成・編集・LoRA 学習を MLX 上で実行。 |
+
+## Models
+
+| Model | License | Terms | Size | Description |
+|---|---|---|---:|---|
+| [black-forest-labs/FLUX.2-klein-9B](https://huggingface.co/black-forest-labs/FLUX.2-klein-9B) | FLUX Non-Commercial License | 要 | 52.9 GB | `klein-9b`（デフォルト）。少ステップ向けの 9B Klein。既定は `steps: 4`、`guidance: 1.0`、`quantize: null`。生成・編集に使える。 |
+| [black-forest-labs/FLUX.2-klein-base-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-base-4B) | Apache-2.0 | 不要 | 23.7 GB | `klein-base-4b`。base variant。既定は `steps: 40`、`guidance: 1.0`、`quantize: 8`。生成・編集・LoRA 学習に使える。 |
+| [black-forest-labs/FLUX.2-klein-base-9B](https://huggingface.co/black-forest-labs/FLUX.2-klein-base-9B) | FLUX Non-Commercial License | 要 | 52.9 GB | `klein-base-9b`。base variant。既定は `steps: 40`、`guidance: 1.0`、`quantize: 8`。生成・編集・LoRA 学習に使える。 |
+
+## Notes
+
+- **サイズ制約**:
+  `width` / `height` は 16 の倍数。既定は `1024 x 1024`、上限は `2048 x 2048`。
+  `steps` の上限は `100`。
+- **LoRA 適用**:
+  `loras: [{"file": {"type": "file_id", "file_id": "..."}, "scale": 1.0}]` で学習済みアダプタを適用する。
+  最大 4 つまで。`scale` は効きの強さ。
+- **LoRA 学習データセット**:
+  ZIP は画像をトップレベル、または単一サブフォルダに入れる。
+  `training_mode: "text"` では各画像に同じ語幹の `.txt` キャプションが必要。
+  `training_mode: "edit"` では `*_in.*` / `*_out.*` の画像ペアと `*_in.txt` プロンプトが必要。
+- **メモリ目安**:
+  `klein-9b` は約 29 GiB、edit では約 31.6 GiB のピーク実測。
+  `klein-base-4b` は q8 / 512 / 40 steps で約 9.1 GiB、
+  `klein-base-9b` は約 16.8 GiB。train は `KIAPI_FLUX2_TRAIN_RESERVE_GB`
+  既定 24 GiB を予約する。
+
+## Quickstart
+
+### generate — txt2img
+
+```bash
+jq -n \
+'{
+  model: "klein-9b",
+  mode: "sync",
+  prompt: "a cafe storefront, a sign clearly reads CAFE, bright daylight",
+  width: 512,
+  height: 512,
+  seed: 1
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/flux2/generate \
+-H 'Content-Type: application/json' \
+--data-binary @- \
+-o flux2.png
+```
+
+Job JSON が欲しい場合:
+
+```bash
+jq -n \
+'{
+  model: "klein-9b",
+  mode: "sync",
+  prompt: "a small robot watering flowers, clean studio illustration",
+  width: 512,
+  height: 512,
+  seed: 2
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/flux2/generate \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary @- |
+jq .
+```
+
+### generate — img2img
+
+先にソース画像をアップロードする:
+
+```bash
+IMG=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@source.png" | jq -r .file_id)
+```
+
+```bash
+jq -n \
+--arg img "$IMG" \
+'{
+  model: "klein-9b",
+  mode: "sync",
+  prompt: "turn this into a polished cozy illustration",
+  init_image: {type: "file_id", file_id: $img},
+  image_strength: 0.45,
+  width: 1024,
+  height: 576,
+  seed: 7
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/flux2/generate \
+-H 'Content-Type: application/json' \
+--data-binary @- \
+-o flux2-img2img.png
+```
+
+`image_strength` は 0-1。小さいほど入力画像を強く残し、大きいほどプロンプト側に寄る。
+
+### edit — 複数参照画像での編集
+
+```bash
+REF1=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@mascot.png" | jq -r .file_id)
+REF2=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@object.png" | jq -r .file_id)
+
+jq -n \
+--arg ref1 "$REF1" \
+--arg ref2 "$REF2" \
+'{
+  model: "klein-9b",
+  mode: "sync",
+  prompt: "make a playful illustration combining the mascot and object",
+  images: [{type: "file_id", file_id: $ref1}, {type: "file_id", file_id: $ref2}],
+  width: 1024,
+  height: 576,
+  seed: 9
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/flux2/edit \
+-H 'Content-Type: application/json' \
+--data-binary @- \
+-o flux2-edit.png
+```
+
+### async
+
+```bash
+JOB=$(
+jq -n \
+'{
+  model: "klein-9b",
+  mode: "async",
+  prompt: "a cinematic product photo of a glass teapot",
+  width: 512,
+  height: 512,
+  seed: 11
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/flux2/generate \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary @- |
+jq -r .job_id
+)
+
+curl -sS http://localhost:${PORT:-8000}/v1/jobs/$JOB | jq .
+```
+
+完了後、Job の `artifacts[0]` または `result.file_id` を使って画像を取得する:
+
+```bash
+FID=$(curl -sS http://localhost:${PORT:-8000}/v1/jobs/$JOB | jq -r .result.file_id)
+curl -sS http://localhost:${PORT:-8000}/v1/files/$FID/download -o flux2-async.png
+```
+
+### train — LoRA
+
+`training_mode: "text"` のデータセット例:
+
+```text
+my_lora/
+  sample_01.png
+  sample_01.txt
+  sample_02.png
+  sample_02.txt
+```
+
+データセット ZIP を作り、Files API にアップロードする:
+
+```bash
+(cd my_lora && zip -q -r - .) > dataset.zip
+
+DS=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@dataset.zip" | jq -r .file_id)
+```
+
+学習を開始する。train は常に async:
+
+```bash
+JOB=$(
+jq -n \
+--arg ds "$DS" \
+'{
+  model: "klein-base-4b",
+  dataset: {type: "file_id", file_id: $ds},
+  training_mode: "text",
+  num_epochs: 10,
+  lora_rank: 8
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/flux2/train \
+-H 'Content-Type: application/json' \
+--data-binary @- |
+jq -r .job_id
+)
+
+echo "$JOB"
+```
+
+完了までポーリングし、学習済みアダプタの `file_id` を取得する:
+
+```bash
+until STATUS=$(curl -sS http://localhost:${PORT:-8000}/v1/jobs/$JOB | jq -r .status) && \
+  [ "$STATUS" != "queued" ] && [ "$STATUS" != "running" ]; do
+  sleep 5
+done
+
+ADAPTER=$(curl -sS http://localhost:${PORT:-8000}/v1/jobs/$JOB | jq -r .result.adapter_file_id)
+echo "$ADAPTER"
+```
+
+### 学習済み LoRA で生成
+
+```bash
+jq -n \
+--arg adapter "$ADAPTER" \
+'{
+  model: "klein-base-4b",
+  mode: "sync",
+  prompt: "<your trigger word> as a clean editorial illustration",
+  width: 512,
+  height: 512,
+  seed: 13,
+  loras: [{file: {type: "file_id", file_id: $adapter}, scale: 1.0}]
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/flux2/generate \
+-H 'Content-Type: application/json' \
+--data-binary @- \
+-o flux2-lora.png
+```

kiapi/capabilities/flux2/README.md

@@ -0,0 +1,241 @@
+# flux2
+
+**English** | [日本語](README.ja.md)
+
+[mflux FLUX.2 Klein](https://github.com/filipstrand/mflux/blob/main/src/mflux/models/flux2/README.md) provides image generation, image editing, and LoRA learning functions.
+
+- **generate**:
+  - txt2img / img2img
+- **edit**:
+  - Multi-reference editing using one or more reference images from the Files API
+- **train**:
+  - Learn LoRA adapter from your own dataset ZIP
+
+## API
+
+| Endpoint | Name | Description |
+|---|---|---|
+| `POST /v1/image/flux2/generate` | Image generation | Generate image from prompt. `init_image` img2img if FileRef exists. |
+| `POST /v1/image/flux2/edit` | Image editing | Edit the `images` FileRef array of Files API as a reference image. |
+| `POST /v1/image/flux2/train` | LoRA learning | Learn LoRA adapter from dataset ZIP. **Always async**. |
+| `GET /v1/image/flux2/models` | List of models | Return the list of available models. |
+| `GET /v1/image/flux2/openapi.json` | OpenAPI | Returns detailed input/output specifications, usage, and TIPS. |
+
+## API Docs
+
+- [OpenAPI JSON](https://kiarina.github.io/kiapi/v1/image/flux2/openapi.json)
+- [Swagger UI](https://kiarina.github.io/kiapi/v1/image/flux2/docs.html)
+- [ReDoc](https://kiarina.github.io/kiapi/v1/image/flux2/redoc.html)
+
+## Dependencies
+
+| Package | License | Description |
+|---|---|---|
+| [mflux](https://github.com/filipstrand/mflux) | MIT | FLUX.2 Execute Klein generation, editing, and LoRA learning on MLX. |
+
+## Models
+
+| Model | License | Terms | Size | Description |
+|---|---|---|---:|---|
+| [black-forest-labs/FLUX.2-klein-9B](https://huggingface.co/black-forest-labs/FLUX.2-klein-9B) | FLUX Non-Commercial License | Required | 52.9 GB | `klein-9b` (default). 9B Klein for small steps. Defaults are `steps: 4`, `guidance: 1.0`, `quantize: null`. Can be used for generation and editing. |
+| [black-forest-labs/FLUX.2-klein-base-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-base-4B) | Apache-2.0 | Not required | 23.7 GB | `klein-base-4b`. base variant. Defaults are `steps: 40`, `guidance: 1.0`, `quantize: 8`. Can be used for generation, editing, and LoRA learning. |
+| [black-forest-labs/FLUX.2-klein-base-9B](https://huggingface.co/black-forest-labs/FLUX.2-klein-base-9B) | FLUX Non-Commercial License | Required | 52.9 GB | `klein-base-9b`. base variant. Defaults are `steps: 40`, `guidance: 1.0`, `quantize: 8`. Can be used for generation, editing, and LoRA learning. |
+
+## Notes
+
+- **Size constraints**:
+  `width` / `height` are multiples of 16. Default is `1024 x 1024`, upper limit is `2048 x 2048`.
+  The upper limit of `steps` is `100`.
+- **LoRA applied**:
+  Apply the learned adapter with `loras: [{"file": {"type": "file_id", "file_id": "..."}, "scale": 1.0}]`.
+  Up to 4. `scale` is the strength of the effect.
+- **LoRA training dataset**:
+  ZIP puts images into a top-level or single subfolder.
+  `training_mode: "text"` requires each image to have a `.txt` caption with the same stem.
+  `training_mode: "edit"` requires `*_in.*` / `*_out.*` image pairs and `*_in.txt` prompt.
+- **Memory guideline**:
+  `klein-9b` has a peak measurement of about 29 GiB, and edit has a peak measurement of about 31.6 GiB.
+  `klein-base-4b` is about 9.1 GiB with q8 / 512 / 40 steps,
+  `klein-base-9b` is approximately 16.8 GiB. train is `KIAPI_FLUX2_TRAIN_RESERVE_GB`
+  Reserve default 24 GiB.
+
+## Quickstart
+
+### generate — txt2img
+```bash
+jq -n \
+'{
+  model: "klein-9b",
+  mode: "sync",
+  prompt: "a cafe storefront, a sign clearly reads CAFE, bright daylight",
+  width: 512,
+  height: 512,
+  seed: 1
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/flux2/generate \
+-H 'Content-Type: application/json' \
+--data-binary @- \
+-o flux2.png
+```
+If you want Job JSON:
+```bash
+jq -n \
+'{
+  model: "klein-9b",
+  mode: "sync",
+  prompt: "a small robot watering flowers, clean studio illustration",
+  width: 512,
+  height: 512,
+  seed: 2
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/flux2/generate \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary @- |
+jq .
+```
+### generate — img2img
+
+Upload the source image first:
+```bash
+IMG=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@source.png" | jq -r .file_id)
+```
+
+```bash
+jq -n \
+--arg img "$IMG" \
+'{
+  model: "klein-9b",
+  mode: "sync",
+  prompt: "turn this into a polished cozy illustration",
+  init_image: {type: "file_id", file_id: $img},
+  image_strength: 0.45,
+  width: 1024,
+  height: 576,
+  seed: 7
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/flux2/generate \
+-H 'Content-Type: application/json' \
+--data-binary @- \
+-o flux2-img2img.png
+```
+`image_strength` is 0-1. The smaller the value, the stronger the input image remains, and the larger the value, the closer it is to the prompt side.
+
+### edit — Editing with multiple reference images
+```bash
+REF1=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@mascot.png" | jq -r .file_id)
+REF2=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@object.png" | jq -r .file_id)
+
+jq -n \
+--arg ref1 "$REF1" \
+--arg ref2 "$REF2" \
+'{
+  model: "klein-9b",
+  mode: "sync",
+  prompt: "make a playful illustration combining the mascot and object",
+  images: [{type: "file_id", file_id: $ref1}, {type: "file_id", file_id: $ref2}],
+  width: 1024,
+  height: 576,
+  seed: 9
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/flux2/edit \
+-H 'Content-Type: application/json' \
+--data-binary @- \
+-o flux2-edit.png
+```
+
+### async
+
+```bash
+JOB=$(
+jq -n \
+'{
+  model: "klein-9b",
+  mode: "async",
+  prompt: "a cinematic product photo of a glass teapot",
+  width: 512,
+  height: 512,
+  seed: 11
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/flux2/generate \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary @- |
+jq -r .job_id
+)
+
+curl -sS http://localhost:${PORT:-8000}/v1/jobs/$JOB | jq .
+```
+Once completed, use the Job's `artifacts[0]` or `result.file_id` to get the image:
+```bash
+FID=$(curl -sS http://localhost:${PORT:-8000}/v1/jobs/$JOB | jq -r .result.file_id)
+curl -sS http://localhost:${PORT:-8000}/v1/files/$FID/download -o flux2-async.png
+```
+### train — LoRA
+
+Example dataset for `training_mode: "text"`:
+```text
+my_lora/
+  sample_01.png
+  sample_01.txt
+  sample_02.png
+  sample_02.txt
+```
+Create a dataset ZIP and upload it to the Files API:
+```bash
+(cd my_lora && zip -q -r - .) > dataset.zip
+
+DS=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@dataset.zip" | jq -r .file_id)
+```
+Start learning. train is always async:
+```bash
+JOB=$(
+jq -n \
+--arg ds "$DS" \
+'{
+  model: "klein-base-4b",
+  dataset: {type: "file_id", file_id: $ds},
+  training_mode: "text",
+  num_epochs: 10,
+  lora_rank: 8
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/flux2/train \
+-H 'Content-Type: application/json' \
+--data-binary @- |
+jq -r .job_id
+)
+
+echo "$JOB"
+```
+Poll until completion and get the learned adapter's `file_id`:
+```bash
+until STATUS=$(curl -sS http://localhost:${PORT:-8000}/v1/jobs/$JOB | jq -r .status) && \
+  [ "$STATUS" != "queued" ] && [ "$STATUS" != "running" ]; do
+  sleep 5
+done
+
+ADAPTER=$(curl -sS http://localhost:${PORT:-8000}/v1/jobs/$JOB | jq -r .result.adapter_file_id)
+echo "$ADAPTER"
+```
+### Generated with trained LoRA
+```bash
+jq -n \
+--arg adapter "$ADAPTER" \
+'{
+  model: "klein-base-4b",
+  mode: "sync",
+  prompt: "<your trigger word> as a clean editorial illustration",
+  width: 512,
+  height: 512,
+  seed: 13,
+  loras: [{file: {type: "file_id", file_id: $adapter}, scale: 1.0}]
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/flux2/generate \
+-H 'Content-Type: application/json' \
+--data-binary @- \
+-o flux2-lora.png
+```

kiapi/capabilities/flux2/__init__.py

@@ -0,0 +1,36 @@
+"""flux2 family — FLUX.2 Klein generation/edit/LoRA-training via mflux.
+
+Endpoints: ``POST /v1/image/flux2/{generate,edit,train}``. ``generate`` is
+text-to-image (img2img when ``init_image_file_id`` is supplied), ``edit`` is
+multi-reference image editing, and ``train`` LoRA-finetunes base variants on
+captioned images or ``*_in`` / ``*_out`` edit pairs (always async). LoRA adapters
+and a ``quantize`` override run on a one-off transient model; otherwise the
+resident model is used.
+"""
+
+from kiapi.capabilities import ValidationError
+
+from ._helpers.register import register
+from ._helpers.validate_edit import validate_edit
+from ._helpers.validate_generate import validate_generate
+from ._operations.handle_edit import handle_edit
+from ._operations.handle_generate import handle_generate
+from ._operations.handle_train import handle_train
+from ._settings import settings_manager
+from ._views.edit_request import EditRequest
+from ._views.generate_request import GenerateRequest
+from ._views.train_request import TrainRequest
+
+__all__ = [
+    "EditRequest",  # ._views
+    "GenerateRequest",  # ._views
+    "TrainRequest",  # ._views
+    "ValidationError",  # kiapi.capabilities
+    "handle_edit",  # ._operations
+    "handle_generate",  # ._operations
+    "handle_train",  # ._operations
+    "register",  # ._helpers
+    "settings_manager",  # ._settings
+    "validate_edit",  # ._helpers
+    "validate_generate",  # ._helpers
+]

kiapi/capabilities/flux2/_constants/description.py

@@ -0,0 +1,81 @@
+DESCRIPTION = """Image generation, editing, and LoRA training (FLUX.2 Klein via mflux).
+
+Three operations on Black Forest Labs' FLUX.2 Klein models: `/generate`
+(text-to-image, or image-to-image when `init_image` is supplied), `/edit`
+(multi-reference image editing), and `/train` (LoRA finetune).
+
+## Upstream docs
+- [mflux — FLUX.2](https://github.com/filipstrand/mflux/blob/main/src/mflux/models/flux2/README.md) — the MLX engine kiapi runs
+- [FLUX.2-klein-9B](https://huggingface.co/black-forest-labs/FLUX.2-klein-9B) — distilled `klein-9b` weights
+- [FLUX.2-klein-base-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-base-4B) / [base-9B](https://huggingface.co/black-forest-labs/FLUX.2-klein-base-9B) — trainable base weights
+
+## Models
+- **klein-9b** (default) — distilled. Fast, few steps (default 4), unquantized.
+  The everyday choice for generate/edit.
+- **klein-base-4b** — base. Slower (default 40 steps, q8) but trainable; the
+  default `/train` target.
+- **klein-base-9b** — base. Highest quality of the three, slowest; also trainable.
+
+Pick the variant with `model` (aliases like `flux2-klein-9b` are accepted);
+discover variants at `GET /v1/image/flux2/models`. Variant-dependent defaults
+(`steps` / `guidance` / `quantize`) are filled in server-side when omitted, and
+the resolved values are recorded in the result `params`. Only base variants are
+trainable — `klein-9b` is rejected by `/train`.
+
+## generate vs edit
+- **generate** is text-to-image; pass `init_image` (+ optional `image_strength`)
+  to seed an img2img run from one image.
+- **edit** takes a list of reference `images` for multi-reference editing /
+  composition under a single prompt.
+
+## Resident vs transient runs
+The warmed, resident model uses the server-default quantization. A request that
+either supplies `loras` or sets a `quantize` differing from the resident model
+builds a **one-off transient model** for that call — weights load fresh, so it is
+slower and not reused. For the fast path, omit `loras` and leave `quantize` unset.
+
+## LoRA workflow
+Train an adapter via `/train` (always async, base variants only), then apply it on
+`/generate` or `/edit` by passing its `file` id in `loras` (up to 4, each
+`{file, scale}`). The dataset is a ZIP uploaded to the Files API; its layout
+depends on `training_mode`.
+
+**`training_mode=text`** — each image has a same-stem `.txt` caption:
+
+```
+dataset.zip
+├── cat_01.png      # image
+├── cat_01.txt      # same-stem caption: "a photo of a tabby cat"
+├── cat_02.jpg
+└── cat_02.txt
+```
+
+**`training_mode=edit`** — `*_in.*` / `*_out.*` image pairs, the `*_in.txt`
+holding the edit prompt:
+
+```
+dataset.zip
+├── 01_in.png       # source image
+├── 01_in.txt       # edit prompt: "make it snow"
+├── 01_out.png      # target image
+├── 02_in.jpg
+├── 02_in.txt
+└── 02_out.jpg
+```
+
+## TIPS
+- For a quick image, call `sync` without `Accept: application/json` to get the
+  raw bytes straight back (`curl -o out.png`).
+- `width`/`height` must be multiples of 16 and at most 2048x2048 (default 1024).
+- `klein-9b` is the fast default; reach for the base variants only when you need
+  their quality or want to train.
+- First use downloads the FLUX.2 weights; run `kiapi activate` ahead of time to
+  avoid a cold-start download on the first request.
+
+## Performance
+- **klein-9b**: ~29 GiB peak RSS for 512 text/img2img, ~31.6 GiB for edit.
+- **klein-base-4b**: ~9.1 GiB peak at q8/512/40 steps.
+- **klein-base-9b**: ~16.8 GiB peak at q8/512/40 steps.
+- Transient runs (any `loras` or a `quantize` override) rebuild the model each
+  call and are slower than the resident path.
+"""