kiapi 0.1.0__py3-none-any.whl

kiapi/api/app.py

@@ -0,0 +1,150 @@
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html
+from fastapi.responses import HTMLResponse
+
+from kiapi.api import build_openapi
+from kiapi.core.app import AppContext
+from kiapi.core.capability import capability_spec_registry
+from kiapi.core.logging import setup_logger
+from kiapi.core.model import model_registry
+from kiapi.core.worker import create_worker
+
+from .audio.acestep.router import router as acestep_router
+from .audio.audiogen.router import router as audiogen_router
+from .chat.router import router as chat_router
+from .embedding.router import router as embedding_router
+from .files.router import router as files_router
+from .health.router import router as health_router
+from .image.depthpro.router import router as depthpro_router
+from .image.ernie.router import router as ernie_router
+from .image.flux2.router import router as flux2_router
+from .image.ideogram4.router import router as ideogram4_router
+from .image.qwen.router import router as qwen_router
+from .image.seedvr2.router import router as seedvr2_router
+from .image.zimage.router import router as zimage_router
+from .jobs.router import router as jobs_router
+from .models.router import router as models_router
+from .video.ltx2.router import router as ltx2_router
+from .web.router import router as web_router
+
+logger = logging.getLogger(__name__)
+
+COMMON_OPENAPI_PATHS = (
+    "/health",
+    "/v1/files",
+    "/v1/jobs",
+)
+CAPABILITY_DESCRIPTION_DOMAIN_ORDER = (
+    "chat",
+    "embedding",
+    "image",
+    "audio",
+    "video",
+    "web",
+)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):  # type: ignore
+    setup_logger()
+
+    if not model_registry.list_specs() or not capability_spec_registry.list_specs():
+        raise RuntimeError(
+            "kiapi capabilities are not registered. "
+            "Start the server with `kiapi run` instead of importing the ASGI app directly."
+        )
+
+    ctx = AppContext.create()
+    worker = create_worker(ctx)
+
+    app.state.ctx = ctx
+    app.state.worker = worker
+
+    worker.start()
+
+    asyncio.create_task(worker.warmup())  # noqa: RUF006
+
+    yield
+
+    await worker.stop()
+
+
+app = FastAPI(title="kiapi", lifespan=lifespan, docs_url=None, redoc_url=None)
+
+
+def root_openapi() -> dict:
+    return build_openapi(
+        app,
+        title="kiapi Common API",
+        description=_root_openapi_description(),
+        path_prefixes=COMMON_OPENAPI_PATHS,
+    )
+
+
+def _root_openapi_description() -> str:
+    lines = [
+        "Common kiapi endpoints.",
+        "",
+        "Capability-specific docs:",
+    ]
+    specs = capability_spec_registry.list_specs()
+    for domain in CAPABILITY_DESCRIPTION_DOMAIN_ORDER:
+        domain_specs = [spec for spec in specs if spec.domain == domain]
+        if not domain_specs:
+            continue
+        lines.append(f"- **{domain}**")
+        for spec in domain_specs:
+            lines.append(
+                f"  - **{spec.title}** - {spec.summary} "
+                f"[Swagger UI]({spec.docs_path}), "
+                f"[ReDoc]({spec.redoc_path}), "
+                f"[OpenAPI JSON]({spec.openapi_path})"
+            )
+    for spec in specs:
+        if spec.domain in CAPABILITY_DESCRIPTION_DOMAIN_ORDER:
+            continue
+        if f"- **{spec.domain}**" not in lines:
+            lines.append(f"- **{spec.domain}**")
+        lines.append(
+            f"  - **{spec.title}** - {spec.summary} "
+            f"[Swagger UI]({spec.docs_path}), "
+            f"[ReDoc]({spec.redoc_path}), "
+            f"[OpenAPI JSON]({spec.openapi_path})"
+        )
+    return "\n".join(lines)
+
+
+app.openapi = root_openapi  # type: ignore[method-assign]
+
+
+@app.get("/docs", include_in_schema=False)
+async def root_docs() -> HTMLResponse:
+    return get_swagger_ui_html(openapi_url="/openapi.json", title="kiapi Common API")
+
+
+@app.get("/redoc", include_in_schema=False)
+async def root_redoc() -> HTMLResponse:
+    return get_redoc_html(openapi_url="/openapi.json", title="kiapi Common API")
+
+
+app.include_router(health_router)
+app.include_router(files_router)
+app.include_router(jobs_router)
+app.include_router(chat_router)
+app.include_router(models_router)
+app.include_router(embedding_router)
+app.include_router(depthpro_router)
+app.include_router(ernie_router)
+app.include_router(flux2_router)
+app.include_router(ideogram4_router)
+app.include_router(qwen_router)
+app.include_router(seedvr2_router)
+app.include_router(zimage_router)
+app.include_router(acestep_router)
+app.include_router(audiogen_router)
+app.include_router(ltx2_router)
+app.include_router(web_router)

