kiapi 0.1.0__py3-none-any.whl

kiapi/capabilities/seedvr2/README.ja.md

@@ -0,0 +1,234 @@
+# seedvr2
+
+[English](README.md) | **日本語**
+
+[mflux SeedVR2](https://github.com/filipstrand/mflux/blob/main/src/mflux/models/seedvr2/README.md) で、単一画像の拡散ベース超解像 / アップスケール機能を提供します。
+SeedVR2 はプロンプト駆動の画像生成ではなく、入力画像を元にディテールを再構成する image-to-image の超解像モデルです。
+
+- **upscale**:
+  - Files API にアップロード済みの画像を `image` FileRef で参照
+  - 最短辺の目標ピクセル数、または `"2x"` のような倍率で出力サイズを指定
+
+
+## API
+
+| Endpoint | Name | Description |
+|---|---|---|
+| `POST /v1/image/seedvr2/upscale` | 画像アップスケール | Files API の画像を超解像し、画像を 1 枚生成。 |
+| `GET /v1/image/seedvr2/models` | モデル一覧 | 利用可能なモデルの一覧を返す。 |
+| `GET /v1/image/seedvr2/openapi.json` | OpenAPI | 詳細な入出力仕様、制約、TIPS を返す。 |
+
+## API Docs
+
+- [OpenAPI JSON](https://kiarina.github.io/kiapi/v1/image/seedvr2/openapi.json)
+- [Swagger UI](https://kiarina.github.io/kiapi/v1/image/seedvr2/docs.html)
+- [ReDoc](https://kiarina.github.io/kiapi/v1/image/seedvr2/redoc.html)
+
+## Dependencies
+
+| Package | License | Description |
+|---|---|---|
+| [mflux](https://github.com/filipstrand/mflux) | MIT | SeedVR2 の MLX 実装を利用。 |
+
+## Models
+
+| Model | License | Terms | Size | Description |
+|---|---|---|---:|---|
+| [numz/SeedVR2_comfyUI](https://huggingface.co/numz/SeedVR2_comfyUI) | Apache-2.0 | 不要 | 7.3 GB | `3b`（デフォルト）。軽量 variant。既定は `resolution: "2x"`、`softness: 0.0`、`quantize: 8`。 |
+| [numz/SeedVR2_comfyUI](https://huggingface.co/numz/SeedVR2_comfyUI) | Apache-2.0 | 不要 | 17 GB | `7b`。高容量 variant。`3b` より重く、kiapi の登録値では重み約 `7.0 GiB`、実行時ヘッドルーム約 `4.0 GiB` を見込む。 |
+
+モデル重みは `KIAPI_SEEDVR2_MODEL_REPO` で差し替えできます。
+既定は `numz/SeedVR2_comfyUI` です。
+
+## Notes
+
+- **resolution**:
+  `resolution` は整数の最短辺ターゲット、または `"2x"` / `"1.5x"` のような倍率です。
+  整数の場合は既定で `16..2048`、倍率の場合は `> 0` かつ `4.0x` 以下です。
+- **softness**:
+  `softness` は `0..1`。既定は `0.0` です。入力画像のディテール再構成の柔らかさを調整します。
+- **seed**:
+  `seed` を省略するとリクエストごとにランダムな seed が割り当てられます。
+  再現性が必要な場合は明示してください。
+- **quantize override**:
+  `quantize` は `3` / `4` / `5` / `6` / `8` / `null`。通常は既定の `8` で常駐モデルを使います。
+  リクエストで既定値と異なる `quantize` を指定した場合は、一回限りの一時モデルとしてロード・実行・解放します。
+- **レスポンス形式**:
+  sync で 1 成果物を生成する場合、`Accept: application/json` を付けなければ生の画像バイト列を返します。
+  `X-Kiapi-File-Id` と `X-Kiapi-Job-Id` ヘッダから保存済み成果物と Job を参照できます。
+  Job JSON が欲しい場合、または async の場合は `Accept: application/json` を使います。
+- **出力形式**:
+  `format` は `png`（既定）/ `jpeg` / `webp`。`jpeg` / `webp` では `quality`
+  `1..100`（既定 `90`）を使います。
+- **メモリ目安**:
+  `3b` は重み約 `2.7 GiB`、実行時ヘッドルーム約 `1.5 GiB`、`7b` は重み約
+  `7.0 GiB`、実行時ヘッドルーム約 `4.0 GiB` として登録されています。
+- **未対応**:
+  テキストプロンプト、画像編集指示、LoRA 学習、複数画像入力は公開していません。
+
+## Quickstart
+
+### upscale - 画像をアップロード
+
+先にソース画像を Files API にアップロードします。
+
+```bash
+IMG=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@source.png" | jq -r .file_id)
+```
+
+### upscale - 倍率で指定
+
+画像だけを保存する:
+
+```bash
+PARAMS=$(
+jq -n \
+--arg image "$IMG" \
+'{
+  model: "3b",
+  mode: "sync",
+  image: {type: "file_id", file_id: $image},
+  resolution: "2x",
+  softness: 0.0,
+  seed: 42
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/seedvr2/upscale \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o seedvr2-2x.png
+```
+
+Job JSON を返す:
+
+```bash
+PARAMS=$(
+jq -n \
+--arg image "$IMG" \
+'{
+  model: "3b",
+  mode: "sync",
+  image: {type: "file_id", file_id: $image},
+  resolution: "2x",
+  format: "webp",
+  quality: 92,
+  seed: 7
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/seedvr2/upscale \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" |
+jq .
+```
+
+### upscale - 最短辺ピクセル数で指定
+
+最短辺を `768px` に合わせてアップスケールします。
+
+```bash
+PARAMS=$(
+jq -n \
+--arg image "$IMG" \
+'{
+  mode: "sync",
+  image: {type: "file_id", file_id: $image},
+  resolution: 768,
+  softness: 0.15,
+  seed: 11
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/seedvr2/upscale \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o seedvr2-768.png
+```
+
+`resolution` に `"768"` のような文字列を渡した場合も整数ターゲットとして解釈されます。
+
+### 7b variant
+
+```bash
+PARAMS=$(
+jq -n \
+--arg image "$IMG" \
+'{
+  model: "7b",
+  mode: "sync",
+  image: {type: "file_id", file_id: $image},
+  resolution: "2x",
+  seed: 13
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/seedvr2/upscale \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o seedvr2-7b.png
+```
+
+### async
+
+```bash
+PARAMS=$(
+jq -n \
+--arg image "$IMG" \
+'{
+  mode: "async",
+  image: {type: "file_id", file_id: $image},
+  resolution: "2x",
+  seed: 17
+}'
+)
+
+JOB=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/seedvr2/upscale \
+-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 seedvr2-async.png
+```
+
+### quantize override
+
+既定と異なる量子化で試す場合は `quantize` を明示します。この呼び出しは常駐モデルを
+再利用せず、一時モデルを構築します。
+
+```bash
+PARAMS=$(
+jq -n \
+--arg image "$IMG" \
+'{
+  model: "3b",
+  mode: "sync",
+  image: {type: "file_id", file_id: $image},
+  resolution: "1.5x",
+  quantize: 6,
+  seed: 19
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/seedvr2/upscale \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o seedvr2-q6.png
+```
+
+### モデル一覧とヘルプ
+
+```bash
+curl -sS http://localhost:${PORT:-8000}/v1/image/seedvr2/models | jq .
+curl -sS http://localhost:${PORT:-8000}/v1/image/seedvr2/openapi.json | jq .
+```

kiapi/capabilities/seedvr2/README.md

@@ -0,0 +1,219 @@
+# seedvr2
+
+**English** | [日本語](README.ja.md)
+
+[mflux SeedVR2](https://github.com/filipstrand/mflux/blob/main/src/mflux/models/seedvr2/README.md) provides single-image diffusion-based super-resolution/upscaling functionality.
+SeedVR2 is an image-to-image super-resolution model that reconstructs details based on input images rather than prompt-driven image generation.
+
+- **upscale**:
+  - Reference images already uploaded to Files API with `image` FileRef
+  - Specify the output size by the target number of pixels on the shortest side or by a scaling factor like `"2x"`
+
+
+## API
+
+| Endpoint | Name | Description |
+|---|---|---|
+| `POST /v1/image/seedvr2/upscale` | Image upscaling | Super-resolve the Files API image and generate one image. |
+| `GET /v1/image/seedvr2/models` | Model list | Returns a list of available models. |
+| `GET /v1/image/seedvr2/openapi.json` | OpenAPI | Return detailed input/output specifications, constraints, and TIPS. |
+
+## API Docs
+
+- [OpenAPI JSON](https://kiarina.github.io/kiapi/v1/image/seedvr2/openapi.json)
+- [Swagger UI](https://kiarina.github.io/kiapi/v1/image/seedvr2/docs.html)
+- [ReDoc](https://kiarina.github.io/kiapi/v1/image/seedvr2/redoc.html)
+
+## Dependencies
+
+| Package | License | Description |
+|---|---|---|
+| [mflux](https://github.com/filipstrand/mflux) | MIT | Uses SeedVR2's MLX implementation. |
+
+## Models
+
+| Model | License | Terms | Size | Description |
+|---|---|---|---:|---|
+| [numz/SeedVR2_comfyUI](https://huggingface.co/numz/SeedVR2_comfyUI) | Apache-2.0 | Not required | 7.3 GB | `3b` (default). Lightweight variant. Defaults are `resolution: "2x"`, `softness: 0.0`, `quantize: 8`. |
+| [numz/SeedVR2_comfyUI](https://huggingface.co/numz/SeedVR2_comfyUI) | Apache-2.0 | Not required | 17 GB | `7b`. High capacity variant. It is heavier than `3b`, and the registered value of kiapi is expected to have a weight of about `7.0 GiB` and a runtime headroom of about `4.0 GiB`. |
+
+Model weights can be replaced with `KIAPI_SEEDVR2_MODEL_REPO`.
+Default is `numz/SeedVR2_comfyUI`.
+
+## Notes
+
+- **resolution**:
+  `resolution` is an integer shortest edge target or a scaling factor such as `"2x"` / `"1.5x"`.
+  The default is `16..2048` for integers, and `> 0` and less than or equal to `4.0x` for scale factors.
+- **softness**:
+  `softness` is `0..1`. Default is `0.0`. Adjusts the softness of detail reconstruction of the input image.
+- **seed**:
+  If `seed` is omitted, a random seed will be assigned for each request.
+  Please specify if reproducibility is required.
+- **quantize override**:
+  `quantize` is `3` / `4` / `5` / `6` / `8` / `null`. Normally, the default `8` uses the resident model.
+  If you specify `quantize` that is different from the default value in the request, it will be loaded, executed, and released as a one-time temporary model.
+- **Response format**:
+  If you generate one artifact with sync, it will return the raw image bytes unless you specify `Accept: application/json`.
+  You can reference saved artifacts and Jobs from the `X-Kiapi-File-Id` and `X-Kiapi-Job-Id` headers.
+  If you want Job JSON or async, use `Accept: application/json`.
+- **Output format**:
+  `format` is `png` (default) / `jpeg` / `webp`. `quality` for `jpeg` / `webp`
+  Use `1..100` (default `90`).
+- **Memory guideline**:
+  `3b` is the weight approximately `2.7 GiB`, runtime headroom is approximately `1.5 GiB`, `7b` is the weight approximately
+  Registered as `7.0 GiB`, runtime headroom approximately `4.0 GiB`.
+- **Not supported**:
+  We do not publish text prompts, image editing instructions, LoRA learning, or multiple image input.
+
+## Quickstart
+
+### upscale - Upload image
+
+First, upload the source image to the Files API.
+```bash
+IMG=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@source.png" | jq -r .file_id)
+```
+### upscale - Specify by scale factor
+
+Save only the image:
+```bash
+PARAMS=$(
+jq -n \
+--arg image "$IMG" \
+'{
+  model: "3b",
+  mode: "sync",
+  image: {type: "file_id", file_id: $image},
+  resolution: "2x",
+  softness: 0.0,
+  seed: 42
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/seedvr2/upscale \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o seedvr2-2x.png
+```
+Returns Job JSON:
+```bash
+PARAMS=$(
+jq -n \
+--arg image "$IMG" \
+'{
+  model: "3b",
+  mode: "sync",
+  image: {type: "file_id", file_id: $image},
+  resolution: "2x",
+  format: "webp",
+  quality: 92,
+  seed: 7
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/seedvr2/upscale \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" |
+jq .
+```
+### upscale - Specified by the number of pixels on the shortest side
+
+Upscale the shortest side to `768px`.
+```bash
+PARAMS=$(
+jq -n \
+--arg image "$IMG" \
+'{
+  mode: "sync",
+  image: {type: "file_id", file_id: $image},
+  resolution: 768,
+  softness: 0.15,
+  seed: 11
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/seedvr2/upscale \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o seedvr2-768.png
+```
+Passing a string like `"768" to `resolution` will also be interpreted as an integer target.
+
+### 7b variant
+```bash
+PARAMS=$(
+jq -n \
+--arg image "$IMG" \
+'{
+  model: "7b",
+  mode: "sync",
+  image: {type: "file_id", file_id: $image},
+  resolution: "2x",
+  seed: 13
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/seedvr2/upscale \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o seedvr2-7b.png
+```
+
+### async
+
+```bash
+PARAMS=$(
+jq -n \
+--arg image "$IMG" \
+'{
+  mode: "async",
+  image: {type: "file_id", file_id: $image},
+  resolution: "2x",
+  seed: 17
+}'
+)
+
+JOB=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/seedvr2/upscale \
+-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 seedvr2-async.png
+```
+### quantize override
+
+Specify `quantize` if you want to try a different quantization than the default. This call calls the resident model
+Build a temporary model without reusing it.
+```bash
+PARAMS=$(
+jq -n \
+--arg image "$IMG" \
+'{
+  model: "3b",
+  mode: "sync",
+  image: {type: "file_id", file_id: $image},
+  resolution: "1.5x",
+  quantize: 6,
+  seed: 19
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/seedvr2/upscale \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o seedvr2-q6.png
+```
+### Model list and help
+```bash
+curl -sS http://localhost:${PORT:-8000}/v1/image/seedvr2/models | jq .
+curl -sS http://localhost:${PORT:-8000}/v1/image/seedvr2/openapi.json | jq .
+```

kiapi/capabilities/seedvr2/__init__.py

@@ -0,0 +1,24 @@
+"""seedvr2 family — diffusion super-resolution / upscale via mflux.
+
+Endpoint: ``POST /v1/image/seedvr2/upscale``. SeedVR2 is not a prompt-driven
+image generator; it takes an input image from the Files API and produces an
+upscaled image. Variants are ``3b`` (default) and ``7b``. A ``quantize`` override
+runs a one-off transient model; otherwise the resident model is used.
+"""
+
+from kiapi.capabilities import ValidationError
+
+from ._helpers.register import register
+from ._helpers.validate_upscale import validate_upscale
+from ._operations.handle_upscale import handle_upscale
+from ._settings import settings_manager
+from ._views.upscale_request import UpscaleRequest
+
+__all__ = [
+    "UpscaleRequest",  # ._views
+    "ValidationError",  # kiapi.capabilities
+    "handle_upscale",  # ._operations
+    "register",  # ._helpers
+    "settings_manager",  # ._settings
+    "validate_upscale",  # ._helpers
+]

kiapi/capabilities/seedvr2/_constants/description.py

@@ -0,0 +1,46 @@
+DESCRIPTION = """Image super-resolution upscaling (SeedVR2 via mflux).
+
+One operation: `/upscale` takes an input image and produces a higher-resolution
+version. SeedVR2 is diffusion-based super-resolution, **not** prompt-driven image
+generation — there is no prompt. To create or edit images from text, use the
+qwen / flux2 / zimage / ideogram4 families instead.
+
+## Upstream docs
+- [mflux — SeedVR2](https://github.com/filipstrand/mflux/blob/main/src/mflux/models/seedvr2/README.md) — the MLX engine kiapi runs
+- [numz/SeedVR2_comfyUI](https://huggingface.co/numz/SeedVR2_comfyUI) — weights
+
+## Models
+- **3b** (default) — faster, lighter; good general upscaler.
+- **7b** — larger variant, higher quality at a higher memory/time cost.
+
+Discover variants at `GET /v1/image/seedvr2/models`. An omitted `quantize` uses
+the resident model's quantization (q8); the resolved values are recorded in the
+result `params`.
+
+## Sizing the output
+`resolution` accepts either form:
+- an **integer** shortest-edge pixel target (16..2048), or
+- a **scale factor** string like `2x` or `1.5x` (> 0 and at most 4.0x).
+
+`softness` (0..1) trades sharpness for smoothing; leave it at 0 for the crispest
+result.
+
+## Resident vs transient runs
+The warmed, resident model uses the server-default quantization (q8). A request
+that 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, leave `quantize` unset.
+
+## TIPS
+- For a quick result, call `sync` without `Accept: application/json` to get the
+  raw bytes straight back (`curl -o out.png`).
+- Upscaling a large source image to a high `resolution` raises peak memory; the
+  request can 503 if it does not fit the global memory budget — try the `3b`
+  variant or a smaller target.
+- First use downloads the SeedVR2 weights; run `kiapi activate` ahead of time to
+  avoid a cold-start download on the first request.
+
+## Performance
+- **3b**: 256→512 q8 first-run peak ~3929 MiB; cached 256→768 peak ~1756 MiB.
+- **7b**: larger variant; estimate only until measured locally.
+"""

kiapi/capabilities/seedvr2/_helpers/register.py

@@ -0,0 +1,60 @@
+"""Register seedvr2'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 seedvr2
+from .._settings import settings_manager
+
+
+def register() -> None:
+    capability_spec_registry.register(
+        CapabilitySpec(
+            name="seedvr2",
+            domain="image",
+            title="kiapi SeedVR2 API",
+            summary="Upscale and restore images with SeedVR2.",
+            description=DESCRIPTION,
+            openapi_path="/v1/image/seedvr2/openapi.json",
+            docs_path="/v1/image/seedvr2/docs",
+            redoc_path="/v1/image/seedvr2/redoc",
+            path_prefixes=("/v1/image/seedvr2",),
+        )
+    )
+
+    _s = settings_manager.get_settings()
+
+    model_registry.register(
+        ModelSpec(
+            name="3b",
+            family="seedvr2",
+            domain="image",
+            repo=f"{_s.model_repo}#3b",
+            module=seedvr2,
+            weight_gb=2.7,
+            peak_headroom_gb=1.5,
+            framework="mlx",
+            priority=0,
+            aliases=("seedvr2-3b", "seedvr2"),
+            default=True,
+            setup_resources=(HfSnapshotResource(repo=_s.model_repo, disk_gb=7.3),),
+        )
+    )
+
+    model_registry.register(
+        ModelSpec(
+            name="7b",
+            family="seedvr2",
+            domain="image",
+            repo=f"{_s.model_repo}#7b",
+            module=seedvr2,
+            weight_gb=7.0,
+            peak_headroom_gb=4.0,
+            framework="mlx",
+            priority=0,
+            aliases=("seedvr2-7b", "seedvr2-7B"),
+            setup_resources=(HfSnapshotResource(repo=_s.model_repo, disk_gb=17.0),),
+        )
+    )

kiapi/capabilities/seedvr2/_helpers/validate_upscale.py

@@ -0,0 +1,52 @@
+from kiapi.capabilities import ValidationError
+
+from .._settings import settings_manager
+from .._views.upscale_request import UpscaleRequest
+
+
+def _parse_scale(value: str) -> float | None:
+    if not value.endswith("x"):
+        return None
+    raw = value[:-1]
+    try:
+        return float(raw)
+    except ValueError:
+        raise ValidationError("resolution scale must look like '2x' or '1.5x'")  # noqa: B904
+
+
+def validate_upscale(req: UpscaleRequest) -> None:
+    settings = settings_manager.get_settings()
+    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 not 0.0 <= req.softness <= 1.0:
+        raise ValidationError("softness must be in 0..1")
+
+    resolution = req.resolution
+    if isinstance(resolution, int):
+        if resolution < settings.min_resolution or resolution > settings.max_resolution:
+            raise ValidationError(
+                f"resolution must be in {settings.min_resolution}..{settings.max_resolution}"
+            )
+        return
+
+    if not isinstance(resolution, str):
+        raise ValidationError(
+            "resolution must be an integer shortest-edge target or a scale like '2x'"
+        )
+    if resolution.endswith("x"):
+        scale = _parse_scale(resolution)
+        if scale is None or scale <= 0 or scale > settings.max_scale:
+            raise ValidationError(
+                f"resolution scale must be > 0 and <= {settings.max_scale}x"
+            )
+        return
+    try:
+        pixels = int(resolution)
+    except ValueError:
+        raise ValidationError(  # noqa: B904
+            "resolution must be an integer shortest-edge target or a scale like '2x'"
+        )
+    if pixels < settings.min_resolution or pixels > settings.max_resolution:
+        raise ValidationError(
+            f"resolution must be in {settings.min_resolution}..{settings.max_resolution}"
+        )