kiapi 0.1.0__py3-none-any.whl

kiapi/api/image/ideogram4/router.py

@@ -0,0 +1,87 @@
+"""Image API (ideogram4): Ideogram 4 txt2img."""
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import Response
+
+from kiapi.api import (
+    REQUIRE_AUTH,
+    build_job_responses,
+    get_accept,
+    get_ctx,
+    get_worker,
+    register_capability_endpoints,
+    submit_and_maybe_wait,
+)
+from kiapi.capabilities.ideogram4 import (
+    GenerateRequest,
+    ValidationError,
+    handle_generate,
+    validate_generate,
+)
+from kiapi.core.app import AppContext
+from kiapi.core.model import UnknownModelError, model_registry
+from kiapi.core.worker import Worker
+
+from ._views.image_response import ImageResponse
+
+router = APIRouter(dependencies=REQUIRE_AUTH)
+
+
+@router.post(
+    "/v1/image/ideogram4/generate",
+    responses=build_job_responses(
+        "image/png", "image/jpeg", "image/webp", result_model=ImageResponse
+    ),
+)
+async def generate(
+    req: GenerateRequest,
+    accept: str | None = Depends(get_accept),
+    ctx: AppContext = Depends(get_ctx),
+    worker: Worker = Depends(get_worker),
+) -> Response:
+    """Generate one image from a text prompt or JSON caption (Ideogram 4, text-to-image).
+
+    Ideogram 4 is typography-focused txt2img — there is no image-to-image or
+    training. Prefer a structured JSON `prompt` (high_level_description,
+    optional style_description, compositional_deconstruction with element
+    `bbox`/`text`) for crisp lettering; plain text works but is usually weaker.
+    The same endpoint serves both `sync` and `async` via `mode`. Pick the
+    speed/quality tradeoff with `preset` (V4_TURBO_12 → V4_DEFAULT_20 →
+    V4_QUALITY_48).
+
+    Sync content negotiation: a single image is produced, so unless the client
+    asks for JSON the raw image bytes are returned with `X-Kiapi-File-Id` /
+    `X-Kiapi-Job-Id` headers — `curl -o out.png` just works. With
+    `Accept: application/json` (or async) the Job JSON is returned, whose
+    `result` follows ImageResponse.
+
+    A `quantize` differing from the resident model runs a one-off transient
+    model (slower, not reused). Ideogram 4 may return an 'Image blocked by safety
+    filter' image (including false positives); kiapi stores it as the artifact
+    rather than raising an error. Async returns 202 immediately; poll
+    GET /v1/jobs/{job_id} and fetch the artifact via GET /v1/files/{file_id}.
+    """
+    try:
+        spec = model_registry.resolve("ideogram4", req.model)
+    except UnknownModelError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))  # noqa: B904
+    try:
+        validate_generate(req)
+    except ValidationError as exc:
+        raise HTTPException(status_code=422, detail=str(exc))  # noqa: B904
+
+    def thunk():  # type: ignore
+        return handle_generate(ctx, req)
+
+    return await submit_and_maybe_wait(
+        ctx,
+        worker,
+        type="ideogram4",
+        params=req.gen_params() | {"model": spec.name, "mode": req.mode},
+        thunk=thunk,
+        mode=req.mode,
+        accept=accept,
+    )
+
+
+register_capability_endpoints(router, name="ideogram4", base_path="/v1/image/ideogram4")

kiapi/api/image/qwen/_views/image_response.py