kiapi/api/audio/acestep/_views/extract_response.py

@@ -0,0 +1,57 @@
+"""``/v1/audio/acestep/extract`` result payload (the Job ``result`` shape).
+
+Mirrors the dict returned by ``capabilities/acestep/_operations/handle_extract``:
+one job runs source separation for every requested target and collects one stem
+per target. It is an output-side projection of the model result (not a
+model-coupled view), so it lives under ``api/audio/acestep/_views``.
+
+``ExtractResponse`` 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 separation time in seconds for this stem."
+    )
+
+
+class _Stem(BaseModel):
+    target: str = Field(description="Stem name, e.g. vocals / drums / bass / other.")
+    model: str = Field(description="Resolved preset that produced the stem.")
+    src: str = Field(description="Files-API id of the source track.")
+
+    file_id: str = Field(
+        description=(
+            "Files-API id of this stem's WAV. Fetch metadata at GET /v1/files/{id} "
+            "or bytes at /download."
+        )
+    )
+    audio_bytes: int = Field(description="Size of the stem WAV in bytes.")
+
+    params: dict[str, Any] = Field(
+        description="Resolved parameters used to separate this stem."
+    )
+    timings: _Timings = Field(description="kiapi extension: server-side timing.")
+
+
+class ExtractResponse(BaseModel):
+    """Capability-specific ``result`` for a succeeded extract job.
+
+    A single job produces one stem per requested target; ``artifacts`` lists the
+    same file_ids in ``stems`` order.
+    """
+
+    task: str = Field(description="Always `extract` for this endpoint.")
+    source_file_id: str = Field(
+        description="Files-API id of the source track that was separated."
+    )
+    targets: list[str] = Field(
+        description="The requested stems, in the order they appear in `stems`."
+    )
+    stems: list[_Stem] = Field(
+        description="One produced stem per target; each references its own WAV file_id."
+    )

kiapi/api/audio/acestep/_views/track_response.py

@@ -0,0 +1,57 @@
+"""``/v1/audio/acestep/{generate,cover,repaint}`` result payload (the Job ``result``).
+
+Mirrors the dict returned by ``capabilities/acestep/_models/acestep.generate_track``
+so the produced track 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/audio/acestep/_views``. The same single-track shape is returned by generate,
+cover, and repaint; ``src`` is present only for cover/repaint.
+
+``TrackResponse`` 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 (subprocess run only)."
+    )
+
+
+class TrackResponse(BaseModel):
+    """Capability-specific ``result`` for a succeeded generate/cover/repaint job."""
+
+    task: str = Field(
+        description="Operation that produced the track: text2music, cover, or repaint."
+    )
+    model: str = Field(
+        description="Resolved preset that produced the track (xl-base or turbo)."
+    )
+
+    file_id: str = Field(
+        description=(
+            "Files-API id of the produced WAV. 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."
+        )
+    )
+    audio_bytes: int = Field(description="Size of the produced WAV in bytes.")
+
+    src: str | None = Field(
+        default=None,
+        description=(
+            "Files-API id of the source track. Present for cover/repaint; null for "
+            "generate (which takes no source)."
+        ),
+    )
+
+    params: dict[str, Any] = Field(
+        description=(
+            "Resolved parameters actually used for the run (prompt, lyrics, duration, "
+            "seed, inference_steps, guidance_scale, shift, …), so the result is "
+            "reproducible."
+        )
+    )
+    timings: _Timings = Field(description="kiapi extension: server-side timing.")

kiapi/api/audio/acestep/router.py

