kiapi 0.1.0__py3-none-any.whl

kiapi/capabilities/ltx2/_settings.py

@@ -0,0 +1,93 @@
+"""LTX-2 capability defaults + caps, read from ``KIAPI_LTX2_`` env vars."""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic_settings_manager import SettingsManager
+
+
+class LTX2Settings(BaseSettings):
+    """Settings for LTX-2 models, video dimensions, frame counts, and progress display."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="KIAPI_LTX2_",
+        extra="ignore",
+        protected_namespaces=(),
+    )
+
+    model_repo: str = Field(
+        default="prince-canuma/LTX-2-distilled",
+        title="LTX-2 model repo",
+        description="Hugging Face repo ID for the LTX-2 model used for video generation.",
+    )
+
+    text_encoder_repo: str | None = Field(
+        default=None,
+        title="Text encoder repo",
+        description=(
+            "Hugging Face repo ID for a text encoder from a separate repo.\n"
+            "When None, the model's default text encoder is used."
+        ),
+    )
+
+    # --------------------------------------------------
+    # generate
+    # --------------------------------------------------
+
+    max_num_frames: int = Field(
+        default=721,
+        title="Maximum frame count",
+        description="Upper limit for the video frame count accepted in a request.",
+    )
+
+    max_width: int = Field(
+        default=768,
+        title="Maximum width",
+        description="Upper pixel limit for the video width accepted in a request.",
+    )
+
+    max_height: int = Field(
+        default=768,
+        title="Maximum height",
+        description="Upper pixel limit for the video height accepted in a request.",
+    )
+
+    default_width: int = Field(
+        default=512,
+        title="Default width",
+        description="Video width in pixels used when a request omits width.",
+    )
+
+    default_height: int = Field(
+        default=512,
+        title="Default height",
+        description="Video height in pixels used when a request omits height.",
+    )
+
+    default_num_frames: int = Field(
+        default=97,
+        title="Default frame count",
+        description="Generated frame count used when a request omits num_frames.",
+    )
+
+    default_fps: int = Field(
+        default=24,
+        title="Default FPS",
+        description="Output video FPS used when a request omits fps.",
+    )
+
+    # mlx-video exposes no per-step hook, so we creep a synthetic 'liveness'
+    # progress on a time-based schedule while it runs (keeps polling agents
+    # waiting); the schedule is paced to hit ~80% at this expected duration. Base
+    # seconds for a 97-frame 512x512 job; scaled by frame count and resolution.
+    # 0 disables the creep (progress stays at the coarse 0.0 until completion).
+    progress_eta_base_s: float = Field(
+        default=90.0,
+        title="Progress ETA base seconds",
+        description=(
+            "Expected seconds for synthetic progress, based on a 97-frame 512x512 LTX-2 job.\n"
+            "The value is scaled by frame count and resolution. Set to 0 to disable it."
+        ),
+    )
+
+
+settings_manager = SettingsManager(LTX2Settings)

kiapi/capabilities/ltx2/_views/generate_params.py

@@ -0,0 +1,34 @@
+"""Resolved LTX-2 generation parameters used by the model layer."""
+
+from pydantic import BaseModel, Field
+
+
+class GenerateParams(BaseModel):
+    model: str = Field(description="Resolved model variant used for the run.")
+
+    prompt: str = Field(description="Prompt used for the generation.")
+    seed: int = Field(description="Resolved seed; generated when request seed is null.")
+    width: int = Field(description="Resolved output width in pixels.")
+    height: int = Field(description="Resolved output height in pixels.")
+    num_frames: int = Field(description="Resolved output frame count.")
+    fps: int = Field(description="Resolved output frame rate.")
+    image_strength: float = Field(description="Resolved first-frame strength.")
+    end_image_strength: float | None = Field(
+        description="Resolved last-frame strength, or null when omitted."
+    )
+    generate_audio: bool = Field(
+        description="Whether LTX-2 should synthesize synchronized audio."
+    )
+
+    def gen_params(self) -> dict:
+        return {
+            "prompt": self.prompt,
+            "width": self.width,
+            "height": self.height,
+            "num_frames": self.num_frames,
+            "fps": self.fps,
+            "seed": self.seed,
+            "image_strength": self.image_strength,
+            "end_image_strength": self.end_image_strength,
+            "generate_audio": self.generate_audio,
+        }

kiapi/capabilities/ltx2/_views/generate_request.py

@@ -0,0 +1,151 @@
+"""LTX-2 video generation request model.
+
+Text/image/audio → MP4. One endpoint serves both sync and async via ``mode``.
+The generation mode (T2V, I2V, A2V, etc.) is inferred from which FileRef inputs
+are present, not from a user-supplied mode field.
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from kiapi.core.file import FileRef
+
+
+class GenerateRequest(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    model: str | None = Field(
+        default=None,
+        description=(
+            "Model variant (see GET /v1/video/ltx2/models). Omit for the "
+            "default `distilled`; this is currently the only public variant."
+        ),
+    )
+    mode: Literal["sync", "async"] = Field(
+        default="sync",
+        description=(
+            "`sync` waits for the MP4 (504 on timeout); `async` returns 202 with "
+            "a job_id immediately — poll GET /v1/jobs/{job_id}."
+        ),
+    )
+
+    prompt: str = Field(
+        ...,
+        min_length=1,
+        description=(
+            "Text description of the desired video. Distilled LTX-2 has no "
+            "negative guidance, so describe the motion, subject, framing, and "
+            "visual qualities you want rather than what to avoid."
+        ),
+        examples=["a cat walking through tall grass, sunny daylight, gentle camera"],
+    )
+    image: FileRef | None = Field(
+        default=None,
+        description=(
+            "Optional first-frame conditioning image (Files-API file id, http(s) "
+            "URL, or data URL). Present with no audio => I2V; present with audio "
+            "=> A2V+I2V."
+        ),
+    )
+    end_image: FileRef | None = Field(
+        default=None,
+        description=(
+            "Optional last-frame conditioning image. Use with `image` for a "
+            "first+last-frame transition, or alone for last-frame conditioning."
+        ),
+    )
+    audio: FileRef | None = Field(
+        default=None,
+        description=(
+            "Optional driving audio file (Files-API file id, http(s) URL, or data "
+            "URL). When present, the mode becomes A2V and the audio is muxed into "
+            "the output MP4. Mutually exclusive with `generate_audio=true`."
+        ),
+    )
+    width: int | None = Field(
+        default=None,
+        description=(
+            "Output width in pixels. Omit for server default 512. Must be a "
+            "positive multiple of 64 and no greater than the configured cap "
+            "(default 768)."
+        ),
+    )
+    height: int | None = Field(
+        default=None,
+        description=(
+            "Output height in pixels. Omit for server default 512. Must be a "
+            "positive multiple of 64 and no greater than the configured cap "
+            "(default 768)."
+        ),
+    )
+    num_frames: int | None = Field(
+        default=None,
+        description=(
+            "Number of output frames. Omit for server default 97. Must satisfy "
+            "`1 + 8*k` (for example 97, 161, 241, 481, 721) and stay within the "
+            "configured cap (default 721). Duration is `num_frames / fps`."
+        ),
+    )
+    fps: int | None = Field(
+        default=None,
+        description=(
+            "Output frame rate. Omit for server default 24. Must be positive; it "
+            "sets playback duration but does not materially reduce generation work."
+        ),
+    )
+    seed: int | None = Field(
+        default=None,
+        description=(
+            "Random seed for reproducibility. Omit for a random seed (the resolved "
+            "seed is recorded in the result `params`)."
+        ),
+    )
+    image_strength: float = Field(
+        default=1.0,
+        ge=0.0,
+        le=1.0,
+        description=(
+            "First-frame conditioning strength in 0..1. 1.0 adheres tightly to "
+            "the input frame; lower values such as ~0.7 allow larger motion or "
+            "composition changes."
+        ),
+    )
+    end_image_strength: float | None = Field(
+        default=None,
+        ge=0.0,
+        le=1.0,
+        description=(
+            "Last-frame conditioning strength in 0..1. Omit to let mlx-video use "
+            "its default behavior for the selected mode."
+        ),
+    )
+    generate_audio: bool = Field(
+        default=False,
+        description=(
+            "Ask LTX-2 to synthesize synchronized audio for the MP4. Mutually "
+            "exclusive with an `audio` FileRef."
+        ),
+    )
+
+    def gen_params(self) -> dict:
+        return {
+            "prompt": self.prompt,
+            "image": self.image.model_dump(mode="json")
+            if self.image is not None
+            else None,
+            "end_image": self.end_image.model_dump(mode="json")
+            if self.end_image is not None
+            else None,
+            "audio": self.audio.model_dump(mode="json")
+            if self.audio is not None
+            else None,
+            "width": self.width,
+            "height": self.height,
+            "num_frames": self.num_frames,
+            "fps": self.fps,
+            "seed": self.seed,
+            "image_strength": self.image_strength,
+            "end_image_strength": self.end_image_strength,
+            "generate_audio": self.generate_audio,
+        }

kiapi/capabilities/qwen/README.ja.md

@@ -0,0 +1,251 @@
+# qwen
+
+[English](README.md) | **日本語**
+
+[mflux Qwen Image](https://github.com/filipstrand/mflux/blob/main/src/mflux/models/qwen/README.md) で、画像生成・画像編集機能を提供します。
+Qwen Image は多言語プロンプトと画像内テキストに強いモデルです。
+
+- **generate**:
+  - テキストから画像を生成
+  - `init_image` FileRef を渡した場合は img2img
+- **edit**:
+  - Files API の 1 枚以上の参照画像を使う自然言語編集
+
+
+## API
+
+| Endpoint | Name | Description |
+|---|---|---|
+| `POST /v1/image/qwen/generate` | 画像生成 | プロンプトと参照画像から画像を生成。 |
+| `POST /v1/image/qwen/edit` | 画像編集 | 複数の参照画像から画像を生成。 |
+| `GET /v1/image/qwen/models` | モデル一覧 | 利用可能なモデルの一覧を返す。 |
+| `GET /v1/image/qwen/openapi.json` | OpenAPI | 詳細な入出力仕様、使い方、TIPS を返す。 |
+
+## API Docs
+
+- [OpenAPI JSON](https://kiarina.github.io/kiapi/v1/image/qwen/openapi.json)
+- [Swagger UI](https://kiarina.github.io/kiapi/v1/image/qwen/docs.html)
+- [ReDoc](https://kiarina.github.io/kiapi/v1/image/qwen/redoc.html)
+
+## Dependencies
+
+| Package | License | Description |
+|---|---|---|
+| [mflux](https://github.com/filipstrand/mflux) | MIT | Qwen Image / Qwen Image Edit を MLX 上で実行。 |
+
+## Models
+
+| Model | License | Terms | Size | Description |
+|---|---|---|---:|---|
+| [Qwen/Qwen-Image](https://huggingface.co/Qwen/Qwen-Image) | Apache-2.0 | 不要 | 58 GB | `image`（デフォルト）。`generate` で使用。txt2img / img2img。既定は `steps: 30`、`guidance: 4.0`、`quantize: 8`。 |
+| [Qwen/Qwen-Image-Edit-2509](https://huggingface.co/Qwen/Qwen-Image-Edit-2509) | Apache-2.0 | 不要 | 58 GB | `edit-2509`。`edit` で使用。単一/複数参照画像の編集。既定は `steps: 30`、`guidance: 2.5`、`quantize: 8`。 |
+
+`POST /v1/image/qwen/generate` は `image` のみ、`POST /v1/image/qwen/edit` は
+`edit-2509` のみを受け付けます。エンドポイントごとのデフォルトは router 側で補われる
+ため、通常は `model` を省略できます。
+
+## Notes
+
+- **画像サイズ**:
+  `width` / `height` は 16 の倍数。既定は `1024 x 1024`、上限は `2048 x 2048`。
+- **steps / guidance**:
+  `steps` は `1..100`。省略時は generate/edit とも `30`。`guidance` は generate が
+  `4.0`、edit が `2.5`。
+- **quantize**:
+  既定は `8`。上書きする場合は `3` / `4` / `5` / `6` / `8` を指定できます。
+  省略、または `null` を渡すと既定値を使います。
+- **LoRA 適用**:
+  `loras: [{"file": {"type": "file_id", "file_id": "..."}, "scale": 1.0}]` でアダプタを適用します。最大 4 つまで。
+  アダプタファイルは Files API に保存されている必要があります。
+- **transient モデル**:
+  mflux は量子化レベルと LoRA をモデル構築時に固定するため、`loras` を持つ、または
+  `quantize` を既定値から上書きするリクエストは、その呼び出し用の一時モデルを構築します。
+  常駐モデルを再利用しないため、素の `image` / `edit-2509` 呼び出しより遅くなります。
+- **出力形式**:
+  `format` は `png`（既定）/ `jpeg` / `webp`。`jpeg` / `webp` では `quality`
+  `1..100`（既定 `90`）を使います。
+- **メモリ目安**:
+  `image` / `edit-2509` はどちらも大きなモデルです。kiapi の登録値では重み約
+  `22.0 GiB`、実行時ヘッドルーム約 `8.0 GiB` を見込んでいます。
+
+## Quickstart
+
+### generate - テキストから画像生成
+
+画像だけを保存する:
+
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "a cafe storefront, a wooden sign clearly reads カフェ, bright daylight" \
+--arg negative_prompt "blurry, low quality, distorted text" \
+'{
+  model: "image",
+  mode: "sync",
+  prompt: $prompt,
+  negative_prompt: $negative_prompt,
+  width: 512,
+  height: 512,
+  seed: 1
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/qwen/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o qwen.png
+```
+
+Job JSON を返す:
+
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "a clean product label design, the main text reads KIAPI, white background" \
+'{
+  mode: "sync",
+  prompt: $prompt,
+  width: 512,
+  height: 512,
+  seed: 2
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/qwen/generate \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" |
+jq .
+```
+
+### generate - img2img
+
+先にソース画像をアップロードします。
+
+```bash
+IMG=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@source.png" | jq -r .file_id)
+```
+
+アップロードした画像を元に生成します。
+
+```bash
+PARAMS=$(
+jq -n \
+--arg img "$IMG" \
+--arg prompt "turn this into a polished cozy illustration" \
+'{
+  model: "image",
+  mode: "sync",
+  prompt: $prompt,
+  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/qwen/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o qwen-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)
+
+PARAMS=$(
+jq -n \
+--arg ref1 "$REF1" \
+--arg ref2 "$REF2" \
+--arg prompt "combine the mascot and object into a bright product key visual; keep the mascot recognizable" \
+'{
+  model: "edit-2509",
+  mode: "sync",
+  prompt: $prompt,
+  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/qwen/edit \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o qwen-edit.png
+```
+
+`images` は 1 枚以上。単一画像の編集にも、複数参照画像を使った合成・再構成にも
+使えます。
+
+### async
+
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "a typography poster, large readable text says LOCAL AI" \
+'{
+  mode: "async",
+  prompt: $prompt,
+  width: 512,
+  height: 512,
+  seed: 11
+}'
+)
+
+JOB=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/qwen/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 qwen-async.png
+```
+
+### LoRA を適用して生成
+
+学習済みアダプタなどの `.safetensors` を Files API にアップロードし、`loras` で参照します。
+
+```bash
+ADAPTER=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@adapter.safetensors" | jq -r .file_id)
+
+PARAMS=$(
+jq -n \
+--arg adapter "$ADAPTER" \
+--arg prompt "<your trigger word> as a clean editorial illustration" \
+'{
+  model: "image",
+  mode: "sync",
+  prompt: $prompt,
+  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/qwen/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o qwen-lora.png
+```
+
+`scale` は効きの強さです。`loras` を使うリクエストは毎回一時モデルを構築します。