@@ -0,0 +1,47 @@
+"""``/v1/image/qwen/{generate,edit}`` result payload (the Job ``result`` shape).
+
+Mirrors the dict returned by ``capabilities/qwen/_models/qwen._store_image`` so the
+produced image result is self-describing in OpenAPI. It is an output-side
+projection of the model result (not a model-coupled view), so it lives under
+``api/image/qwen/_views``. The same shape is returned by both generate and edit.
+
+``ImageResponse`` is the sole public element; nested pieces stay private.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class _Timings(BaseModel):
+    total_s: float = Field(
+        description="Wall-clock generation time in seconds (model run only)."
+    )
+
+
+class ImageResponse(BaseModel):
+    """Capability-specific ``result`` for a succeeded qwen generate/edit job."""
+
+    model: str = Field(description="Resolved model variant that produced the image.")
+    prompt: str = Field(description="The prompt used for the run.")
+
+    file_id: str = Field(
+        description=(
+            "Files-API id of the produced image. Fetch metadata at "
+            "GET /v1/files/{id} or bytes at /download. This is also the artifact "
+            "returned as raw bytes by a single-artifact sync call."
+        )
+    )
+    image_bytes: int = Field(description="Size of the produced image in bytes.")
+
+    width: int = Field(description="Width in pixels of the produced image.")
+    height: int = Field(description="Height in pixels of the produced image.")
+
+    params: dict[str, Any] = Field(
+        description=(
+            "Resolved parameters actually used for the run (model, prompt, seed, "
+            "width, height, steps, guidance, quantize, scheduler, format, quality, "
+            "loras, …), so the result is reproducible."
+        )
+    )
+    timings: _Timings = Field(description="kiapi extension: server-side timing.")

kiapi/api/image/qwen/router.py

@@ -0,0 +1,141 @@
+"""Image API (qwen): Qwen Image generate/edit."""
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import Response
+
+from kiapi.api import (
+    REQUIRE_AUTH,
+    build_job_responses,
+    get_accept,
+    get_ctx,
+    get_worker,
+    register_capability_endpoints,
+    submit_and_maybe_wait,
+)
+from kiapi.capabilities.qwen import (
+    EditRequest,
+    GenerateRequest,
+    ValidationError,
+    handle_edit,
+    handle_generate,
+    validate_edit,
+    validate_generate,
+)
+from kiapi.core.app import AppContext
+from kiapi.core.model import UnknownModelError, model_registry
+from kiapi.core.worker import Worker
+
+from ._views.image_response import ImageResponse
+
+router = APIRouter(dependencies=REQUIRE_AUTH)
+
+
+@router.post(
+    "/v1/image/qwen/generate",
+    responses=build_job_responses(
+        "image/png", "image/jpeg", "image/webp", result_model=ImageResponse
+    ),
+)
+async def generate_qwen_endpoint(
+    req: GenerateRequest,
+    accept: str | None = Depends(get_accept),
+    ctx: AppContext = Depends(get_ctx),
+    worker: Worker = Depends(get_worker),
+) -> Response:
+    """Generate an image from a text prompt (Qwen Image, text-to-image / img2img).
+
+    Plain text-to-image by default; supply `init_image` (+ optional
+    `image_strength`) to run img2img instead — use `/v1/image/qwen/edit` for
+    natural-language single/multi-image editing. The same endpoint serves both
+    `sync` and `async` via `mode`. This endpoint only accepts the `image` model
+    variant.
+
+    Sync content negotiation: a single image is produced, so unless the client
+    asks for JSON the raw image bytes are returned with `X-Kiapi-File-Id` /
+    `X-Kiapi-Job-Id` headers — `curl -o out.png` just works. With
+    `Accept: application/json` (or async) the Job JSON is returned, whose
+    `result` follows ImageResponse.
+
+    Any `loras` or a `quantize` differing from the resident model runs a one-off
+    transient model (slower, not reused). Async returns 202 immediately; poll
+    GET /v1/jobs/{job_id} and fetch the artifact via GET /v1/files/{file_id}.
+    """
+    try:
+        spec = model_registry.resolve("qwen", req.model or "image")
+    except UnknownModelError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))  # noqa: B904
+    if spec.name != "image":
+        raise HTTPException(
+            status_code=400, detail="qwen generate requires model 'image'"
+        )
+    try:
+        validate_generate(req)
+    except ValidationError as exc:
+        raise HTTPException(status_code=422, detail=str(exc))  # noqa: B904
+
+    def thunk():  # type: ignore
+        return handle_generate(ctx, req)
+
+    return await submit_and_maybe_wait(
+        ctx,
+        worker,
+        type="qwen",
+        params=req.gen_params() | {"model": spec.name, "mode": req.mode},
+        thunk=thunk,
+        mode=req.mode,
+        accept=accept,
+    )
+
+
+@router.post(
+    "/v1/image/qwen/edit",
+    responses=build_job_responses(
+        "image/png", "image/jpeg", "image/webp", result_model=ImageResponse
+    ),
+)
+async def edit_qwen_endpoint(
+    req: EditRequest,
+    accept: str | None = Depends(get_accept),
+    ctx: AppContext = Depends(get_ctx),
+    worker: Worker = Depends(get_worker),
+) -> Response:
+    """Edit / combine one or more reference images with a prompt (Qwen Image Edit).
+
+    Takes a list of `images` (FileRefs, single or multi-image) plus a
+    natural-language `prompt`. For plain image-to-image from a single seed image,
+    use `init_image` on `/v1/image/qwen/generate` instead. The same endpoint
+    serves both `sync` and `async` via `mode`. This endpoint only accepts the
+    `edit-2509` model variant.
+
+    Sync content negotiation, transient-model behavior (`loras` / `quantize`
+    override), and the ImageResponse `result` shape match
+    `/v1/image/qwen/generate`.
+    """
+    try:
+        spec = model_registry.resolve("qwen", req.model or "edit-2509")
+    except UnknownModelError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))  # noqa: B904
+    if spec.name != "edit-2509":
+        raise HTTPException(
+            status_code=400, detail="qwen edit requires model 'edit-2509'"
+        )
+    try:
+        validate_edit(req)
+    except ValidationError as exc:
+        raise HTTPException(status_code=422, detail=str(exc))  # noqa: B904
+
+    def thunk():  # type: ignore
+        return handle_edit(ctx, req)
+
+    return await submit_and_maybe_wait(
+        ctx,
+        worker,
+        type="qwen-edit",
+        params=req.gen_params() | {"model": spec.name, "mode": req.mode},
+        thunk=thunk,
+        mode=req.mode,
+        accept=accept,
+    )
+
+
+register_capability_endpoints(router, name="qwen", base_path="/v1/image/qwen")

kiapi/api/image/seedvr2/_views/image_response.py

@@ -0,0 +1,50 @@
+"""``/v1/image/seedvr2/upscale`` result payload (the Job ``result`` shape).
+
+Mirrors the dict returned by ``capabilities/seedvr2/_models/seedvr2._store_image``
+so the upscaled image result is self-describing in OpenAPI. It is an output-side
+projection of the model result (not a model-coupled view), so it lives under
+``api/image/seedvr2/_views``.
+
+``ImageResponse`` is the sole public element; nested pieces stay private.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class _Timings(BaseModel):
+    total_s: float = Field(
+        description="Wall-clock upscale time in seconds (model run only)."
+    )
+
+
+class ImageResponse(BaseModel):
+    """Capability-specific ``result`` for a succeeded seedvr2 upscale job."""
+
+    model: str = Field(
+        description="Resolved model variant that produced the image (3b or 7b)."
+    )
+
+    file_id: str = Field(
+        description=(
+            "Files-API id of the upscaled image. Fetch metadata at "
+            "GET /v1/files/{id} or bytes at /download. This is also the artifact "
+            "returned as raw bytes by a single-artifact sync call."
+        )
+    )
+    image_bytes: int = Field(description="Size of the produced image in bytes.")
+
+    input_width: int = Field(description="Width in pixels of the input image.")
+    input_height: int = Field(description="Height in pixels of the input image.")
+    width: int = Field(description="Width in pixels of the upscaled image.")
+    height: int = Field(description="Height in pixels of the upscaled image.")
+
+    params: dict[str, Any] = Field(
+        description=(
+            "Resolved parameters actually used for the run (model, resolution, "
+            "softness, seed, quantize, format, quality), so the result is "
+            "reproducible."
+        )
+    )
+    timings: _Timings = Field(description="kiapi extension: server-side timing.")