@@ -0,0 +1,190 @@
+"""Music API (acestep): ``POST /v1/audio/acestep/{generate,cover,repaint,extract}``.
+
+Each endpoint is sync or async via ``mode``. generate validates the duration cap.
+"""
+
+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.acestep import (
+    CoverRequest,
+    ExtractRequest,
+    GenerateRequest,
+    RepaintRequest,
+    handle_cover,
+    handle_extract,
+    handle_generate,
+    handle_repaint,
+    settings_manager,
+)
+from kiapi.core.app import AppContext
+from kiapi.core.model import UnknownModelError, model_registry
+from kiapi.core.worker import Worker
+
+from ._views.extract_response import ExtractResponse
+from ._views.track_response import TrackResponse
+
+router = APIRouter(dependencies=REQUIRE_AUTH)
+
+
+def _validate_model(model: str) -> None:
+    try:
+        model_registry.resolve("acestep", model)
+    except UnknownModelError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))  # noqa: B904
+
+
+@router.post(
+    "/v1/audio/acestep/generate",
+    responses=build_job_responses("audio/wav", result_model=TrackResponse),
+)
+async def generate_music(
+    req: GenerateRequest,
+    accept: str | None = Depends(get_accept),
+    ctx: AppContext = Depends(get_ctx),
+    worker: Worker = Depends(get_worker),
+) -> Response:
+    """Generate a brand-new song from a style prompt + lyrics (text2music).
+
+    Takes no source track: `prompt` describes the SOUND, `lyrics` carries the
+    section-tagged words (or `[Instrumental]`), and `duration`/`lang` shape the
+    output. To restyle or edit an existing track use `/cover`, `/repaint`, or
+    `/extract` instead. The same endpoint serves both `sync` and `async` via
+    `mode`.
+
+    Sync content negotiation: one WAV is produced, so unless the client asks for
+    JSON the raw audio bytes are returned with `X-Kiapi-File-Id` / `X-Kiapi-Job-Id`
+    headers — `curl -o out.wav` just works. With `Accept: application/json` (or
+    async) the Job JSON is returned, whose `result` follows TrackResponse.
+
+    Async returns 202 immediately; poll GET /v1/jobs/{job_id} and fetch the
+    artifact via GET /v1/files/{file_id}.
+    """
+    _validate_model(req.model)
+    cap = settings_manager.get_settings().max_duration
+    if req.duration > cap:
+        raise HTTPException(
+            status_code=422, detail=f"duration {req.duration}s exceeds max {cap}s"
+        )
+    return await submit_and_maybe_wait(
+        ctx,
+        worker,
+        type="acestep.generate",
+        params=req.gen_params() | {"model": req.model},
+        thunk=lambda: handle_generate(ctx, req),
+        mode=req.mode,
+        accept=accept,
+    )
+
+
+@router.post(
+    "/v1/audio/acestep/cover",
+    responses=build_job_responses("audio/wav", result_model=TrackResponse),
+)
+async def cover_music(
+    req: CoverRequest,
+    accept: str | None = Depends(get_accept),
+    ctx: AppContext = Depends(get_ctx),
+    worker: Worker = Depends(get_worker),
+) -> Response:
+    """Re-style an existing track while preserving its structure (cover).
+
+    Requires a `source` track and a `prompt` describing the target style;
+    `strength` (0..1) trades creative freedom against faithfulness to the source.
+    To regenerate only a time range use `/repaint`; to make a song from scratch
+    use `/generate`. The same endpoint serves both `sync` and `async` via `mode`.
+
+    Sync content negotiation and the TrackResponse `result` shape match
+    `/v1/audio/acestep/generate` (one WAV artifact; `result.src` references the
+    source file_id).
+    """
+    _validate_model(req.model)
+    return await submit_and_maybe_wait(
+        ctx,
+        worker,
+        type="acestep.cover",
+        params=req.gen_params() | {"model": req.model},
+        thunk=lambda: handle_cover(ctx, req),
+        mode=req.mode,
+        accept=accept,
+    )
+
+
+@router.post(
+    "/v1/audio/acestep/repaint",
+    responses=build_job_responses("audio/wav", result_model=TrackResponse),
+)
+async def repaint_music(
+    req: RepaintRequest,
+    accept: str | None = Depends(get_accept),
+    ctx: AppContext = Depends(get_ctx),
+    worker: Worker = Depends(get_worker),
+) -> Response:
+    """Regenerate one time range of an existing track (repaint).
+
+    Requires a `source` track, a `prompt` for the section's style, and a
+    `start`/`end` window (`end=-1` runs to the end of the track); `strength`
+    (0..1) controls how aggressively that window is regenerated while it blends
+    into the rest. To restyle the whole track use `/cover`. The same endpoint
+    serves both `sync` and `async` via `mode`.
+
+    Sync content negotiation and the TrackResponse `result` shape match
+    `/v1/audio/acestep/generate` (one WAV artifact; `result.src` references the
+    source file_id).
+    """
+    _validate_model(req.model)
+    return await submit_and_maybe_wait(
+        ctx,
+        worker,
+        type="acestep.repaint",
+        params=req.gen_params() | {"model": req.model},
+        thunk=lambda: handle_repaint(ctx, req),
+        mode=req.mode,
+        accept=accept,
+    )
+
+
+@router.post(
+    "/v1/audio/acestep/extract",
+    responses=build_job_responses("audio/wav", result_model=ExtractResponse),
+)
+async def extract_music(
+    req: ExtractRequest,
+    accept: str | None = Depends(get_accept),
+    ctx: AppContext = Depends(get_ctx),
+    worker: Worker = Depends(get_worker),
+) -> Response:
+    """Separate a track into stems / source separation (extract).
+
+    Requires a `source` track and a list of `targets` (e.g. vocals / drums / bass
+    / other). One job produces one WAV stem per target, so `artifacts` holds a
+    file_id per target. The same endpoint serves both `sync` and `async` via
+    `mode`.
+
+    Unlike the other operations this is a multi-artifact job, so sync always
+    returns the Job JSON (no raw-bytes shortcut). The `result` follows
+    ExtractResponse, whose `stems[]` carry one file_id each. Fetch each via
+    GET /v1/files/{file_id}.
+    """
+    _validate_model(req.model)
+    return await submit_and_maybe_wait(
+        ctx,
+        worker,
+        type="acestep.extract",
+        params=req.gen_params() | {"model": req.model},
+        thunk=lambda: handle_extract(ctx, req),
+        mode=req.mode,
+        accept=accept,
+    )
+
+
+register_capability_endpoints(router, name="acestep", base_path="/v1/audio/acestep")

