kiapi 0.1.0__py3-none-any.whl

kiapi/capabilities/ernie/README.ja.md

@@ -0,0 +1,242 @@
+# ernie
+
+[English](README.md) | **日本語**
+
+[mflux ERNIE-Image](https://github.com/filipstrand/mflux/blob/main/src/mflux/models/ernie_image/README.md) で、画像生成・画像編集・LoRA ファインチューニング機能を提供します。
+
+- **generate**: テキストから画像を生成
+- **edit**: Files API の単一画像をプロンプトで編集
+- **train**: キャプション付き画像 ZIP から LoRA アダプタを学習
+
+## API
+
+| Endpoint | Name | Description |
+|---|---|---|
+| `POST /v1/image/ernie/generate` | 画像生成 | プロンプトから画像を生成。 |
+| `POST /v1/image/ernie/edit` | 画像編集 | Files API の単一画像をプロンプトで img2img 編集。 |
+| `POST /v1/image/ernie/train` | LoRA 学習 | キャプション付き画像 ZIP から LoRA アダプタを学習。常に async。 |
+| `GET /v1/image/ernie/models` | モデル一覧 | 利用可能なモデルの一覧を返す。 |
+| `GET /v1/image/ernie/openapi.json` | OpenAPI | 詳細な入出力仕様、使い方、TIPS を返す。 |
+
+## API Docs
+
+- [OpenAPI JSON](https://kiarina.github.io/kiapi/v1/image/ernie/openapi.json)
+- [Swagger UI](https://kiarina.github.io/kiapi/v1/image/ernie/docs.html)
+- [ReDoc](https://kiarina.github.io/kiapi/v1/image/ernie/redoc.html)
+
+## Dependencies
+
+| Package | License | Description |
+|---|---|---|
+| [mflux](https://github.com/filipstrand/mflux) | MIT | ERNIE-Image の MLX 実装と LoRA 学習機能を利用。 |
+
+## Models
+
+| Model | License | Terms | Size | Description |
+|---|---|---|---:|---|
+| [baidu/ERNIE-Image-Turbo](https://huggingface.co/baidu/ERNIE-Image-Turbo) | Apache-2.0 | 不要 | 31.6 GB | `turbo`（デフォルト）。蒸留 8 ステップモデル。既定は `steps: 8`、`guidance: 1.0`、`quantize: 8`。 |
+| [baidu/ERNIE-Image](https://huggingface.co/baidu/ERNIE-Image) | Apache-2.0 | 不要 | 31.6 GB | `base`。非 distilled のモデル。既定は `steps: 50`、`guidance: 4.0`、`quantize: 8`。 |
+
+## Notes
+
+- **画像サイズ**:
+  `width` / `height` は 16 の倍数で、既定は `1024x1024`、上限は `2048x2048` です。
+- **edit の正方形ガード**:
+  `mflux==0.18.0` では ERNIE img2img の一部の非正方形サイズが latent packing で
+  失敗することがあります。kiapi はデフォルトで `edit` の `width == height` を要求します。
+  無効にするには `KIAPI_ERNIE_EDIT_REQUIRE_SQUARE=0` を設定します。
+- **steps / quantize**:
+  `steps` は `1..100`。`quantize` は `3` / `4` / `5` / `6` / `8` / `null` を使います。
+  `quantize` を省略するとモデルごとの既定値を使います。
+- **LoRA 適用**:
+  `generate` / `edit` の `loras` には `[{ "file_id": "...", "scale": 1.0 }]` を渡します。
+  既定では最大 4 個まで適用できます。
+- **LoRA 学習データセット**:
+  ZIP のトップレベル、または ZIP 内の単一サブフォルダに画像を置きます。画像ごとに
+  同じ語幹の `.txt` キャプションが必要です。`preview*` で始まる画像はキャプション
+  必須チェックから除外されます。
+
+## Quickstart
+
+### generate - テキストから画像生成
+
+Job JSON を返す:
+
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "A quiet Japanese garden after rain, soft morning light, detailed watercolor" \
+'{
+  model: "turbo",
+  mode: "sync",
+  prompt: $prompt,
+  width: 1024,
+  height: 1024,
+  steps: 8,
+  seed: 404
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/ernie/generate \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" | jq .
+```
+
+画像だけを保存する:
+
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "A barn owl portrait on a mossy branch, natural wildlife photography" \
+'{
+  model: "turbo",
+  mode: "sync",
+  prompt: $prompt,
+  width: 512,
+  height: 512,
+  steps: 8,
+  seed: 404
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/ernie/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o ernie.png
+```
+
+### edit - 単一画像を編集
+
+先に入力画像をアップロードする:
+
+```bash
+IMG=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@tests/assets/miineko.png;type=image/png" | jq -r .file_id)
+```
+
+アップロードした画像を編集する:
+
+```bash
+PARAMS=$(
+jq -n \
+--arg image "$IMG" \
+--arg prompt "Turn this image into a soft watercolor illustration" \
+'{
+  model: "turbo",
+  mode: "sync",
+  prompt: $prompt,
+  image: {type: "file_id", file_id: $image},
+  image_strength: 0.55,
+  width: 512,
+  height: 512,
+  steps: 8,
+  seed: 42
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/ernie/edit \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o ernie_edit.png
+```
+
+`image_strength` は `0..1`。小さいほど元画像を強く残し、大きいほどプロンプト側の
+変化が強くなります。
+
+### async
+
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "A small robot reading a book in a cozy library" \
+'{
+  model: "turbo",
+  mode: "async",
+  prompt: $prompt,
+  width: 512,
+  height: 512,
+  seed: 7
+}'
+)
+
+JOB=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/ernie/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 ernie_async.png
+```
+
+### train - LoRA ファインチューニング
+
+画像と同じ語幹の `.txt` キャプションを含む ZIP データセットを用意します。
+
+```text
+dataset/
+  sample_00.png
+  sample_00.txt
+  sample_01.png
+  sample_01.txt
+```
+
+データセットをアップロードして学習を開始します。
+
+```bash
+DATASET_ID=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@dataset.zip;type=application/zip" | jq -r .file_id)
+
+JOB=$(
+jq -n \
+--arg dataset "$DATASET_ID" \
+'{
+  model: "turbo",
+  dataset: {type: "file_id", file_id: $dataset},
+  num_epochs: 1,
+  lora_rank: 16,
+  max_resolution: 512
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/ernie/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 adapter "$ADAPTER" \
+--arg prompt "portrait in the trained character style" \
+'{
+  model: "turbo",
+  mode: "sync",
+  prompt: $prompt,
+  width: 512,
+  height: 512,
+  loras: [{file: {type: "file_id", file_id: $adapter}, scale: 1.0}]
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/ernie/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o ernie_lora.png
+```

kiapi/capabilities/ernie/README.md

@@ -0,0 +1,223 @@
+# ernie
+
+**English** | [日本語](README.ja.md)
+
+[mflux ERNIE-Image](https://github.com/filipstrand/mflux/blob/main/src/mflux/models/ernie_image/README.md) provides image generation, image editing, and LoRA fine tuning functions.
+
+- **generate**: Generate image from text
+- **edit**: Prompt editing of single image in Files API
+- **train**: Train LoRA adapter from captioned image ZIP
+
+## API
+
+| Endpoint | Name | Description |
+|---|---|---|
+| `POST /v1/image/ernie/generate` | Image generation | Generate image from prompt. |
+| `POST /v1/image/ernie/edit` | Image editing | Files API single image prompt img2img editing. |
+| `POST /v1/image/ernie/train` | LoRA learning | Learning LoRA adapter from captioned image ZIP. Always async. |
+| `GET /v1/image/ernie/models` | Model list | Returns a list of available models. |
+| `GET /v1/image/ernie/openapi.json` | OpenAPI | Returns detailed input/output specifications, usage, and TIPS. |
+
+## API Docs
+
+- [OpenAPI JSON](https://kiarina.github.io/kiapi/v1/image/ernie/openapi.json)
+- [Swagger UI](https://kiarina.github.io/kiapi/v1/image/ernie/docs.html)
+- [ReDoc](https://kiarina.github.io/kiapi/v1/image/ernie/redoc.html)
+
+## Dependencies
+
+| Package | License | Description |
+|---|---|---|
+| [mflux](https://github.com/filipstrand/mflux) | MIT | Uses ERNIE-Image's MLX implementation and LoRA learning function. |
+
+## Models
+
+| Model | License | Terms | Size | Description |
+|---|---|---|---:|---|
+| [baidu/ERNIE-Image-Turbo](https://huggingface.co/baidu/ERNIE-Image-Turbo) | Apache-2.0 | Not required | 31.6 GB | `turbo` (default). Distillation 8 step model. Defaults are `steps: 8`, `guidance: 1.0`, `quantize: 8`. |
+| [baidu/ERNIE-Image](https://huggingface.co/baidu/ERNIE-Image) | Apache-2.0 | Not required | 31.6 GB | `base`. Non-distilled model. Defaults are `steps: 50`, `guidance: 4.0`, `quantize: 8`. |
+
+## Notes
+
+- **Image size**:
+  `width` / `height` are multiples of 16, default is `1024x1024`, upper limit is `2048x2048`.
+- **edit square guard**:
+  With `mflux==0.18.0`, some non-square sizes of ERNIE img2img are latent packing.
+  It may fail. kiapi requires `width == height` for `edit` by default.
+  To disable it, set `KIAPI_ERNIE_EDIT_REQUIRE_SQUARE=0`.
+- **steps/quantize**:
+  `steps` is `1..100`. `quantize` uses `3` / `4` / `5` / `6` / `8` / `null`.
+  If `quantize` is omitted, the default value for each model will be used.
+- **LoRA applied**:
+  Pass `[{ "file_id": "...", "scale": 1.0 }]` to `loras` of `generate` / `edit`.
+  By default, up to 4 can be applied.
+- **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. Images starting with `preview*` are captions.
+  Excluded from mandatory checks.
+
+## Quickstart
+
+### generate - generate image from text
+
+Returns Job JSON:
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "A quiet Japanese garden after rain, soft morning light, detailed watercolor" \
+'{
+  model: "turbo",
+  mode: "sync",
+  prompt: $prompt,
+  width: 1024,
+  height: 1024,
+  steps: 8,
+  seed: 404
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/ernie/generate \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" | jq .
+```
+Save only the image:
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "A barn owl portrait on a mossy branch, natural wildlife photography" \
+'{
+  model: "turbo",
+  mode: "sync",
+  prompt: $prompt,
+  width: 512,
+  height: 512,
+  steps: 8,
+  seed: 404
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/ernie/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o ernie.png
+```
+### edit - edit a single image
+
+Upload the input image first:
+```bash
+IMG=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@tests/assets/miineko.png;type=image/png" | jq -r .file_id)
+```
+Edit the uploaded image:
+```bash
+PARAMS=$(
+jq -n \
+--arg image "$IMG" \
+--arg prompt "Turn this image into a soft watercolor illustration" \
+'{
+  model: "turbo",
+  mode: "sync",
+  prompt: $prompt,
+  image: {type: "file_id", file_id: $image},
+  image_strength: 0.55,
+  width: 512,
+  height: 512,
+  steps: 8,
+  seed: 42
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/ernie/edit \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o ernie_edit.png
+```
+`image_strength` is `0..1`. The smaller the value, the stronger the original image will remain; the larger the value, the more the prompt side will remain.
+The changes will become stronger.
+
+###async
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "A small robot reading a book in a cozy library" \
+'{
+  model: "turbo",
+  mode: "async",
+  prompt: $prompt,
+  width: 512,
+  height: 512,
+  seed: 7
+}'
+)
+
+JOB=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/ernie/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 ernie_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
+```
+Upload your dataset and start training.
+```bash
+DATASET_ID=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@dataset.zip;type=application/zip" | jq -r .file_id)
+
+JOB=$(
+jq -n \
+--arg dataset "$DATASET_ID" \
+'{
+  model: "turbo",
+  dataset: {type: "file_id", file_id: $dataset},
+  num_epochs: 1,
+  lora_rank: 16,
+  max_resolution: 512
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/ernie/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 during generation and editing.
+```bash
+PARAMS=$(
+jq -n \
+--arg adapter "$ADAPTER" \
+--arg prompt "portrait in the trained character style" \
+'{
+  model: "turbo",
+  mode: "sync",
+  prompt: $prompt,
+  width: 512,
+  height: 512,
+  loras: [{file: {type: "file_id", file_id: $adapter}, scale: 1.0}]
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/ernie/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o ernie_lora.png
+```

kiapi/capabilities/ernie/__init__.py

@@ -0,0 +1,34 @@
+"""ernie family — ERNIE-Image generation/edit/LoRA-training via mflux.
+
+Endpoints: ``POST /v1/image/ernie/{generate,edit,train}``. ``generate`` is
+text-to-image, ``edit`` is single-image img2img, and ``train`` LoRA-finetunes on
+captioned images (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/ernie/_constants/description.py

@@ -0,0 +1,71 @@
+DESCRIPTION = """Image generation, editing, and LoRA training (ERNIE-Image via mflux).
+
+Three operations on Baidu's ERNIE-Image models: `/generate` (text-to-image),
+`/edit` (single-image image-to-image), and `/train` (LoRA finetune).
+
+## Upstream docs
+- [mflux — ERNIE-Image](https://github.com/filipstrand/mflux/blob/main/src/mflux/models/ernie_image/README.md) — the MLX engine kiapi runs
+- [baidu/ERNIE-Image-Turbo](https://huggingface.co/baidu/ERNIE-Image-Turbo) — `turbo` weights
+- [baidu/ERNIE-Image](https://huggingface.co/baidu/ERNIE-Image) — `base` weights
+
+## Models
+- **turbo** (default) — `baidu/ERNIE-Image-Turbo`. Fast, few steps (default 8),
+  guidance 1.0. The everyday choice.
+- **base** — `baidu/ERNIE-Image`. Higher quality but slower: more steps
+  (default 50) and stronger guidance (default 4.0).
+
+Pick the variant with `model` (aliases like `ernie-image-turbo` are accepted);
+discover variants at `GET /v1/image/ernie/models`. Variant-dependent defaults
+(`steps` / `guidance` / `quantize`) are filled in server-side when omitted, and
+the resolved values are recorded in the result `params`.
+
+## 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 from a captioned image set via `/train` (always async), then
+apply it on `/generate` or `/edit` 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. `edit`
+  additionally requires square sizes by default — set
+  `KIAPI_ERNIE_EDIT_REQUIRE_SQUARE=0` to lift the guard (mflux 0.18.0 can fail on
+  some non-square ERNIE img2img sizes).
+- First use downloads the ERNIE-Image weights; run `kiapi activate` ahead of time
+  to avoid a cold-start download on the first request.
+
+## Performance
+- **turbo**: q8 512x512 generation around 15s after cache load, peak RSS ~5-6 GiB.
+- **base**: slower and uses more steps; prefer turbo unless you need its quality.
+- Transient runs (any `loras` or a `quantize` override) rebuild the model each
+  call and are slower than the resident path.
+"""

kiapi/capabilities/ernie/_helpers/register.py

@@ -0,0 +1,60 @@
+"""Register ernie'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 ernie
+from .._settings import settings_manager
+
+
+def register() -> None:
+    capability_spec_registry.register(
+        CapabilitySpec(
+            name="ernie",
+            domain="image",
+            title="kiapi ERNIE-Image API",
+            summary="Generate, edit, and train LoRA adapters for ERNIE-Image models.",
+            description=DESCRIPTION,
+            openapi_path="/v1/image/ernie/openapi.json",
+            docs_path="/v1/image/ernie/docs",
+            redoc_path="/v1/image/ernie/redoc",
+            path_prefixes=("/v1/image/ernie",),
+        )
+    )
+
+    _s = settings_manager.get_settings()
+
+    model_registry.register(
+        ModelSpec(
+            name="turbo",
+            family="ernie",
+            domain="image",
+            repo=_s.turbo_model,
+            module=ernie,
+            weight_gb=6.0,
+            peak_headroom_gb=4.0,
+            framework="mlx",
+            priority=0,
+            aliases=("ernie-image-turbo", "baidu/ERNIE-Image-Turbo"),
+            default=True,
+            setup_resources=(HfSnapshotResource(repo=_s.turbo_model, disk_gb=31.6),),
+        )
+    )
+
+    model_registry.register(
+        ModelSpec(
+            name="base",
+            family="ernie",
+            domain="image",
+            repo=_s.base_model,
+            module=ernie,
+            weight_gb=12.0,
+            peak_headroom_gb=8.0,
+            framework="mlx",
+            priority=0,
+            aliases=("ernie-image", "baidu/ERNIE-Image"),
+            setup_resources=(HfSnapshotResource(repo=_s.base_model, disk_gb=31.6),),
+        )
+    )

kiapi/capabilities/ernie/_helpers/validate_edit.py

@@ -0,0 +1,19 @@
+from kiapi.capabilities import ValidationError
+
+from .._operations.validate_common import validate_common
+from .._settings import settings_manager
+from .._views.edit_request import EditRequest
+
+
+def validate_edit(req: EditRequest, *, variant: str) -> None:
+    settings = settings_manager.get_settings()
+    validate_common(req, settings, variant=variant)
+    if not 0 <= req.image_strength <= 1:
+        raise ValidationError("image_strength must be in 0..1")
+    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 settings.edit_require_square and width != height:
+        raise ValidationError(
+            "ERNIE edit currently requires square width/height; set "
+            "KIAPI_ERNIE_EDIT_REQUIRE_SQUARE=0 to disable this guard"
+        )

kiapi/capabilities/ernie/_helpers/validate_generate.py

@@ -0,0 +1,8 @@
+from .._operations.validate_common import validate_common
+from .._settings import settings_manager
+from .._views.generate_request import GenerateRequest
+
+
+def validate_generate(req: GenerateRequest, *, variant: str) -> None:
+    settings = settings_manager.get_settings()
+    validate_common(req, settings, variant=variant)