kiapi 0.1.0__py3-none-any.whl

kiapi/capabilities/zimage/README.ja.md

@@ -0,0 +1,249 @@
+# zimage
+
+[English](README.md) | **日本語**
+
+[mflux Z-Image](https://github.com/filipstrand/mflux/blob/main/src/mflux/models/z_image/README.md) で、画像生成と LoRA ファインチューニング機能を提供します。
+
+Z-Image は比較的軽量に扱える画像生成モデルです。
+`turbo` は少ステップで高速、`base` は guidance / negative prompt を使った調整向きです。
+
+- **generate**: テキストから画像を生成
+- **train**: キャプション付き画像 ZIP から LoRA アダプタを学習
+
+## API
+
+| Endpoint | Name | Description |
+|---|---|---|
+| `POST /v1/image/zimage/generate` | 画像生成 | プロンプトから画像を生成。`application/json` の body を渡す。 |
+| `POST /v1/image/zimage/train` | LoRA 学習 | キャプション付き画像 ZIP から LoRA アダプタを学習。常に async。 |
+| `GET /v1/image/zimage/models` | モデル一覧 | 利用可能なモデルの一覧を返す。 |
+| `GET /v1/image/zimage/openapi.json` | OpenAPI | 詳細な入出力仕様、使い方、TIPS を返す。 |
+
+## API Docs
+
+- [OpenAPI JSON](https://kiarina.github.io/kiapi/v1/image/zimage/openapi.json)
+- [Swagger UI](https://kiarina.github.io/kiapi/v1/image/zimage/docs.html)
+- [ReDoc](https://kiarina.github.io/kiapi/v1/image/zimage/redoc.html)
+
+## Dependencies
+
+| Package | License | Description |
+|---|---|---|
+| [mflux](https://github.com/filipstrand/mflux) | MIT | Z-Image の生成と LoRA 学習を MLX 上で実行。 |
+
+## Models
+
+| Model | License | Terms | Size | Description |
+|---|---|---|---:|---|
+| [filipstrand/Z-Image-Turbo-mflux-4bit](https://huggingface.co/filipstrand/Z-Image-Turbo-mflux-4bit) | Tongyi Qianwen License | 不要 | 5.5 GB | `turbo`（デフォルト）。蒸留・少ステップ向け。既定は `steps: 9`、`guidance: null`、`quantize: null`。 |
+| [Tongyi-MAI/Z-Image](https://huggingface.co/Tongyi-MAI/Z-Image) | Apache-2.0 | 不要 | 19 GB | `base`。非 distilled のモデル。既定は `steps: 28`、`guidance: 4.0`、`quantize: 8`。 |
+
+kiapi の登録値では、`turbo` は重み約 `6.0 GiB` / 実行時ヘッドルーム約 `8.0 GiB`、
+`base` は重み約 `12.0 GiB` / 実行時ヘッドルーム約 `16.0 GiB` を見込んでいます。
+
+## Notes
+
+- **画像サイズ**:
+  `width` / `height` は 16 の倍数。既定は `1024 x 1024`、上限は `2048 x 2048`。
+- **steps / guidance**:
+  `steps` は `1..100`。省略時は `turbo` が `9`、`base` が `28`。
+  `turbo` は distilled model なので `guidance` と `negative_prompt` の効果はありません。
+  `base` は `guidance` と `negative_prompt` を使えます。
+- **quantize**:
+  `quantize` は `3` / `4` / `5` / `6` / `8` を指定できます。省略するとモデルごとの既定値を使います。
+  `turbo` は 4-bit 事前量子化 repo を使うため、通常は省略します。
+- **LoRA 適用**:
+  `generate` の `loras` には `[{ "file": {"type": "file_id", "file_id": "..."}, "scale": 1.0 }]` を渡します。
+  既定では最大 4 個まで適用できます。アダプタファイルは Files API に保存されている必要があります。
+- **transient モデル**:
+  mflux は量子化レベルと LoRA をモデル構築時に固定します。`loras` を持つ、または
+  `quantize` を既定値から上書きするリクエストは、その呼び出し用の一時モデルを構築します。
+  常駐モデルを再利用しないため、素の `turbo` / `base` 呼び出しより遅くなります。
+- **出力形式**:
+  `format` は `png`（既定）/ `jpeg` / `webp`。`jpeg` / `webp` では `quality`
+  `1..100`（既定 `90`）を使います。
+- **LoRA 学習データセット**:
+  ZIP のトップレベル、または ZIP 内の単一サブフォルダに画像を置きます。画像ごとに
+  同じ語幹の `.txt` キャプションが必要です。
+
+## Quickstart
+
+### generate - テキストから画像生成
+
+画像だけを保存する:
+
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "a red fox in fresh snow, soft morning light, realistic photo" \
+'{
+  model: "turbo",
+  mode: "sync",
+  prompt: $prompt,
+  width: 1024,
+  height: 1024,
+  seed: 1
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/zimage/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o zimage.png
+```
+
+Job JSON を返す:
+
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "a small robot watering flowers, clean studio illustration" \
+--arg negative_prompt "blurry, low quality" \
+'{
+  model: "base",
+  mode: "sync",
+  prompt: $prompt,
+  negative_prompt: $negative_prompt,
+  width: 512,
+  height: 512,
+  seed: 2
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/zimage/generate \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" |
+jq .
+```
+
+`file_id` が必要な場合はレスポンスヘッダから読めます。
+
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "a red fox in fresh snow" \
+'{
+  mode: "sync",
+  prompt: $prompt,
+  width: 512,
+  height: 512,
+  seed: 1
+}'
+)
+
+FILE_ID=$(curl -sS -D - -o zimage.png \
+-X POST http://localhost:${PORT:-8000}/v1/image/zimage/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+| awk -F': ' 'tolower($1)=="x-kiapi-file-id"{print $2}' | tr -d '\r')
+
+echo "$FILE_ID"
+```
+
+### async
+
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "a cinematic product photo of a glass teapot" \
+'{
+  model: "turbo",
+  mode: "async",
+  prompt: $prompt,
+  width: 512,
+  height: 512,
+  seed: 11
+}'
+)
+
+JOB=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/zimage/generate \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" |
+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 zimage-async.png
+```
+
+### train - LoRA ファインチューニング
+
+画像と同じ語幹の `.txt` キャプションを含む ZIP データセットを用意します。
+
+```text
+dataset/
+  sample_00.png
+  sample_00.txt
+  sample_01.png
+  sample_01.txt
+```
+
+データセット ZIP を作り、Files API にアップロードします。
+
+```bash
+(cd dataset && zip -q -r - .) > dataset.zip
+
+DATASET_ID=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@dataset.zip;type=application/zip" | jq -r .file_id)
+```
+
+学習を開始します。train は常に async です。
+
+```bash
+JOB=$(
+jq -n \
+--arg dataset "$DATASET_ID" \
+'{
+  model: "turbo",
+  dataset: {type: "file_id", file_id: $dataset},
+  num_epochs: 10,
+  lora_rank: 16,
+  max_resolution: 512
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/zimage/train \
+-H 'Content-Type: application/json' \
+--data-binary @- |
+jq -r .job_id
+)
+
+curl -sS http://localhost:${PORT:-8000}/v1/jobs/$JOB | jq .
+```
+
+完了後、`result.adapter_file_id` が学習済みアダプタです。
+
+```bash
+ADAPTER=$(curl -sS http://localhost:${PORT:-8000}/v1/jobs/$JOB | jq -r .result.adapter_file_id)
+```
+
+生成で LoRA を適用します。
+
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "<your trigger word> in a magical garden" \
+--arg adapter "$ADAPTER" \
+'{
+  model: "turbo",
+  mode: "sync",
+  prompt: $prompt,
+  width: 512,
+  height: 512,
+  seed: 7,
+  loras: [{file: {type: "file_id", file_id: $adapter}, scale: 1.0}]
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/zimage/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o zimage-lora.png
+```
+
+`scale` は効きの強さです。`loras` を使うリクエストは毎回一時モデルを構築します。

kiapi/capabilities/zimage/README.md

@@ -0,0 +1,231 @@
+# zimage
+
+**English** | [日本語](README.ja.md)
+
+[mflux Z-Image](https://github.com/filipstrand/mflux/blob/main/src/mflux/models/z_image/README.md) provides image generation and LoRA fine-tuning functionality.
+
+Z-Image is a relatively lightweight image generation model.
+`turbo` is fast with few steps, and `base` is suitable for adjustment using guidance / negative prompt.
+
+- **generate**: Generate image from text
+- **train**: Train LoRA adapter from captioned image ZIP
+
+## API
+
+| Endpoint | Name | Description |
+|---|---|---|
+| `POST /v1/image/zimage/generate` | Image generation | Generate image from prompt. Pass the body of `application/json`. |
+| `POST /v1/image/zimage/train` | LoRA learning | Learn LoRA adapter from captioned image ZIP. Always async. |
+| `GET /v1/image/zimage/models` | List of models | Return a list of available models. |
+| `GET /v1/image/zimage/openapi.json` | OpenAPI | Returns detailed input/output specifications, usage, and TIPS. |
+
+## API Docs
+
+- [OpenAPI JSON](https://kiarina.github.io/kiapi/v1/image/zimage/openapi.json)
+- [Swagger UI](https://kiarina.github.io/kiapi/v1/image/zimage/docs.html)
+- [ReDoc](https://kiarina.github.io/kiapi/v1/image/zimage/redoc.html)
+
+## Dependencies
+
+| Package | License | Description |
+|---|---|---|
+| [mflux](https://github.com/filipstrand/mflux) | MIT | Perform Z-Image generation and LoRA training on MLX. |
+
+## Models
+
+| Model | License | Terms | Size | Description |
+|---|---|---|---:|---|
+| [filipstrand/Z-Image-Turbo-mflux-4bit](https://huggingface.co/filipstrand/Z-Image-Turbo-mflux-4bit) | Tongyi Qianwen License | Not required | 5.5 GB | `turbo` (default). For distillation and small steps. Defaults are `steps: 9`, `guidance: null`, `quantize: null`. |
+| [Tongyi-MAI/Z-Image](https://huggingface.co/Tongyi-MAI/Z-Image) | Apache-2.0 | Not required | 19 GB | `base`. Non-distilled model. Defaults are `steps: 28`, `guidance: 4.0`, `quantize: 8`. |
+
+In kiapi's registered values, `turbo` has a weight of approximately `6.0 GiB` / runtime headroom of approximately `8.0 GiB`,
+`base` is expected to have a weight of approximately `12.0 GiB` / runtime headroom of approximately `16.0 GiB`.
+
+## Notes
+
+- **Image size**:
+  `width` / `height` are multiples of 16. Default is `1024 x 1024`, upper limit is `2048 x 2048`.
+- **steps/guidance**:
+  `steps` is `1..100`. If omitted, `turbo` is `9` and `base` is `28`.
+  Since `turbo` is a distilled model, `guidance` and `negative_prompt` have no effect.
+  `base` can use `guidance` and `negative_prompt`.
+- **quantize**:
+  `quantize` can specify `3` / `4` / `5` / `6` / `8`. If omitted, the default value for each model will be used.
+  `turbo` uses a 4-bit pre-quantized repo, so it is usually omitted.
+- **LoRA applied**:
+  Pass `[{ "file": {"type": "file_id", "file_id": "..."}, "scale": 1.0 }]` to `loras` of `generate`.
+  By default, up to 4 can be applied. Adapter files must be stored in the Files API.
+- **transient model**:
+  mflux fixes the quantization level and LoRA during model construction. has `loras`, or
+  A request to override `quantize` from its default value builds a temporary model for that call.
+  It is slower than a plain `turbo` / `base` call because it does not reuse the resident model.
+- **Output format**:
+  `format` is `png` (default) / `jpeg` / `webp`. `quality` for `jpeg` / `webp`
+  Use `1..100` (default `90`).
+- **LoRA training dataset**:
+  Place images at the top level of the ZIP or in a single subfolder within the ZIP. per image
+  Requires a `.txt` caption with the same stem.
+
+## Quickstart
+
+### generate - generate image from text
+
+Save only the image:
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "a red fox in fresh snow, soft morning light, realistic photo" \
+'{
+  model: "turbo",
+  mode: "sync",
+  prompt: $prompt,
+  width: 1024,
+  height: 1024,
+  seed: 1
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/zimage/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o zimage.png
+```
+Returns Job JSON:
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "a small robot watering flowers, clean studio illustration" \
+--arg negative_prompt "blurry, low quality" \
+'{
+  model: "base",
+  mode: "sync",
+  prompt: $prompt,
+  negative_prompt: $negative_prompt,
+  width: 512,
+  height: 512,
+  seed: 2
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/zimage/generate \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" |
+jq .
+```
+If you need the `file_id`, you can read it from the response header.
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "a red fox in fresh snow" \
+'{
+  mode: "sync",
+  prompt: $prompt,
+  width: 512,
+  height: 512,
+  seed: 1
+}'
+)
+
+FILE_ID=$(curl -sS -D - -o zimage.png \
+-X POST http://localhost:${PORT:-8000}/v1/image/zimage/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+| awk -F': ' 'tolower($1)=="x-kiapi-file-id"{print $2}' | tr -d '\r')
+
+echo "$FILE_ID"
+```
+
+### async
+
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "a cinematic product photo of a glass teapot" \
+'{
+  model: "turbo",
+  mode: "async",
+  prompt: $prompt,
+  width: 512,
+  height: 512,
+  seed: 11
+}'
+)
+
+JOB=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/zimage/generate \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" |
+jq -r .job_id)
+
+curl -sS http://localhost:${PORT:-8000}/v1/jobs/$JOB | jq .
+```
+After completion, 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 zimage-async.png
+```
+### train - LoRA Fine Tuning
+
+Prepare a ZIP dataset containing a `.txt` caption with the same stem as the image.
+```text
+dataset/
+  sample_00.png
+  sample_00.txt
+  sample_01.png
+  sample_01.txt
+```
+Create a dataset ZIP and upload it to the Files API.
+```bash
+(cd dataset && zip -q -r - .) > dataset.zip
+
+DATASET_ID=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@dataset.zip;type=application/zip" | jq -r .file_id)
+```
+Start learning. train is always async.
+```bash
+JOB=$(
+jq -n \
+--arg dataset "$DATASET_ID" \
+'{
+  model: "turbo",
+  dataset: {type: "file_id", file_id: $dataset},
+  num_epochs: 10,
+  lora_rank: 16,
+  max_resolution: 512
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/zimage/train \
+-H 'Content-Type: application/json' \
+--data-binary @- |
+jq -r .job_id
+)
+
+curl -sS http://localhost:${PORT:-8000}/v1/jobs/$JOB | jq .
+```
+After completion, `result.adapter_file_id` is the learned adapter.
+```bash
+ADAPTER=$(curl -sS http://localhost:${PORT:-8000}/v1/jobs/$JOB | jq -r .result.adapter_file_id)
+```
+Apply LoRA on generation.
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "<your trigger word> in a magical garden" \
+--arg adapter "$ADAPTER" \
+'{
+  model: "turbo",
+  mode: "sync",
+  prompt: $prompt,
+  width: 512,
+  height: 512,
+  seed: 7,
+  loras: [{file: {type: "file_id", file_id: $adapter}, scale: 1.0}]
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/zimage/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o zimage-lora.png
+```
+`scale` is the strength of the effect. Every request using `loras` builds a temporary model.

kiapi/capabilities/zimage/__init__.py

@@ -0,0 +1,34 @@
+"""zimage family - Z-Image text-to-image generation via mflux.
+
+Endpoint: ``POST /v1/image/zimage/generate`` (multipart params; txt2img).
+Integrates mflux's Z-Image. Two variants:
+
+  - ``turbo`` (default) - distilled few-step model, pre-quantized 4-bit, fast.
+  - ``base`` - full Z-Image, more steps + guidance, higher quality / slower.
+
+Both are resident MLX models held under the global budget. A request that adds
+``loras`` or overrides ``quantize`` is served by a one-off transient model
+(mflux bakes those in at load time) via ``memory.reserve()`` instead. Sync/async
+via ``mode``; the PNG lands in the Files API.
+"""
+
+from kiapi.capabilities import ValidationError
+
+from ._helpers.register import register
+from ._helpers.validate_generate import validate_generate
+from ._operations.handle_generate import handle_generate
+from ._operations.handle_train import handle_train
+from ._settings import settings_manager
+from ._views.generate_request import GenerateRequest
+from ._views.train_request import TrainRequest
+
+__all__ = [
+    "GenerateRequest",
+    "TrainRequest",
+    "ValidationError",
+    "handle_generate",
+    "handle_train",
+    "register",
+    "settings_manager",
+    "validate_generate",
+]

kiapi/capabilities/zimage/_constants/description.py

@@ -0,0 +1,73 @@
+DESCRIPTION = """Fast text-to-image generation and LoRA training (Z-Image via mflux).
+
+Two operations on Alibaba's Z-Image models: `/generate` (text-to-image) and
+`/train` (LoRA finetune). Z-Image is txt2img only — there is no image-to-image
+edit endpoint. To edit an existing image, use the ernie / qwen / flux2 families.
+
+## Upstream docs
+- [mflux — Z-Image](https://github.com/filipstrand/mflux/blob/main/src/mflux/models/z_image/README.md) — the MLX engine kiapi runs
+- [Tongyi-MAI/Z-Image](https://huggingface.co/Tongyi-MAI/Z-Image) — `base` weights
+
+## Models
+- **turbo** (default) — `filipstrand/Z-Image-Turbo-mflux-4bit`. Distilled,
+  few-step (default 9), pre-quantized 4-bit, no guidance. The everyday choice.
+- **base** — `Tongyi-MAI/Z-Image`. The full model: more steps (default 28) and
+  guidance (default 4.0), 8-bit by default. Higher quality but slower.
+
+Pick the variant with `model`; discover variants at
+`GET /v1/image/zimage/models`. Variant-dependent defaults (`steps` / `guidance` /
+`quantize`) are filled in server-side when omitted, and the resolved values are
+recorded in the result `params`. `negative_prompt` is most effective on `base`
+with guidance > 1; on the distilled `turbo` (no guidance) it has little effect.
+
+## 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 — mflux bakes those in at load
+time, so weights load fresh and the run is slower and not reused. For the fast
+path, omit `loras` and leave `quantize` unset.
+
+## LoRA workflow
+Train an adapter from a captioned image set via `/train` (always async), then
+apply it on `/generate` by passing its `adapter_file_id` in `loras` (up to 4,
+each `{file, scale}`). Dataset = a ZIP uploaded to the Files API with a same-stem
+`.txt` caption next to each image (`cat.png` + `cat.txt`); images may sit at the
+top level or in a single subfolder, and `preview*` images are exempt from the
+caption requirement.
+
+```
+dataset.zip
+├── cat_01.png      # image
+├── cat_01.txt      # same-stem caption: "a photo of a tabby cat"
+├── cat_02.jpg
+├── cat_02.txt
+└── preview.png     # optional preview, no caption needed
+```
+
+A single wrapping subfolder is also accepted (the images just need to live
+together under one directory):
+
+```
+dataset.zip
+└── cats/
+    ├── cat_01.png
+    ├── cat_01.txt
+    └── ...
+```
+
+## 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.
+- First use downloads the Z-Image weights; run `kiapi activate` ahead of time to
+  avoid a cold-start download on the first request.
+
+## Performance
+- **turbo**: ~9 steps, pre-quantized 4-bit; the fast default.
+- **base**: full model, many steps, 8-bit by default — prefer turbo unless you
+  need its quality.
+- First request is slower while weights load + convert; then the model is
+  resident until its TTL frees it.
+- Transient runs (any `loras` or a `quantize` override) rebuild the model each
+  call and are slower than the resident path.
+"""

kiapi/capabilities/zimage/_helpers/register.py

@@ -0,0 +1,62 @@
+"""Register zimage's models + OpenAPI description in the global registries."""
+
+from kiapi.core.capability import CapabilitySpec, capability_spec_registry
+from kiapi.core.model import ModelSpec, model_registry
+from kiapi.core.setup import HfSnapshotResource
+
+from .._constants.description import DESCRIPTION
+from .._models import zimage
+from .._settings import settings_manager
+
+
+def register() -> None:
+    capability_spec_registry.register(
+        CapabilitySpec(
+            name="zimage",
+            domain="image",
+            title="kiapi Z-Image API",
+            summary="Generate images and train LoRA adapters with Z-Image models.",
+            description=DESCRIPTION,
+            openapi_path="/v1/image/zimage/openapi.json",
+            docs_path="/v1/image/zimage/docs",
+            redoc_path="/v1/image/zimage/redoc",
+            path_prefixes=("/v1/image/zimage",),
+        )
+    )
+
+    settings = settings_manager.get_settings()
+
+    model_registry.register(
+        ModelSpec(
+            name="turbo",
+            family="zimage",
+            domain="image",
+            repo=settings.turbo_repo,
+            module=zimage,
+            weight_gb=6.0,
+            peak_headroom_gb=8.0,
+            framework="mlx",
+            priority=0,
+            default=True,
+            setup_resources=(
+                HfSnapshotResource(repo=settings.turbo_repo, disk_gb=5.5),
+            ),
+        )
+    )
+
+    model_registry.register(
+        ModelSpec(
+            name="base",
+            family="zimage",
+            domain="image",
+            repo=settings.base_repo,
+            module=zimage,
+            weight_gb=12.0,
+            peak_headroom_gb=16.0,
+            framework="mlx",
+            priority=0,
+            setup_resources=(
+                HfSnapshotResource(repo=settings.base_repo, disk_gb=19.0),
+            ),
+        )
+    )

kiapi/capabilities/zimage/_helpers/validate_generate.py

@@ -0,0 +1,37 @@
+from kiapi.capabilities import ValidationError
+
+from .._settings import ZimageSettings, settings_manager
+from .._views.generate_request import GenerateRequest
+
+_MULTIPLE = 16
+
+
+def validate_generate(req: GenerateRequest, *, variant: str) -> None:
+    settings = settings_manager.get_settings()
+    _validate_generate(req, settings, variant=variant)
+
+
+def _validate_generate(
+    req: GenerateRequest, settings: ZimageSettings, *, variant: str
+) -> None:
+    width = req.width if req.width is not None else settings.default_width
+    height = req.height if req.height is not None else settings.default_height
+
+    if width <= 0 or height <= 0:
+        raise ValidationError("width and height must be positive")
+    if width % _MULTIPLE or height % _MULTIPLE:
+        raise ValidationError(f"width and height must be multiples of {_MULTIPLE}")
+    if width > settings.max_width or height > settings.max_height:
+        raise ValidationError(
+            f"size {width}x{height} exceeds the cap {settings.max_width}x{settings.max_height}"
+        )
+
+    steps = (
+        req.steps if req.steps is not None else settings.default_steps.get(variant, 9)
+    )
+    if steps < 1 or steps > settings.max_steps:
+        raise ValidationError(f"steps must be in 1..{settings.max_steps}")
+    if req.quantize is not None and req.quantize not in (3, 4, 5, 6, 8):
+        raise ValidationError("quantize must be one of 3, 4, 5, 6, 8")
+    if len(req.loras) > settings.max_loras:
+        raise ValidationError(f"at most {settings.max_loras} loras may be applied")