kiapi 0.1.0__py3-none-any.whl

kiapi/capabilities/ltx2/README.md

@@ -0,0 +1,274 @@
+# ltx2
+
+**English** | [日本語](README.ja.md)
+
+[mlx-video LTX-2](https://github.com/Blaizzy/mlx-video) provides short video generation functionality.
+
+- **T2V**: Generate video from text
+- **I2V**: animate image as first or last frame
+- **A2V**: Drive motion and timing with voice
+- **T2V + Audio**: Generate audio along with video
+
+## API
+
+| Endpoint | Name | Description |
+|---|---|---|
+| `POST /v1/video/ltx2/generate` | Video generation | Generate MP4 from JSON body and any `image` / `end_image` / `audio` FileRef. |
+| `GET /v1/video/ltx2/models` | List of models | Return a list of available models. |
+| `GET /v1/video/ltx2/openapi.json` | OpenAPI | Returns detailed input/output specifications, usage, and TIPS. |
+
+Inferred mode:
+
+| input | mode |
+|---|---|
+| No file attachment | T2V — Text to video |
+| `image` FileRef | I2V — Animate the first frame |
+| `image` + `end_image` FileRef | I2V — Specify first and last frame |
+| `end_image` FileRef | I2V — Specify the last frame |
+| `audio` FileRef | A2V — Drive motion/timing with audio |
+| `image` + `audio` FileRef | A2V + I2V |
+| `generate_audio: true` | T2V + Audio — also generates audio |
+
+- `mode: "sync"` waits until completion and returns raw MP4 bytes by default for single artifacts.
+  If you want Job JSON, add `Accept: application/json`.
+- `mode: "async"` returns `202` and `{job_id}`.
+  Check the progress with `GET /v1/jobs/{job_id}` and after completion use `result.file_id` or
+  Get MP4 with `artifacts[0]`.
+- `audio` files and `generate_audio: true` are exclusive.
+
+## API Docs
+
+- [OpenAPI JSON](https://kiarina.github.io/kiapi/v1/video/ltx2/openapi.json)
+- [Swagger UI](https://kiarina.github.io/kiapi/v1/video/ltx2/docs.html)
+- [ReDoc](https://kiarina.github.io/kiapi/v1/video/ltx2/redoc.html)
+
+## Dependencies
+
+| Package | License | Description |
+|---|---|---|
+| [mlx-video](https://github.com/Blaizzy/mlx-video) | MIT | Run LTX-2 distilled pipeline on MLX. `pyproject.toml` pins known good git commits. |
+
+## Models
+
+| Model | License | Terms | Size | Description |
+|---|---|---|---:|---|
+| [prince-canuma/LTX-2-distilled](https://huggingface.co/prince-canuma/LTX-2-distilled) | [LTX-2 Community License Agreement](https://huggingface.co/Lightricks/LTX-2/blob/main/LICENSE) (derived from [Lightricks/LTX-2](https://huggingface.co/Lightricks/LTX-2) Compliant with repo itself (no model card / LICENSE) | HF gated. However, use and distribution require license agreement | 101 GB | `distilled` (default). Two-stage distilled pipeline. No CFG, about 11 steps inside. A transient model that loads/releases on every call. |
+
+Key defaults and limits:
+
+| Item | Default value | Constraints |
+|---|---:|---|
+| `width` | `512` | Positive multiple of 64. Upper limit `768`. |
+| `height` | `512` | Positive multiple of 64. Upper limit `768`. |
+| `num_frames` | `97` | `1 + 8*k`. Upper limit `721`. |
+| `fps` | `24` | Positive integer. |
+| `image_strength` | `1.0` | `0.0..1.0`. The degree to which I2V is constrained to the input frame. |
+
+`duration = num_frames / fps`. At 24 fps, `97` takes about 4 seconds, `161` takes about 6.7 seconds,
+`241` takes about 10 seconds, `481` takes about 20 seconds, and `721` takes about 30 seconds.
+
+## Notes
+
+- **transient model**:
+  LTX-2 is not a permanent model. Load, create, and free each call, and before execution
+  Reserve a temporary memory budget of approximately 40 GB with `memory.reserve()`. Therefore, `/health`
+  It will not remain in the resident model.
+- **Response format**:
+  If sync produces only one MP4, it defaults to returning the raw MP4.
+  You can trace the metadata from the `X-Kiapi-File-Id` / `X-Kiapi-Job-Id` headers.
+  `Accept: application/json` returns Job JSON.
+- **distilled has no negative guidance**:
+  There is no classifier-free guidance, so there is no negative prompt or `no zoom` / `don't ...`
+  Suppression instructions such as this do not work. The movement, composition, and texture you want, not what you want to avoid.
+  and adjust it with seed and `image_strength`.
+- **I2V's `image_strength`**:
+  `1.0` is strongly fixed to the input frame. If you want to move clearly, set it to around `0.7`
+  Lowering it makes it easier to tolerate changes.
+- **Progress**:
+  mlx-video does not expose per-step progress callbacks. kiapi is
+  Time-based, relative to `progress_eta_base_s`, scaled by number of frames and resolution.
+  Stream synthetic progress.
+- **Notes on updating dependencies**:
+  `mlx-video` is pinned to git commit because the API is changeable. When updating
+  `_models/ltx2.py` calls `generate_video` and routes `PipelineType.DISTILLED`.
+  Please check it and verify it on the actual machine using `make verify-ltx2`.
+
+## Quickstart
+
+### generate — T2V
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "a cat walking through tall grass, sunny, shallow depth of field" \
+'{
+  model: "distilled",
+  mode: "sync",
+  prompt: $prompt,
+  width: 512,
+  height: 512,
+  num_frames: 97,
+  fps: 24,
+  seed: 1
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/video/ltx2/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o ltx2.mp4
+```
+If you want Job JSON:
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "a small paper boat floating on a quiet pond, gentle ripples" \
+'{
+  mode: "sync",
+  prompt: $prompt,
+  width: 512,
+  height: 512,
+  num_frames: 97,
+  seed: 2
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/video/ltx2/generate \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" | jq .
+```
+### generate — I2V
+
+Upload and reference the image you want to use for the first frame to the Files API.
+```bash
+IMAGE_ID=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@first_frame.png;type=image/png" | jq -r .file_id)
+
+PARAMS=$(
+jq -n \
+--arg image "$IMAGE_ID" \
+--arg prompt "gentle wind, leaves moving, soft cinematic motion" \
+'{
+  mode: "sync",
+  prompt: $prompt,
+  image: {type: "file_id", file_id: $image},
+  num_frames: 97,
+  image_strength: 0.7,
+  seed: 3
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/video/ltx2/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o ltx2-i2v.mp4
+```
+To specify the first and last frame:
+```bash
+IMAGE_ID=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@first_frame.png;type=image/png" | jq -r .file_id)
+END_IMAGE_ID=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@last_frame.png;type=image/png" | jq -r .file_id)
+
+PARAMS=$(
+jq -n \
+--arg image "$IMAGE_ID" \
+--arg end_image "$END_IMAGE_ID" \
+--arg prompt "a smooth transition from morning to sunset" \
+'{
+  mode: "sync",
+  prompt: $prompt,
+  image: {type: "file_id", file_id: $image},
+  end_image: {type: "file_id", file_id: $end_image},
+  num_frames: 97,
+  image_strength: 0.8,
+  end_image_strength: 0.8,
+  seed: 4
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/video/ltx2/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o ltx2-first-last.mp4
+```
+### generate — A2V
+
+When you upload and reference audio files to the Files API, audio drives motion, timing, and
+Mixed to output MP4.
+```bash
+AUDIO_ID=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/files \
+-F "file=@drums.wav;type=audio/wav" | jq -r .file_id)
+
+PARAMS=$(
+jq -n \
+--arg audio "$AUDIO_ID" \
+--arg prompt "a drummer on stage, energetic performance, stage lighting" \
+'{
+  mode: "sync",
+  prompt: $prompt,
+  audio: {type: "file_id", file_id: $audio},
+  width: 512,
+  height: 512,
+  num_frames: 97,
+  seed: 5
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/video/ltx2/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o ltx2-a2v.mp4
+```
+### generate — T2V + Audio
+
+Generates audio along with the video without using an audio file.
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "a tiny robot dancing in a neon room, playful electronic beat" \
+'{
+  mode: "sync",
+  prompt: $prompt,
+  width: 512,
+  height: 512,
+  num_frames: 97,
+  generate_audio: true,
+  seed: 6
+}'
+)
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/video/ltx2/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o ltx2-audio.mp4
+```
+
+### async
+
+```bash
+PARAMS=$(
+jq -n \
+--arg prompt "a cinematic shot of clouds moving over a mountain lake" \
+'{
+  mode: "async",
+  prompt: $prompt,
+  width: 512,
+  height: 512,
+  num_frames: 97,
+  seed: 7
+}'
+)
+
+JOB=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/video/ltx2/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 .
+```
+Once completed, use the Job's `artifacts[0]` or `result.file_id` to get the MP4.
+```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 ltx2-async.mp4
+```

kiapi/capabilities/ltx2/__init__.py

@@ -0,0 +1,26 @@
+"""ltx2 family — LTX-2 distilled video generation via mlx-video.
+
+Endpoint: ``POST /v1/video/ltx2/generate`` (multipart; T2V/I2V/A2V inferred from
+attached inputs). mlx-video loads and frees its own weights per call, so this
+family is transient (``resident=False``): the service reserves budget room before
+each run instead of holding a model.
+"""
+
+from kiapi.capabilities import ValidationError
+
+from ._helpers.register import register
+from ._helpers.validate_generate import validate_generate
+from ._operations.detect_mode import detect_mode
+from ._operations.handle_generate import handle_generate
+from ._settings import settings_manager
+from ._views.generate_request import GenerateRequest
+
+__all__ = [
+    "GenerateRequest",  # ._views
+    "ValidationError",  # kiapi.capabilities
+    "detect_mode",  # ._operations
+    "handle_generate",  # ._operations
+    "register",  # ._helpers
+    "settings_manager",  # ._settings
+    "validate_generate",  # ._helpers
+]

kiapi/capabilities/ltx2/_constants/description.py

@@ -0,0 +1,81 @@
+DESCRIPTION = """Short video generation with LTX-2 distilled.
+
+LTX-2 generates short MP4 videos from text, optional image conditioning, and
+optional audio.
+
+## Upstream docs
+- [mlx-video](https://github.com/Blaizzy/mlx-video) — the MLX engine kiapi runs
+- [Lightricks/LTX-2](https://huggingface.co/Lightricks/LTX-2) — upstream model card and license source
+- [prince-canuma/LTX-2-distilled](https://huggingface.co/prince-canuma/LTX-2-distilled) — distilled MLX weights used by kiapi
+
+## Model
+
+- **default model**: `distilled`
+- **repo**: `prince-canuma/LTX-2-distilled`
+- **pipeline**: two-stage distilled LTX-2 via `mlx-video`
+- **residency**: transient. The pipeline is loaded for each job, run, then freed.
+- **memory**: kiapi reserves about 40 GB for the transient run before generation.
+
+The distilled pipeline does not use classifier-free guidance. Negative prompts
+and suppression phrases such as `no zoom`, `do not move`, or `avoid blur` are not
+reliable controls. Describe the desired subject, motion, framing, camera behavior,
+lighting, and texture directly.
+
+## Modes
+
+The generation mode is inferred from attached inputs:
+
+- **T2V**: prompt only
+- **I2V**: prompt + `image`
+- **I2V(first+last)**: prompt + `image` + `end_image`
+- **I2V(last)**: prompt + `end_image`
+- **A2V**: prompt + `audio`
+- **A2V+I2V**: prompt + `image` + `audio`
+- **T2V+Audio**: prompt + `generate_audio=true`
+
+An uploaded or referenced `audio` file drives timing and is muxed into the MP4.
+It cannot be combined with `generate_audio=true`.
+
+## Practical Defaults
+
+The server defaults target a useful quality/speed balance:
+
+- `width`: 512
+- `height`: 512
+- `num_frames`: 97
+- `fps`: 24
+
+At 24 fps, common frame counts are roughly:
+
+- `97`: about 4 seconds
+- `161`: about 6.7 seconds
+- `241`: about 10 seconds
+- `481`: about 20 seconds
+- `721`: about 30 seconds
+
+`num_frames` must be `1 + 8*k`, and width/height must be multiples of 64.
+
+## Tips
+
+- Prefer positive direction over negative constraints. Write what should happen,
+  not what should be prevented.
+- For I2V, `image_strength=1.0` keeps the first frame very stable. Lower values
+  around `0.7` allow more visible motion or composition change.
+- Phrases like `looking at the camera` can encourage push-in/zoom behavior. If a
+  stable gaze is desired, try wording such as `looking ahead`.
+- Use seed sweeps for composition, pose, and camera variation. A few seeds are
+  often more effective than over-constraining the prompt.
+- 512x512 is the sweet spot for general use. Larger resolutions and longer frame
+  counts hold the single-flight queue for longer.
+
+## Performance Notes
+
+Generation time depends heavily on frame count and resolution. A 512x512,
+97-frame job is the baseline used for synthetic progress; shorter/lower
+resolution jobs complete faster, while long 721-frame jobs can occupy the worker
+for much longer.
+
+Because kiapi is single-flight, one LTX-2 job blocks all other heavy jobs until
+it finishes. Use `mode="async"` for longer videos so clients can poll
+`/v1/jobs/{job_id}` instead of holding an HTTP request open.
+"""

kiapi/capabilities/ltx2/_helpers/register.py

@@ -0,0 +1,58 @@
+"""Register ltx2'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, PythonPackageResource
+
+from .._constants.description import DESCRIPTION
+from .._models import ltx2
+from .._settings import settings_manager
+
+MLX_VIDEO_SPEC = (
+    "mlx-video @ git+https://github.com/Blaizzy/mlx-video.git"
+    "@87db56a51758fefb748a359b90a5283bb8ba4837"
+)
+
+
+def register() -> None:
+    capability_spec_registry.register(
+        CapabilitySpec(
+            name="ltx2",
+            domain="video",
+            title="kiapi LTX-2 API",
+            summary="Generate video from text, image, and music or audio inputs.",
+            description=DESCRIPTION,
+            openapi_path="/v1/video/ltx2/openapi.json",
+            docs_path="/v1/video/ltx2/docs",
+            redoc_path="/v1/video/ltx2/redoc",
+            path_prefixes=("/v1/video/ltx2",),
+        )
+    )
+
+    settings = settings_manager.get_settings()
+
+    model_registry.register(
+        ModelSpec(
+            name="distilled",
+            family="ltx2",
+            domain="video",
+            repo=settings.model_repo,
+            module=ltx2,
+            weight_gb=0.0,  # transient: not held resident
+            peak_headroom_gb=40.0,  # transient peak to reserve; reconciled on device
+            framework="mlx",
+            priority=0,
+            default=True,
+            resident=False,
+            setup_resources=(
+                PythonPackageResource(
+                    package="mlx-video",
+                    spec=MLX_VIDEO_SPEC,
+                    import_name="mlx_video.models.ltx_2.generate",
+                    verify_attrs=("PipelineType", "generate_video"),
+                    label_name="mlx-video-ltx2",
+                ),
+                HfSnapshotResource(repo=settings.model_repo, disk_gb=101.0),
+            ),
+        )
+    )

kiapi/capabilities/ltx2/_helpers/validate_generate.py

@@ -0,0 +1,42 @@
+"""Pure validation for LTX-2 generate requests."""
+
+from kiapi.capabilities import ValidationError
+
+from .._settings import settings_manager
+from .._views.generate_request import GenerateRequest
+
+
+def validate_generate(req: GenerateRequest, *, variant: str, has_audio: bool) -> None:
+    settings = settings_manager.get_settings()
+
+    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
+    num_frames = (
+        req.num_frames if req.num_frames is not None else settings.default_num_frames
+    )
+    fps = req.fps if req.fps is not None else settings.default_fps
+
+    if width <= 0 or width % 64 != 0:
+        raise ValidationError(f"width must be a positive multiple of 64 (got {width})")
+    if height <= 0 or height % 64 != 0:
+        raise ValidationError(
+            f"height must be a positive multiple of 64 (got {height})"
+        )
+    if width > settings.max_width:
+        raise ValidationError(f"width {width} exceeds max {settings.max_width}")
+    if height > settings.max_height:
+        raise ValidationError(f"height {height} exceeds max {settings.max_height}")
+    if num_frames < 1 or (num_frames - 1) % 8 != 0:
+        raise ValidationError(
+            f"num_frames must be 1 + 8*k (e.g. 33, 97, 241, 481, 721); got {num_frames}"
+        )
+    if num_frames > settings.max_num_frames:
+        raise ValidationError(
+            f"num_frames {num_frames} exceeds max {settings.max_num_frames}"
+        )
+    if fps <= 0:
+        raise ValidationError(f"fps must be positive (got {fps})")
+    if has_audio and req.generate_audio:
+        raise ValidationError(
+            "cannot combine an audio file (A2V) with generate_audio; choose one"
+        )

kiapi/capabilities/ltx2/_models/ltx2.py

@@ -0,0 +1,106 @@
+"""Handler for LTX-2 distilled (text/image/audio → video; via mlx-video)."""
+
+import time
+from pathlib import Path
+from typing import Any
+
+from kiapi.core.file import FileStore
+from kiapi.core.workdir import create_work_dir
+
+from .._settings import LTX2Settings
+from .._views.generate_params import GenerateParams
+
+FEATURES = {"text", "image", "audio"}
+
+
+def warmup(payload: object | None = None) -> None:
+    """Prime kernels with a tiny T2V generation (artifact discarded)."""
+    from mlx_video.models.ltx_2.generate import (  # type: ignore
+        PipelineType,
+        generate_video,
+    )
+
+    from .._settings import settings_manager
+
+    s = settings_manager.get_settings()
+    tmp = create_work_dir("video/ltx2/warmup")
+    generate_video(
+        model_repo=s.model_repo,
+        text_encoder_repo=s.text_encoder_repo,  # pyright: ignore
+        prompt="warmup",
+        pipeline=PipelineType.DISTILLED,
+        height=256,
+        width=256,
+        num_frames=9,
+        fps=24,
+        seed=0,
+        output_path=str(tmp / "warm.mp4"),
+        verbose=False,
+    )
+
+
+def run_generate(
+    params: GenerateParams,
+    settings: LTX2Settings,
+    files: FileStore,
+    staged: dict[str, Any],
+    mode: str,
+) -> dict[str, Any]:
+    """Blocking generation. Returns artifact metadata (the job's ``result``)."""
+    from mlx_video.models.ltx_2.generate import PipelineType, generate_video
+
+    tmp = create_work_dir("video/ltx2")
+    video_path = tmp / "video.mp4"
+
+    image = staged.get("image")
+    end_image = staged.get("end_image")
+    audio_file = staged.get("audio")
+    wants_audio = audio_file is not None or params.generate_audio
+    audio_out = str(tmp / "audio.wav") if wants_audio else None
+
+    t0 = time.time()
+    generate_video(
+        model_repo=settings.model_repo,
+        text_encoder_repo=settings.text_encoder_repo,  # pyright: ignore
+        prompt=params.prompt,
+        pipeline=PipelineType.DISTILLED,
+        height=params.height,
+        width=params.width,
+        num_frames=params.num_frames,
+        fps=params.fps,
+        seed=params.seed,
+        output_path=str(video_path),
+        image=image,
+        image_strength=params.image_strength,
+        end_image=end_image,
+        end_image_strength=params.end_image_strength,
+        audio=params.generate_audio,
+        audio_file=audio_file,
+        output_audio_path=audio_out,
+        verbose=False,
+    )
+    total_s = round(time.time() - t0, 2)
+
+    if not video_path.exists():
+        raise RuntimeError("generation finished but no video file was produced")
+
+    # Audio (when requested) is muxed into video.mp4 by mlx-video; drop the wav.
+    has_audio = audio_out is not None and Path(audio_out).exists()
+    if audio_out is not None:
+        Path(audio_out).unlink(missing_ok=True)
+
+    meta = {
+        "mode": mode,
+        "prompt": params.prompt,
+        "params": params.gen_params(),
+        "has_audio": has_audio,
+        "timings": {"total_s": total_s},
+    }
+    rec = files.put_path(
+        video_path,
+        filename=f"video_{int(time.time())}.mp4",
+        content_type="video/mp4",
+        meta=meta,
+        move=True,
+    )
+    return {"file_id": rec.file_id, "video_bytes": rec.size, **meta}

kiapi/capabilities/ltx2/_operations/detect_mode.py

@@ -0,0 +1,19 @@
+"""Infer the LTX-2 generation mode from attached inputs."""
+
+
+def detect_mode(
+    *, has_image: bool, has_end_image: bool, has_audio: bool, generate_audio: bool
+) -> str:
+    is_i2v = has_image or has_end_image
+
+    if has_audio:
+        return "A2V+I2V" if is_i2v else "A2V"
+
+    if is_i2v:
+        if has_image and has_end_image:
+            return "I2V(first+last)"
+        if has_end_image:
+            return "I2V(last)"
+        return "I2V"
+
+    return "T2V+Audio" if generate_audio else "T2V"

kiapi/capabilities/ltx2/_operations/handle_generate.py

@@ -0,0 +1,52 @@
+"""LTX-2 generate service entry (worker-thread thunk body)."""
+
+from kiapi.capabilities import resolve_file_ref
+from kiapi.core.app import AppContext
+from kiapi.core.file import FileID
+from kiapi.core.job import JobResult, creep_progress
+from kiapi.core.model import model_registry
+
+from .._settings import settings_manager
+from .._views.generate_params import GenerateParams
+from .._views.generate_request import GenerateRequest
+from .resolve_generate_params import resolve_generate_params
+
+
+def handle_generate(
+    ctx: AppContext,
+    req: GenerateRequest,
+    mode: str,
+) -> tuple[JobResult, list[FileID]]:
+    settings = settings_manager.get_settings()
+    spec = model_registry.resolve("ltx2", req.model)
+    ctx.ensure_model_ready(spec)
+    params = resolve_generate_params(settings, req, variant=spec.name)
+    staged = _resolve_staged_inputs(ctx, req)
+
+    ctx.memory_manager.reserve(spec.weight_gb + spec.peak_headroom_gb)
+
+    with creep_progress(eta_s=_calc_eta_s(params, settings.progress_eta_base_s)):
+        result = spec.module.run_generate(
+            params, settings, ctx.file_store, staged, mode
+        )
+
+    return result, [result["file_id"]]
+
+
+def _resolve_staged_inputs(ctx: AppContext, req: GenerateRequest) -> dict[str, str]:
+    staged: dict[str, str] = {}
+    if req.image is not None:
+        staged["image"] = resolve_file_ref(ctx.file_store, req.image, kind="image").path
+    if req.end_image is not None:
+        staged["end_image"] = resolve_file_ref(
+            ctx.file_store, req.end_image, kind="end_image"
+        ).path
+    if req.audio is not None:
+        staged["audio"] = resolve_file_ref(ctx.file_store, req.audio, kind="audio").path
+    return staged
+
+
+def _calc_eta_s(params: GenerateParams, base_s: float) -> float:
+    frames = params.num_frames / 97
+    pixels = (params.width * params.height) / (512 * 512)
+    return base_s * max(frames * pixels, 0.1)

kiapi/capabilities/ltx2/_operations/resolve_generate_params.py

@@ -0,0 +1,31 @@
+"""Merge an LTX-2 generate request with settings defaults."""
+
+import random
+
+from .._settings import LTX2Settings
+from .._views.generate_params import GenerateParams
+from .._views.generate_request import GenerateRequest
+
+
+def resolve_generate_params(
+    settings: LTX2Settings,
+    req: GenerateRequest,
+    *,
+    variant: str,
+) -> GenerateParams:
+    return GenerateParams(
+        model=variant,
+        prompt=req.prompt,
+        seed=req.seed if req.seed is not None else random.randint(0, 2**31 - 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,
+        num_frames=(
+            req.num_frames
+            if req.num_frames is not None
+            else settings.default_num_frames
+        ),
+        fps=req.fps if req.fps is not None else settings.default_fps,
+        image_strength=req.image_strength,
+        end_image_strength=req.end_image_strength,
+        generate_audio=req.generate_audio,
+    )