kiapi 0.1.0__py3-none-any.whl

kiapi/capabilities/ideogram4/README.md

@@ -0,0 +1,219 @@
+# ideogram4
+
+**English** | [日本語](README.ja.md)
+
+[mflux Ideogram 4 FP8](https://github.com/filipstrand/mflux/blob/main/src/mflux/models/ideogram4/README.md) provides typography-friendly text image generation functionality.
+Ideogram 4 is a model suitable for situations where you want to handle text, signs, labels, logo-like text, etc. in images.
+kiapi only exposes txt2img and saves the generated results as Files API artifacts.
+
+- **generate**:
+  - Generate images from Ideogram 4's JSON caption or regular text prompts
+
+
+## API
+
+| Endpoint | Name | Description |
+|---|---|---|
+| `POST /v1/image/ideogram4/generate` | Image generation | Generate one image from JSON caption or text prompt. |
+| `GET /v1/image/ideogram4/models` | Model list | Returns a list of available models. |
+| `GET /v1/image/ideogram4/openapi.json` | OpenAPI | Returns detailed input/output specifications, prompt shapes, constraints, and TIPS. |
+
+## API Docs
+
+- [OpenAPI JSON](https://kiarina.github.io/kiapi/v1/image/ideogram4/openapi.json)
+- [Swagger UI](https://kiarina.github.io/kiapi/v1/image/ideogram4/docs.html)
+- [ReDoc](https://kiarina.github.io/kiapi/v1/image/ideogram4/redoc.html)
+
+## Dependencies
+
+| Package | License | Description |
+|---|---|---|
+| [mflux](https://github.com/filipstrand/mflux) | MIT | Uses the MLX implementation of Ideogram 4 FP8. |
+
+## Models
+
+| Model | License | Terms | Size | Description |
+|---|---|---|---:|---|
+| [ideogram-ai/ideogram-4-fp8](https://huggingface.co/ideogram-ai/ideogram-4-fp8) | Ideogram license (non-commercial) | Required | 27.5 GB | `fp8` (default). Hugging Face's gated repo. Default is `1024x1024`, `preset: V4_DEFAULT_20`, `quantize: null`. |
+
+## Notes
+
+- **Hugging Face's gated repo**:
+  The model weights are obtained from `ideogram-ai/ideogram-4-fp8`.
+  Before running it for the first time, you need to approve access on Hugging Face and authenticate in the local environment.
+- **JSON caption recommended**:
+  Although it accepts regular string prompts, Ideogram 4 performs best with structured JSON captions.
+  If you want to target the text in the image, set `type: "text"` to `compositional_deconstruction.elements[]`,
+  The basics are to include `bbox`, `text`, and `desc`.
+- **bbox coordinates**:
+  `bbox` in JSON caption has the format `[x1, y1, x2, y2]`.
+  Ideogram 4's prompting guide treats them as normalized layout coordinates from 0-1000.
+- **Preset**:
+  `preset` is one of `V4_DEFAULT_20` / `V4_QUALITY_48` / `V4_TURBO_12`.
+  Default is `V4_DEFAULT_20`. If quality is your priority, use `V4_QUALITY_48`, and if speed is your priority, use `V4_TURBO_12`.
+- **Image size**:
+  `width` / `height` are multiples of 16, defaulting to `1024x1024`.
+  The default upper limit is `2048x2048` and the lower limit is `256x256`.
+- **quantize override**:
+  `quantize` is `3` / `4` / `5` / `6` / `8` / `null`.
+  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` / `jpeg` / `webp`. Default is `png`.
+  `quality` is the encoding quality of `jpeg` / `webp`, `1..100`, default is `90`.
+- **Safety Filter**:
+  Some prompts may return `Image blocked by safety filter` images, including false positives.
+  kiapi does not make this an HTTP error, but instead stores the returned image as an artifact.
+- **Not supported**:
+  We do not publish image-to-image, image editing, LoRA learning, hosted Magic Prompt API, or checkpoint layouts other than FP8.
+
+## Prompt JSON
+
+This is the recommended basic form of JSON caption.
+```json
+{
+  "high_level_description": "Overall scene description.",
+  "style_description": "Optional style, lighting, medium, and color guidance.",
+  "compositional_deconstruction": {
+    "background": "Background and layout description.",
+    "elements": [
+      {
+        "type": "text",
+        "bbox": [360, 420, 640, 560],
+        "text": "HELLO",
+        "desc": "Crisp black uppercase letters centered on the sign."
+      }
+    ]
+  }
+}
+```
+For detailed instructions, please also refer to [Ideogram 4 prompting guide](https://github.com/ideogram-oss/ideogram4/blob/main/docs/prompting.md).
+
+## Quickstart
+
+### generate - Generate an image with text using JSON caption
+
+Returns Job JSON:
+```bash
+PARAMS=$(jq -n '{
+  model: "fp8",
+  mode: "sync",
+  prompt: {
+    high_level_description: "A clean studio photo of a white notebook with the word MFLUX on the cover.",
+    style_description: "Minimal product photography, soft window light, realistic paper texture.",
+    compositional_deconstruction: {
+      background: "Warm wooden desk with soft shadows.",
+      elements: [
+        {
+          type: "text",
+          bbox: [390, 430, 610, 560],
+          text: "MFLUX",
+          desc: "Crisp black uppercase letters centered on the notebook cover."
+        }
+      ]
+    }
+  },
+  width: 1024,
+  height: 1024,
+  preset: "V4_DEFAULT_20",
+  seed: 42
+}')
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/ideogram4/generate \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" |
+jq .
+```
+Save only the image:
+```bash
+PARAMS=$(jq -n '{
+  model: "fp8",
+  mode: "sync",
+  prompt: {
+    high_level_description: "A square cafe poster with the large word KIASA.",
+    style_description: "Clean editorial poster, warm morning colors, sharp typography.",
+    compositional_deconstruction: {
+      background: "Cream wall with a simple coffee cup illustration.",
+      elements: [
+        {
+          type: "text",
+          bbox: [260, 320, 740, 500],
+          text: "KIASA",
+          desc: "Large bold serif letters, perfectly readable."
+        }
+      ]
+    }
+  },
+  width: 1024,
+  height: 1024,
+  seed: 7
+}')
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/ideogram4/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o ideogram4.png
+```
+### generate - plain text
+```bash
+PARAMS=$(jq -n '{
+  mode: "sync",
+  prompt: "A vintage travel poster for TOKYO, the word TOKYO is large and perfectly readable, bright flat colors",
+  width: 768,
+  height: 1024,
+  preset: "V4_QUALITY_48",
+  seed: 11
+}')
+
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/ideogram4/generate \
+-H 'Content-Type: application/json' \
+--data-binary "$PARAMS" \
+-o ideogram4-text.png
+```
+
+### async
+
+```bash
+PARAMS=$(jq -n '{
+  mode: "async",
+  prompt: {
+    high_level_description: "A clean packaging mockup for a tea box labeled HIKARI.",
+    compositional_deconstruction: {
+      background: "Soft green studio backdrop.",
+      elements: [
+        {
+          type: "text",
+          bbox: [330, 360, 670, 520],
+          text: "HIKARI",
+          desc: "Elegant uppercase letters printed on the front of the box."
+        }
+      ]
+    }
+  },
+  width: 1024,
+  height: 1024,
+  preset: "V4_TURBO_12"
+}')
+
+JOB=$(curl -sS -X POST http://localhost:${PORT:-8000}/v1/image/ideogram4/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 .
+```
+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 ideogram4-async.png
+```
+### Model list and help
+```bash
+curl -sS http://localhost:${PORT:-8000}/v1/image/ideogram4/models | jq .
+curl -sS http://localhost:${PORT:-8000}/v1/image/ideogram4/openapi.json | jq .
+```

kiapi/capabilities/ideogram4/__init__.py

@@ -0,0 +1,24 @@
+"""ideogram4 family — Ideogram 4 FP8 text-to-image via mflux.
+
+Endpoint: ``POST /v1/image/ideogram4/generate``. Ideogram 4 is typography-
+focused txt2img. It accepts plain text, but structured JSON captions are the
+preferred prompt form and are surfaced in help. A ``quantize`` override runs on
+a one-off transient model; otherwise the resident model is used.
+"""
+
+from kiapi.capabilities import ValidationError
+
+from ._helpers.register import register
+from ._helpers.validate_generate import validate_generate
+from ._operations.handle_generate import handle_generate
+from ._settings import settings_manager
+from ._views.generate_request import GenerateRequest
+
+__all__ = [
+    "GenerateRequest",  # ._views
+    "ValidationError",  # kiapi.capabilities
+    "handle_generate",  # ._operations
+    "register",  # ._helpers
+    "settings_manager",  # ._settings
+    "validate_generate",  # ._helpers
+]

kiapi/capabilities/ideogram4/_constants/description.py

@@ -0,0 +1,65 @@
+DESCRIPTION = """Typography-focused text-to-image generation (Ideogram 4 FP8 via mflux).
+
+One operation: `/generate` (text-to-image). Ideogram 4 excels at rendering legible
+text and typography. There is no image-to-image, no training, and no hosted Magic
+Prompt API.
+
+## Upstream docs
+- [mflux — Ideogram 4](https://github.com/filipstrand/mflux/blob/main/src/mflux/models/ideogram4/README.md) — the MLX engine kiapi runs
+- [ideogram-ai/ideogram-4-fp8](https://huggingface.co/ideogram-ai/ideogram-4-fp8) — the `fp8` weights (gated)
+
+## Models
+- **fp8** (default) — `ideogram-ai/ideogram-4-fp8`. The only variant; discover it
+  at `GET /v1/image/ideogram4/models`. The Hugging Face repo is **gated**: approve
+  access to `ideogram-ai/ideogram-4-fp8` before the first download. Non-FP8
+  checkpoint layouts are not supported.
+
+## Prompting (JSON caption preferred)
+Ideogram 4 follows a **structured JSON caption** far better than plain text,
+especially for laying out and spelling words. Plain text is accepted but usually
+weaker. See the official prompt guide for the full caption schema, key-order
+rules, bbox layout, and color-palette conditioning:
+- [Ideogram 4 prompting guide](https://github.com/ideogram-oss/ideogram-4/blob/main/docs/prompting.md)
+
+A caption looks like:
+
+```json
+{
+  "high_level_description": "A clean studio photo of a white notebook with the word MFLUX on the cover.",
+  "style_description": "Soft daylight, shallow depth of field, product-photography aesthetic.",
+  "compositional_deconstruction": {
+    "background": "Warm wooden desk with soft window light.",
+    "elements": [
+      {
+        "type": "text",
+        "bbox": [420, 420, 620, 560],
+        "text": "MFLUX",
+        "desc": "Crisp black uppercase letters centered on the notebook."
+      }
+    ]
+  }
+}
+```
+
+- `bbox` is `[x1, y1, x2, y2]` in normalized **0-1000** layout coordinates.
+- `type` is `text` (needs a `text` field) or `obj`.
+- Set `strict_caption_validation=true` to fail (400) on mflux caption-schema
+  warnings; `warn_on_caption_issues` (default true) just surfaces them.
+
+## Presets
+`preset` bundles steps + guidance + noise schedule. Trade speed for quality:
+`V4_TURBO_12` (fast, 12 steps) → `V4_DEFAULT_20` (balanced) → `V4_QUALITY_48`
+(best, 48 steps).
+
+## TIPS
+- For a quick image, call `sync` without `Accept: application/json` to get the raw
+  bytes straight back (`curl -o out.png`).
+- `width`/`height` must be multiples of 16 and within 256..2048 (default 1024).
+- First use downloads the gated FP8 weights; run `kiapi activate` ahead of time to
+  avoid a cold-start download on the first request.
+
+## Performance
+- **fp8**: roughly 26-28 GiB peak RSS at 1024x1024 / V4_DEFAULT_20.
+- **first request**: may be much slower if gated weights are still being
+  downloaded from Hugging Face.
+"""

kiapi/capabilities/ideogram4/_helpers/register.py

@@ -0,0 +1,44 @@
+"""Register ideogram4'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 ideogram4
+from .._settings import settings_manager
+
+
+def register() -> None:
+    capability_spec_registry.register(
+        CapabilitySpec(
+            name="ideogram4",
+            domain="image",
+            title="kiapi Ideogram 4 API",
+            summary="Generate images from text prompts with Ideogram 4.",
+            description=DESCRIPTION,
+            openapi_path="/v1/image/ideogram4/openapi.json",
+            docs_path="/v1/image/ideogram4/docs",
+            redoc_path="/v1/image/ideogram4/redoc",
+            path_prefixes=("/v1/image/ideogram4",),
+        )
+    )
+
+    _s = settings_manager.get_settings()
+
+    model_registry.register(
+        ModelSpec(
+            name="fp8",
+            family="ideogram4",
+            domain="image",
+            repo=_s.model_repo,
+            module=ideogram4,
+            weight_gb=26.0,
+            peak_headroom_gb=4.0,
+            framework="mlx",
+            priority=0,
+            aliases=("ideogram4", "ideogram-4", "ideogram-ai/ideogram-4-fp8"),
+            default=True,
+            setup_resources=(HfSnapshotResource(repo=_s.model_repo, disk_gb=27.5),),
+        )
+    )

kiapi/capabilities/ideogram4/_helpers/validate_generate.py

@@ -0,0 +1,31 @@
+from kiapi.capabilities import ValidationError
+
+from .._settings import settings_manager
+from .._views.generate_request import GenerateRequest
+
+_MULTIPLE = 16
+
+
+def validate_generate(req: GenerateRequest) -> 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
+
+    if width < settings.min_width or height < settings.min_height:
+        raise ValidationError(
+            f"width and height must be >= {settings.min_width}x{settings.min_height}"
+        )
+    if width % _MULTIPLE or height % _MULTIPLE:
+        raise ValidationError(f"width and height must be multiples of {_MULTIPLE}")
+    if width > settings.max_width or height > settings.max_height:
+        raise ValidationError(
+            f"size {width}x{height} exceeds the cap {settings.max_width}x{settings.max_height}"
+        )
+
+    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 isinstance(req.prompt, str) and not req.prompt.strip():
+        raise ValidationError("prompt must not be empty")
+    if isinstance(req.prompt, dict) and not req.prompt:
+        raise ValidationError("prompt JSON must not be empty")

kiapi/capabilities/ideogram4/_models/ideogram4.py

@@ -0,0 +1,120 @@
+"""Handler for Ideogram 4 FP8 txt2img via mflux."""
+
+import gc
+import time
+from types import SimpleNamespace
+from typing import Any
+
+from kiapi.capabilities import attach_mflux_progress
+from kiapi.core.file import FileStore
+from kiapi.core.model import ModelSpec
+from kiapi.core.workdir import create_work_dir
+
+from .._views.generate_params import GenerateParams
+
+FEATURES = {"text"}
+
+_SAFETY_FILTER_NOTE = (
+    "Ideogram 4 may return an 'Image blocked by safety filter' image; "
+    "kiapi stores the returned image as-is."
+)
+
+
+def build_model(spec: ModelSpec, *, quantize: int | None) -> Any:
+    from mflux.models.common.config import ModelConfig  # type: ignore
+    from mflux.models.ideogram4 import Ideogram4  # type: ignore
+
+    return Ideogram4(
+        quantize=quantize,
+        model_path=spec.repo,
+        model_config=ModelConfig.ideogram4_fp8(),
+    )
+
+
+def load(spec: ModelSpec) -> SimpleNamespace:
+    from .._settings import settings_manager
+
+    quantize = settings_manager.get_settings().default_quantize
+    model = build_model(spec, quantize=quantize)
+    return SimpleNamespace(model=model, spec=spec, quantize=quantize)
+
+
+def _store_image(
+    image: Any,
+    *,
+    fmt: str,
+    quality: int,
+    files: FileStore,
+    meta: dict[str, Any],
+) -> dict[str, Any]:
+    pil = getattr(image, "image", image)
+    ext = "jpg" if fmt == "jpeg" else fmt
+    tmp_dir = create_work_dir("image/ideogram4")
+    out_path = tmp_dir / f"image.{ext}"
+    save_kwargs: dict[str, Any] = {}
+    if fmt in ("jpeg", "webp"):
+        save_kwargs["quality"] = quality
+    if fmt == "jpeg":
+        pil = pil.convert("RGB")
+    pil.save(out_path, format=fmt.upper(), **save_kwargs)
+    if not out_path.exists():
+        raise RuntimeError("generation finished but no image file was produced")
+    rec = files.put_path(
+        out_path,
+        filename=f"ideogram4_{int(time.time())}.{ext}",
+        content_type=f"image/{fmt}",
+        meta=meta,
+        move=True,
+    )
+    return {"file_id": rec.file_id, "image_bytes": rec.size, **meta}
+
+
+def _generate(model: Any, params: GenerateParams, files: FileStore) -> dict[str, Any]:
+    t0 = time.time()
+    attach_mflux_progress(model)
+    image = model.generate_image(
+        seed=params.seed,
+        prompt=params.prompt,
+        width=params.width,
+        height=params.height,
+        preset=params.preset,
+        strict_caption_validation=params.strict_caption_validation,
+        warn_on_caption_issues=params.warn_on_caption_issues,
+    )
+    total_s = round(time.time() - t0, 2)
+    meta = {
+        "model": params.model,
+        "prompt": params.prompt,
+        "params": params.model_dump(),
+        "width": params.width,
+        "height": params.height,
+        "safety_filter_note": _SAFETY_FILTER_NOTE,
+        "timings": {"total_s": total_s},
+    }
+    return _store_image(
+        image, fmt=params.format, quality=params.quality, files=files, meta=meta
+    )
+
+
+def run_generate(
+    payload: SimpleNamespace, params: GenerateParams, files: FileStore
+) -> dict[str, Any]:
+    return _generate(payload.model, params, files)
+
+
+def run_generate_transient(
+    spec: ModelSpec, params: GenerateParams, files: FileStore
+) -> dict[str, Any]:
+    model = build_model(spec, quantize=params.quantize)
+    try:
+        return _generate(model, params, files)
+    finally:
+        _free(model)
+
+
+def _free(model: Any) -> None:
+    del model
+    gc.collect()
+    import mlx.core as mx
+
+    mx.clear_cache()

kiapi/capabilities/ideogram4/_operations/handle_generate.py

@@ -0,0 +1,30 @@
+"""Ideogram 4 text-to-image service entry (worker-thread thunk body)."""
+
+from kiapi.core.app import AppContext
+from kiapi.core.file import FileID
+from kiapi.core.job import JobResult
+from kiapi.core.model import model_registry
+
+from .._settings import settings_manager
+from .._views.generate_request import GenerateRequest
+from .is_quantize_override import is_quantize_override
+from .resolve_generate_params import resolve_generate_params
+
+
+def handle_generate(
+    ctx: AppContext, req: GenerateRequest
+) -> tuple[JobResult, list[FileID]]:
+    settings = settings_manager.get_settings()
+    spec = model_registry.resolve("ideogram4", req.model)
+    ctx.ensure_model_ready(spec)
+    override = is_quantize_override(settings, req)
+    params = resolve_generate_params(settings, req, variant=spec.name)
+
+    if override:
+        ctx.memory_manager.reserve(spec.weight_gb + spec.peak_headroom_gb)
+        result = spec.module.run_generate_transient(spec, params, ctx.file_store)
+    else:
+        payload = ctx.memory_manager.acquire(spec)
+        result = spec.module.run_generate(payload, params, ctx.file_store)
+
+    return result, [result["file_id"]]

kiapi/capabilities/ideogram4/_operations/is_quantize_override.py

@@ -0,0 +1,12 @@
+"""Decide whether a request's quantize differs from the variant default.
+
+A True result means the resident model (quantized at its default) can't serve the
+request, so ``handle_generate`` runs a one-off transient model instead.
+"""
+
+from .._settings import Ideogram4Settings
+from .._views.generate_request import GenerateRequest
+
+
+def is_quantize_override(settings: Ideogram4Settings, req: GenerateRequest) -> bool:
+    return req.quantize is not None and req.quantize != settings.default_quantize

kiapi/capabilities/ideogram4/_operations/resolve_generate_params.py

@@ -0,0 +1,30 @@
+"""Merge a generate request with settings defaults into the complete GenerateParams."""
+
+import random
+
+from .._settings import Ideogram4Settings
+from .._views.generate_params import GenerateParams
+from .._views.generate_request import GenerateRequest
+
+
+def resolve_generate_params(
+    settings: Ideogram4Settings,
+    req: GenerateRequest,
+    *,
+    variant: str,
+) -> GenerateParams:
+    return GenerateParams(
+        model=variant,
+        prompt=req.prompt,
+        preset=req.preset,
+        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,
+        quantize=req.quantize
+        if req.quantize is not None
+        else settings.default_quantize,
+        strict_caption_validation=req.strict_caption_validation,
+        warn_on_caption_issues=req.warn_on_caption_issues,
+        format=req.format,
+        quality=req.quality,
+    )

kiapi/capabilities/ideogram4/_settings.py

@@ -0,0 +1,89 @@
+"""Ideogram 4 capability defaults + caps, read from ``KIAPI_IDEOGRAM4_`` env vars."""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic_settings_manager import SettingsManager
+
+
+class Ideogram4Settings(BaseSettings):
+    """Settings for the Ideogram 4 model, image sizes, presets, and quantization."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="KIAPI_IDEOGRAM4_",
+        extra="ignore",
+        protected_namespaces=(),
+    )
+
+    model_repo: str = Field(
+        default="ideogram-ai/ideogram-4-fp8",
+        title="Ideogram 4 model repo",
+        description="Hugging Face repo ID for the Ideogram 4 model used for image generation.",
+    )
+
+    # --------------------------------------------------
+    # generate
+    # --------------------------------------------------
+
+    default_width: int = Field(
+        default=1024,
+        title="Default width",
+        description="Output image width in pixels used when a request omits width.",
+    )
+
+    default_height: int = Field(
+        default=1024,
+        title="Default height",
+        description="Output image height in pixels used when a request omits height.",
+    )
+
+    min_width: int = Field(
+        default=256,
+        title="Minimum width",
+        description="Lower pixel limit for the output image width accepted in a request.",
+    )
+
+    min_height: int = Field(
+        default=256,
+        title="Minimum height",
+        description="Lower pixel limit for the output image height accepted in a request.",
+    )
+
+    max_width: int = Field(
+        default=2048,
+        title="Maximum width",
+        description="Upper pixel limit for the output image width accepted in a request.",
+    )
+
+    max_height: int = Field(
+        default=2048,
+        title="Maximum height",
+        description="Upper pixel limit for the output image height accepted in a request.",
+    )
+
+    default_preset: str = Field(
+        default="V4_DEFAULT_20",
+        title="Default preset",
+        description=(
+            "Ideogram 4 preset name used when a request omits preset.\n"
+            "The value must be included in presets."
+        ),
+    )
+
+    presets: tuple[str, ...] = Field(
+        default=("V4_DEFAULT_20", "V4_QUALITY_48", "V4_TURBO_12"),
+        title="Available presets",
+        description="List of Ideogram 4 preset names accepted by the API.",
+    )
+
+    default_quantize: int | None = Field(
+        default=None,
+        title="Default quantization bits",
+        description=(
+            "Default quantization bit count used when loading the Ideogram 4 model.\n"
+            "When None, the model repo's default precision is used. A numeric "
+            "value quantizes to that bit count."
+        ),
+    )
+
+
+settings_manager = SettingsManager(Ideogram4Settings)