kiapi/api/image/seedvr2/router.py

@@ -0,0 +1,83 @@
+"""Image API (seedvr2): ``POST /v1/image/seedvr2/upscale``."""
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import Response
+
+from kiapi.api import (
+    REQUIRE_AUTH,
+    build_job_responses,
+    get_accept,
+    get_ctx,
+    get_worker,
+    register_capability_endpoints,
+    submit_and_maybe_wait,
+)
+from kiapi.capabilities.seedvr2 import (
+    UpscaleRequest,
+    ValidationError,
+    handle_upscale,
+    validate_upscale,
+)
+from kiapi.core.app import AppContext
+from kiapi.core.model import UnknownModelError, model_registry
+from kiapi.core.worker import Worker
+
+from ._views.image_response import ImageResponse
+
+router = APIRouter(dependencies=REQUIRE_AUTH)
+
+
+@router.post(
+    "/v1/image/seedvr2/upscale",
+    responses=build_job_responses(
+        "image/png", "image/jpeg", "image/webp", result_model=ImageResponse
+    ),
+)
+async def upscale_seedvr2_endpoint(
+    req: UpscaleRequest,
+    accept: str | None = Depends(get_accept),
+    ctx: AppContext = Depends(get_ctx),
+    worker: Worker = Depends(get_worker),
+) -> Response:
+    """Upscale one image with diffusion super-resolution (SeedVR2 via mflux).
+
+    Takes an input `image` (FileRef) and produces a higher-resolution version.
+    SeedVR2 is super-resolution, not prompt-driven generation — there is no
+    prompt. The target size is set by `resolution`: an integer shortest-edge
+    pixel target (16..2048) or a scale factor like `"2x"` (up to `4.0x`). The
+    same endpoint serves both `sync` and `async` via `mode`.
+
+    Sync content negotiation: a single image is produced, so unless the client
+    asks for JSON the raw image bytes are returned with `X-Kiapi-File-Id` /
+    `X-Kiapi-Job-Id` headers — `curl -o out.png` just works. With
+    `Accept: application/json` (or async) the Job JSON is returned, whose
+    `result` follows ImageResponse.
+
+    A `quantize` differing from the resident model's quantization runs a one-off
+    transient model (slower, not reused). Async returns 202 immediately; poll
+    GET /v1/jobs/{job_id} and fetch the artifact via GET /v1/files/{file_id}.
+    """
+    try:
+        spec = model_registry.resolve("seedvr2", req.model)
+    except UnknownModelError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))  # noqa: B904
+    try:
+        validate_upscale(req)
+    except ValidationError as exc:
+        raise HTTPException(status_code=422, detail=str(exc))  # noqa: B904
+
+    def thunk():  # type: ignore
+        return handle_upscale(ctx, req)
+
+    return await submit_and_maybe_wait(
+        ctx,
+        worker,
+        type="seedvr2",
+        params=req.gen_params() | {"model": spec.name, "mode": req.mode},
+        thunk=thunk,
+        mode=req.mode,
+        accept=accept,
+    )
+
+
+register_capability_endpoints(router, name="seedvr2", base_path="/v1/image/seedvr2")