kiapi/api/audio/audiogen/_views/audio_response.py

@@ -0,0 +1,46 @@
+"""``/v1/audio/audiogen/generate`` result payload (the Job ``result``).
+
+Mirrors the dict returned by ``capabilities/audiogen/_models/audiogen.run`` so the
+produced WAV is self-describing in OpenAPI. It is an output-side projection of
+the model result, so it lives under ``api/audio/audiogen/_views``.
+
+``AudioResponse`` 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.")
+
+
+class AudioResponse(BaseModel):
+    """Capability-specific ``result`` for a succeeded AudioGen generate job."""
+
+    file_id: str = Field(
+        description=(
+            "Files-API id of the produced WAV. 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."
+        )
+    )
+    audio_bytes: int = Field(description="Size of the produced WAV in bytes.")
+
+    model: str = Field(description="Resolved AudioGen variant that produced the WAV.")
+    prompt: str = Field(description="Prompt used to generate the sound effect.")
+    duration_s: float = Field(
+        description="Actual WAV duration in seconds, measured from the output samples."
+    )
+    sample_rate: int = Field(
+        description="Output sample rate in Hz. AudioGen-medium produces 16 kHz mono WAV."
+    )
+
+    params: dict[str, Any] = Field(
+        description=(
+            "Resolved parameters actually used for the run (model, prompt, duration, "
+            "seed, top_k, top_p, temperature, cfg_coef), so the result is reproducible."
+        )
+    )
+    timings: _Timings = Field(description="kiapi extension: server-side timing.")

kiapi/api/audio/audiogen/router.py

@@ -0,0 +1,77 @@
+"""Sound-effect API: ``POST /v1/audio/audiogen/generate`` (sync or async via ``mode``)."""
+
+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.audiogen 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.audio_response import AudioResponse
+
+router = APIRouter(dependencies=REQUIRE_AUTH)
+
+
+@router.post(
+    "/v1/audio/audiogen/generate",
+    responses=build_job_responses("audio/wav", result_model=AudioResponse),
+)
+async def generate_se(
+    req: GenerateRequest,
+    accept: str | None = Depends(get_accept),
+    ctx: AppContext = Depends(get_ctx),
+    worker: Worker = Depends(get_worker),
+) -> Response:
+    """Generate a short non-musical sound effect from a text prompt.
+
+    Takes no source audio: `prompt` describes the sound event, environment, and
+    texture, while `duration` and the sampling knobs shape the clip. AudioGen is
+    for SFX/ambient audio such as rain, footsteps, impacts, machinery, or room
+    tone; use `/v1/audio/acestep/generate` for music. The same endpoint serves
+    both `sync` and `async` via `mode`.
+
+    Sync content negotiation: one WAV is produced, so unless the client asks for
+    JSON the raw audio bytes are returned with `X-Kiapi-File-Id` / `X-Kiapi-Job-Id`
+    headers. With `Accept: application/json` (or async) the Job JSON is returned,
+    whose `result` follows AudioResponse.
+
+    Async returns 202 immediately; poll GET /v1/jobs/{job_id} and fetch the
+    artifact via GET /v1/files/{file_id}.
+    """
+    # Validate up front so async callers also get immediate 400/422.
+    try:
+        spec = model_registry.resolve("audiogen", 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
+
+    return await submit_and_maybe_wait(
+        ctx,
+        worker,
+        type="audiogen",
+        params=req.gen_params() | {"model": spec.name, "mode": req.mode},
+        thunk=lambda: handle_generate(ctx, req),
+        mode=req.mode,
+        accept=accept,
+    )
+
+
+register_capability_endpoints(router, name="audiogen", base_path="/v1/audio/audiogen")

kiapi/api/chat/_views/chat_completion_response.py

@@ -0,0 +1,71 @@
+"""OpenAI-compatible ``chat.completion`` response model.
+
+Mirrors the dict shaped by ``capabilities/chat/_operations/format_response`` so
+the non-streaming response 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/chat/_views``. Streaming responses use a separate ``chat.completion.chunk``
+shape and are documented on the endpoint.
+
+``ChatCompletionResponse`` is the sole public element; the nested pieces are
+private since nothing references them on their own.
+"""
+
+from pydantic import BaseModel, Field
+
+
+class _FunctionCall(BaseModel):
+    name: str = Field(description="Called function name, matching a request tool.")
+    arguments: str = Field(
+        description="Call arguments as a JSON-encoded string (OpenAI convention)."
+    )
+
+
+class _ToolCall(BaseModel):
+    id: str = Field(description="Unique id for this tool call, e.g. `call_<hex>`.")
+    type: str = Field(default="function", description="Always `function`.")
+    function: _FunctionCall = Field(description="The function and its arguments.")
+
+
+class _ResponseMessage(BaseModel):
+    role: str = Field(default="assistant", description="Always `assistant`.")
+    content: str | None = Field(
+        default=None,
+        description=(
+            "Assistant text. Null when the turn is only tool calls; may hold the "
+            "natural-language preamble that preceded a tool call."
+        ),
+    )
+    tool_calls: list[_ToolCall] | None = Field(
+        default=None,
+        description="Tool calls the model requested, when any.",
+    )
+
+
+class _Choice(BaseModel):
+    index: int = Field(description="Choice index (always 0; kiapi returns one).")
+    message: _ResponseMessage = Field(description="The generated assistant message.")
+    finish_reason: str = Field(
+        description="`stop` for normal completion, `tool_calls` when tools were called."
+    )
+
+
+class _Usage(BaseModel):
+    prompt_tokens: int = Field(description="Tokens in the prompt.")
+    completion_tokens: int = Field(description="Tokens generated.")
+    total_tokens: int = Field(description="Sum of prompt and completion tokens.")
+
+
+class _Timings(BaseModel):
+    total_s: float = Field(description="Wall-clock generation time in seconds.")
+
+
+class ChatCompletionResponse(BaseModel):
+    id: str = Field(description="Completion id, e.g. `chatcmpl-<hex>`.")
+    object: str = Field(
+        default="chat.completion", description="Always `chat.completion`."
+    )
+    created: int = Field(description="Unix timestamp (seconds) when created.")
+    model: str = Field(description="Resolved model name that answered.")
+    choices: list[_Choice] = Field(description="Generated choices (one).")
+    usage: _Usage = Field(description="Token accounting for the request.")
+    timings: _Timings = Field(description="kiapi extension: server-side timing.")