kiapi/api/image/zimage/_views/image_response.py

@@ -0,0 +1,49 @@
+"""``/v1/image/zimage/generate`` result payload (the Job ``result`` shape).
+
+Mirrors the dict returned by ``capabilities/zimage/_models/zimage._store_image``
+so the produced image result is self-describing in OpenAPI. It is an output-side
+projection of the model result (not a model-coupled view), so it lives under
+``api/image/zimage/_views``.
+
+``ImageResponse`` is the sole public element; nested pieces stay private.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class _Timings(BaseModel):
+    total_s: float = Field(
+        description="Wall-clock generation time in seconds (model run only)."
+    )
+
+
+class ImageResponse(BaseModel):
+    """Capability-specific ``result`` for a succeeded zimage generate job."""
+
+    model: str = Field(
+        description="Resolved model variant that produced the image (turbo | base)."
+    )
+    prompt: str = Field(description="The prompt used for the run.")
+
+    file_id: str = Field(
+        description=(
+            "Files-API id of the produced image. Fetch metadata at "
+            "GET /v1/files/{id} or bytes at /download. This is also the artifact "
+            "returned as raw bytes by a single-artifact sync call."
+        )
+    )
+    image_bytes: int = Field(description="Size of the produced image in bytes.")
+
+    width: int = Field(description="Width in pixels of the produced image.")
+    height: int = Field(description="Height in pixels of the produced image.")
+
+    params: dict[str, Any] = Field(
+        description=(
+            "Resolved parameters actually used for the run (model, prompt, seed, "
+            "width, height, steps, guidance, quantize, format, quality, loras), so "
+            "the result is reproducible."
+        )
+    )
+    timings: _Timings = Field(description="kiapi extension: server-side timing.")

kiapi/api/image/zimage/router.py

@@ -0,0 +1,131 @@
+"""Image API (zimage): ``POST /v1/image/zimage/generate`` (JSON; sync or async)."""
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import Response
+
+from kiapi.api import (
+    REQUIRE_AUTH,
+    build_job_responses,
+    build_train_responses,
+    get_accept,
+    get_ctx,
+    get_worker,
+    register_capability_endpoints,
+    submit_and_maybe_wait,
+)
+from kiapi.capabilities.zimage import (
+    GenerateRequest,
+    TrainRequest,
+    ValidationError,
+    handle_generate,
+    handle_train,
+    validate_generate,
+)
+from kiapi.core.app import AppContext
+from kiapi.core.file import FileIDRef
+from kiapi.core.model import UnknownModelError, model_registry
+from kiapi.core.worker import Worker
+
+from ._views.image_response import ImageResponse
+
+router = APIRouter(dependencies=REQUIRE_AUTH)
+
+
+@router.post(
+    "/v1/image/zimage/generate",
+    responses=build_job_responses(
+        "image/png", "image/jpeg", "image/webp", result_model=ImageResponse
+    ),
+)
+async def generate_image_endpoint(
+    req: GenerateRequest,
+    accept: str | None = Depends(get_accept),
+    ctx: AppContext = Depends(get_ctx),
+    worker: Worker = Depends(get_worker),
+) -> Response:
+    """Generate an image from a text prompt (Z-Image, text-to-image).
+
+    No input image — Z-Image is txt2img only. The same endpoint serves both
+    `sync` and `async` via `mode`. Variant defaults differ: `turbo` (default) is
+    distilled, few-step and fast; `base` is the full model — more steps and
+    guidance, higher quality but slower.
+
+    Sync content negotiation: a single image is produced, so unless the client
+    asks for JSON the raw image bytes are returned with `X-Kiapi-File-Id` /
+    `X-Kiapi-Job-Id` headers — `curl -o out.png` just works. With
+    `Accept: application/json` (or async) the Job JSON is returned, whose
+    `result` follows ImageResponse.
+
+    Any `loras` or a `quantize` differing from the resident model runs a one-off
+    transient model (slower, not reused). Async returns 202 immediately; poll
+    GET /v1/jobs/{job_id} and fetch the artifact via GET /v1/files/{file_id}.
+    """
+    try:
+        spec = model_registry.resolve("zimage", req.model)
+    except UnknownModelError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))  # noqa: B904
+    try:
+        validate_generate(req, variant=spec.name)
+    except ValidationError as exc:
+        raise HTTPException(status_code=422, detail=str(exc))  # noqa: B904
+
+    def thunk():  # type: ignore
+        return handle_generate(ctx, req)
+
+    return await submit_and_maybe_wait(
+        ctx,
+        worker,
+        type="zimage",
+        params=req.gen_params() | {"model": spec.name, "mode": req.mode},
+        thunk=thunk,
+        mode=req.mode,
+        accept=accept,
+    )
+
+
+@router.post("/v1/image/zimage/train", responses=build_train_responses())
+async def train_zimage_endpoint(
+    req: TrainRequest,
+    ctx: AppContext = Depends(get_ctx),
+    worker: Worker = Depends(get_worker),
+) -> Response:
+    """Train a LoRA adapter on a captioned image set (Z-Image, always async).
+
+    Long-running, so this endpoint is always async: it returns 202 with a
+    job_id — poll GET /v1/jobs/{job_id}. The `dataset` is a Files-API ZIP whose
+    images each have a same-stem `.txt` caption. On success the job's `result`
+    holds `adapter_file_id` (the trained `.safetensors`, also the artifact),
+    `adapter_bytes`, `num_images`, the resolved `config`, `lora_targets`,
+    `checkpoint`, and `timings`; the adapter can then be passed back via `loras`
+    on generate."""
+    try:
+        spec = model_registry.resolve("zimage", req.model)
+    except UnknownModelError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))  # noqa: B904
+    if (
+        isinstance(req.dataset, FileIDRef)
+        and ctx.file_store.get(req.dataset.file_id) is None
+    ):
+        raise HTTPException(
+            status_code=400, detail=f"unknown dataset file_id {req.dataset.file_id!r}"
+        )
+
+    def thunk():  # type: ignore
+        return handle_train(ctx, req)
+
+    return await submit_and_maybe_wait(
+        ctx,
+        worker,
+        type="zimage-train",
+        params={
+            "model": spec.name,
+            "dataset": req.dataset.model_dump(mode="json"),
+            "num_epochs": req.num_epochs,
+            "lora_rank": req.lora_rank,
+        },
+        thunk=thunk,
+        mode="async",
+    )
+
+
+register_capability_endpoints(router, name="zimage", base_path="/v1/image/zimage")

kiapi/api/jobs/_operations/get_job_id.py

@@ -0,0 +1,18 @@
+from typing import Annotated
+
+from fastapi import Path
+
+from kiapi.core.job import JobID
+
+
+def get_job_id(
+    job_id: Annotated[
+        str,
+        Path(
+            pattern=r"^job_[0-9a-f]+$",
+            description="In-memory job id returned by async or sync inference requests.",
+            examples=["job_0123456789abcdef"],
+        ),
+    ],
+) -> JobID:
+    return job_id

kiapi/api/jobs/_views/job_delete_response.py

@@ -0,0 +1,19 @@
+from pydantic import BaseModel, Field
+
+
+class JobDeleteResponse(BaseModel):
+    deleted: bool = Field(
+        ...,
+        description="True when the job was removed from the in-memory job store.",
+        examples=[True],
+    )
+    job_id: str = Field(
+        ...,
+        description="Deleted job id.",
+        examples=["job_0123456789abcdef"],
+    )
+    was_running: bool = Field(
+        ...,
+        description="True if the job was running when deleted. Running jobs cannot be interrupted; deletion only forgets the record.",
+        examples=[False],
+    )

kiapi/api/jobs/_views/job_list_response.py

@@ -0,0 +1,15 @@
+from pydantic import BaseModel, Field
+
+from kiapi.core.job import Job
+
+
+class JobListResponse(BaseModel):
+    object: str = Field(
+        default="list",
+        description="OpenAI-style list envelope marker.",
+        examples=["list"],
+    )
+    data: list[Job] = Field(
+        default_factory=list,
+        description="Jobs currently retained in the in-memory job store.",
+    )