Add Character Studio app, registry, requirements, docs (#1)

- Add Character Studio app, registry, requirements, docs (5a7069b0de1924567bb47c3a83a5cf6319c6b401)


Co-authored-by: pormungtailaw <pormungtai@users.noreply.huggingface.co>

README.md

@@ -1,15 +1,64 @@
 ---
 title: Character Studio
-emoji: 🚀
-colorFrom: red
-colorTo: gray
+emoji: 🎭
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.15.2
-python_version: '3.12'
+sdk_version: 5.9.1
 app_file: app.py
 pinned: false
 license: apache-2.0
-short_description: Multi-model character generator (SD1.5 / SDXL / FLUX) on Zer
+short_description: Multi-model character generator on ZeroGPU
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🎭 Character Studio
+
+A Hugging Face **ZeroGPU** Space that bundles many image models behind one UI for
+character generation. Pick a model from an **editable registry**, type a prompt,
+optionally drop a **reference image**, and generate.
+
+## Features
+- **Editable model registry** — add / remove models by editing `models.json`, no code change.
+- **Multiple base families** — SD1.5, SDXL, FLUX. Each model declares its own `base`.
+- **Multiple input modes** — `txt2img`, `img2img`, `IP-Adapter` (style/subject), `Face identity` (FaceID).
+- **Custom sources** — HF repos, full `.safetensors` checkpoints, and Civitai download URLs.
+
+## Hardware
+Set the Space hardware to **ZeroGPU** (Nvidia, dynamic). Free tier works; pipelines
+are cached on CPU and moved to GPU only during a generation call.
+
+## Secrets / environment variables (Settings → Variables and secrets)
+- `HF_TOKEN` — needed only for **gated** models (e.g. FLUX.1-dev). Optional otherwise.
+- `CIVITAI_TOKEN` — needed only if a registry entry pulls from a Civitai download URL.
+
+## Adding / removing models
+See **README_TH.md** for the full Thai field guide. Quick version: each entry in
+`models.json` looks like:
+
+```json
+{
+  "id": "my-model",
+  "label": "My Model (SDXL)",
+  "base": "sdxl",
+  "type": "checkpoint",
+  "repo_id": "author/repo-on-hf",
+  "single_file_url": null,
+  "default_steps": 30,
+  "default_guidance": 6.0,
+  "enabled": true
+}
+```
+
+For a LoRA, set `"type": "lora"`, keep `repo_id` as the **base checkpoint**, and add
+either `lora_repo_id` (+ optional `lora_weight_name`) or `lora_url` (Civitai), plus
+`lora_scale`. After editing, click **🔄 Reload models** in the UI.
+
+## Notes
+- IP-Adapter and Face identity modes are available for **SD1.5 / SDXL** only; FLUX
+  supports `txt2img` / `img2img`.
+- Face identity uses InsightFace (`buffalo_l`) + IP-Adapter-FaceID and needs a clear face.
+- Only one large model is held in memory at a time; switching models reloads.
+
+## Responsible use
+This tool is for original character art and authorized creative work. Do not use the
+Face identity feature to depict real people without their consent.

README_TH.md

@@ -0,0 +1,120 @@
+# 🎭 Character Studio — คู่มือภาษาไทย
+
+Space รวมโมเดลสร้างตัวละครหลายตัวไว้ใน UI เดียว ทำงานบน **ZeroGPU**
+เลือกโมเดลจากรายการ → พิมพ์ prompt → (ถ้าต้องการ) ใส่รูปต้นแบบ → กด Generate
+
+---
+
+## 1) วิธีนำขึ้น Hugging Face
+
+1. สร้าง Space ใหม่: https://huggingface.co/new-space
+   - **SDK = Gradio**
+   - **Hardware = ZeroGPU** (Nvidia, dynamic)
+2. อัปโหลดไฟล์ทั้งหมดในโฟลเดอร์นี้ (`app.py`, `pipeline_manager.py`, `models.json`,
+   `requirements.txt`, `README.md`) ขึ้นไปที่ root ของ Space
+   - ผ่านเว็บ (ลากวาง) หรือผ่าน git:
+     ```bash
+     git clone https://huggingface.co/spaces/<user>/<space-name>
+     # คัดลอกไฟล์ในโฟลเดอร์นี้เข้าไป แล้ว
+     git add . && git commit -m "init character studio" && git push
+     ```
+3. ไปที่ **Settings → Variables and secrets** ใส่ค่า (เท่าที่จำเป็น):
+   - `HF_TOKEN` — เฉพาะโมเดล gated เช่น FLUX.1-dev
+   - `CIVITAI_TOKEN` — เฉพาะเมื่อโหลดจากลิงก์ Civitai
+
+---
+
+## 2) เพิ่ม / ลบ / ปิดโมเดล (แก้ `models.json` อย่างเดียว)
+
+แก้ไฟล์ `models.json` แล้วกดปุ่ม **🔄 Reload models** ใน UI (หรือ restart Space)
+
+### โครงสร้างแต่ละโมเดล
+
+| field | ความหมาย |
+|---|---|
+| `id` | รหัสไม่ซ้ำ (อังกฤษ-ขีดกลาง) |
+| `label` | ชื่อที่โชว์ใน UI |
+| `base` | `"sd15"` / `"sdxl"` / `"flux"` — **สำคัญมาก** กำหนดว่าโหมดไหนใช้ได้ |
+| `type` | `"checkpoint"` (โมเดลเต็ม) หรือ `"lora"` |
+| `repo_id` | repo บน HF (สำหรับ checkpoint) หรือ **base checkpoint** (สำหรับ lora) |
+| `single_file_url` | ลิงก์ `.safetensors` โดยตรง เช่น Civitai (ใช้แทน repo_id ได้) |
+| `lora_repo_id` / `lora_weight_name` | สำหรับ LoRA ที่อยู่บน HF |
+| `lora_url` | สำหรับ LoRA จาก Civitai (ลิงก์ download) |
+| `lora_scale` | น้ำหนัก LoRA เช่น 0.8 |
+| `trigger` | คำ trigger ที่จะเติมหน้า prompt อัตโนมัติ |
+| `recommended_prompt` | prompt ตัวอย่าง (โชว์เป็น placeholder) |
+| `negative_prompt` | negative เริ่มต้น |
+| `default_steps` / `default_guidance` | ค่าเริ่มต้นเวลาเลือกโมเดลนี้ |
+| `enabled` | `true`/`false` ปิดชั่วคราวได้โดยไม่ต้องลบ |
+
+### ตัวอย่าง — checkpoint จาก Civitai (SD1.5)
+```json
+{
+  "id": "asian-realistic-v6",
+  "label": "AsianRealistic SDLife V6 (SD1.5)",
+  "base": "sd15",
+  "type": "checkpoint",
+  "repo_id": null,
+  "single_file_url": "https://civitai.com/api/download/models/130072",
+  "default_steps": 28,
+  "default_guidance": 6.5,
+  "enabled": true
+}
+```
+> ต้องใส่ `CIVITAI_TOKEN` ใน Secrets ด้วย
+
+### ตัวอย่าง — LoRA จาก Civitai (วางบน base SD1.5)
+```json
+{
+  "id": "asian-girls-face",
+  "label": "Asian Girls Face (LoRA)",
+  "base": "sd15",
+  "type": "lora",
+  "repo_id": "stable-diffusion-v1-5/stable-diffusion-v1-5",
+  "lora_url": "https://civitai.com/api/download/models/67980",
+  "lora_scale": 0.8,
+  "enabled": true
+}
+```
+
+### ตัวอย่าง — โมเดลบน HF (SDXL)
+```json
+{
+  "id": "my-sdxl",
+  "label": "My SDXL model",
+  "base": "sdxl",
+  "type": "checkpoint",
+  "repo_id": "author/my-sdxl-repo",
+  "default_steps": 30,
+  "default_guidance": 6.0,
+  "enabled": true
+}
+```
+
+**ลบโมเดล** = ลบ block นั้นออกจาก array `models` หรือตั้ง `"enabled": false`
+
+---
+
+## 3) โหมดรูปต้นแบบ (Input mode)
+
+| โหมด | ทำอะไร | ใช้กับ base |
+|---|---|---|
+| Text → Image | สร้างจาก prompt อย่างเดียว | ทุก base |
+| Image → Image | แปลงรูปเดิม (ปรับ denoise) | ทุก base |
+| IP-Adapter | ดึงสไตล์/องค์ประกอบจากรูป | sd15, sdxl |
+| Face identity | ล็อกใบหน้าจากรูปต้นแบบ (FaceID) | sd15, sdxl |
+
+> FLUX รองรับเฉพาะ txt2img / img2img (IP-Adapter/FaceID ของ FLUX ยังไม่รวมในเวอร์ชันนี้)
+
+---
+
+## 4) ข้อควรรู้เรื่อง ZeroGPU
+- โมเดลใหญ่จะถูกเก็บทีละตัว สลับโมเดล = โหลดใหม่ (ครั้งแรกช้าหน่อย)
+- หนึ่งครั้ง generate จำกัดเวลา GPU ~120 วินาที (ปรับใน `@spaces.GPU(duration=...)`)
+- โมเดล Civitai/checkpoint เต็มก้อนใหญ่ ดาวน์โหลดครั้งแรกใช้เวลา — ใจเย็น
+
+---
+
+## 5) การใช้งานอย่างรับผิดชอบ
+เครื่องมือนี้สำหรับงานสร้างสรรค์ตัวละครต้นฉบับ/งานที่ได้รับอนุญาต
+**อย่าใช้โหมด Face identity สร้างภาพบุคคลจริงโดยไม่ได้รับความยินยอม**

app.py

@@ -0,0 +1,177 @@
+"""
+Character Studio — a ZeroGPU Hugging Face Space.
+
+A multi-model character generator: pick a model from an editable registry,
+type a prompt, optionally drop a reference image, and generate. Supports
+SD1.5 / SDXL / FLUX bases and txt2img / img2img / IP-Adapter / FaceID modes.
+
+Add or remove models by editing models.json (no code change needed), then
+click "🔄 Reload models" or restart the Space.
+"""
+
+import random
+import traceback
+
+import spaces  # must be imported before torch on ZeroGPU
+import gradio as gr
+
+import pipeline_manager as pm
+
+MAX_SEED = 2**31 - 1
+
+
+# ---------------------------------------------------------------------------
+# Registry helpers
+# ---------------------------------------------------------------------------
+def load_models():
+    return pm.load_registry()
+
+
+MODELS = load_models()
+
+
+def model_choices(models):
+    return [(m["label"], m["id"]) for m in models]
+
+
+def modes_for(models, model_id):
+    m = pm.get_model(models, model_id)
+    if not m:
+        return [("Text → Image", "txt2img")]
+    return [(pm.MODE_LABELS[k], k) for k in pm.SUPPORTED_MODES[m["base"]]]
+
+
+# ---------------------------------------------------------------------------
+# GPU generation
+# ---------------------------------------------------------------------------
+@spaces.GPU(duration=120)
+def generate(model_id, mode, prompt, negative_prompt, ref_image,
+             steps, guidance, denoise, ip_scale, width, height, seed, randomize):
+    models = load_models()
+    cfg = pm.get_model(models, model_id)
+    if cfg is None:
+        raise gr.Error("ไม่พบโมเดลที่เลือก โปรด Reload models / Selected model not found.")
+
+    if randomize or seed is None or int(seed) < 0:
+        seed = random.randint(0, MAX_SEED)
+
+    try:
+        img = pm.run_generation(
+            cfg=cfg, mode=mode, prompt=prompt, negative_prompt=negative_prompt,
+            ref_image=ref_image, steps=steps, guidance=guidance, denoise=denoise,
+            ip_scale=ip_scale, width=width, height=height, seed=seed,
+        )
+    except Exception as e:
+        traceback.print_exc()
+        raise gr.Error(str(e))
+
+    status = f"✅ {cfg['label']} · {pm.MODE_LABELS.get(mode, mode)} · seed {seed}"
+    return img, seed, status
+
+
+# ---------------------------------------------------------------------------
+# UI callbacks
+# ---------------------------------------------------------------------------
+def on_model_change(model_id):
+    models = load_models()
+    cfg = pm.get_model(models, model_id)
+    if not cfg:
+        return gr.update(), gr.update(), gr.update(), gr.update(), gr.update()
+    choices = modes_for(models, model_id)
+    return (
+        gr.update(choices=choices, value=choices[0][1]),         # mode radio
+        gr.update(placeholder=cfg.get("recommended_prompt", "")),  # prompt
+        gr.update(value=cfg.get("negative_prompt", "")),          # negative
+        gr.update(value=cfg.get("default_steps", 28)),            # steps
+        gr.update(value=cfg.get("default_guidance", 6.0)),        # guidance
+    )
+
+
+def reload_registry():
+    global MODELS
+    MODELS = load_models()
+    choices = model_choices(MODELS)
+    first = choices[0][1] if choices else None
+    return gr.update(choices=choices, value=first), f"🔄 โหลดแล้ว {len(MODELS)} โมเดล"
+
+
+# ---------------------------------------------------------------------------
+# Layout (mirrors the FLUX LoRA DLC reference UI)
+# ---------------------------------------------------------------------------
+CSS = """
+#gen-btn {height: 100%; font-size: 1.3rem; font-weight: 700;}
+.card {border-radius: 14px;}
+footer {visibility: hidden;}
+"""
+
+with gr.Blocks(css=CSS, theme=gr.themes.Soft(primary_hue="blue"),
+               title="Character Studio") as demo:
+    gr.Markdown("## 🎭 Character Studio — multi-model character generator (ZeroGPU)")
+
+    with gr.Row():
+        prompt = gr.Textbox(
+            label="Edit Prompt", lines=2, scale=4,
+            placeholder="✦ เลือกโมเดลแล้วพิมพ์ prompt / Choose a model and type the prompt",
+        )
+        gen_btn = gr.Button("Generate", variant="primary", scale=1, elem_id="gen-btn")
+
+    with gr.Row(equal_height=False):
+        # ---- left: model picker ----
+        with gr.Column(scale=1):
+            with gr.Group():
+                gr.Markdown("### 🧩 เลือกโมเดล / Models")
+                model_radio = gr.Radio(
+                    choices=model_choices(MODELS),
+                    value=MODELS[0]["id"] if MODELS else None,
+                    label=None, container=False,
+                )
+                reload_btn = gr.Button("🔄 Reload models", size="sm")
+                reload_status = gr.Markdown("")
+
+            mode_radio = gr.Radio(
+                choices=modes_for(MODELS, MODELS[0]["id"]) if MODELS else [],
+                value="txt2img",
+                label="โหม��รูปต้นแบบ / Input mode",
+            )
+
+        # ---- right: output ----
+        with gr.Column(scale=1):
+            output = gr.Image(label="Generated Image", height=560, elem_classes="card")
+            status = gr.Markdown("")
+
+    # ---- advanced ----
+    with gr.Accordion("Advanced Settings", open=False):
+        with gr.Row():
+            with gr.Column():
+                ref_image = gr.Image(label="Input image (รูปต้นแบบ)", type="pil", height=240)
+                ip_scale = gr.Slider(0.0, 1.5, value=0.7, step=0.05,
+                                     label="Reference strength (IP-Adapter / FaceID)")
+                denoise = gr.Slider(0.1, 1.0, value=0.65, step=0.01,
+                                    label="Denoise strength (img2img · ต่ำ = อิงรูปมาก)")
+            with gr.Column():
+                negative_prompt = gr.Textbox(label="Negative prompt", lines=2)
+                with gr.Row():
+                    steps = gr.Slider(1, 50, value=28, step=1, label="Steps")
+                    guidance = gr.Slider(0.0, 15.0, value=6.5, step=0.1, label="Guidance (CFG)")
+                with gr.Row():
+                    width = gr.Slider(384, 1280, value=768, step=64, label="Width")
+                    height = gr.Slider(384, 1280, value=768, step=64, label="Height")
+                with gr.Row():
+                    seed = gr.Number(value=-1, label="Seed (-1 = random)", precision=0)
+                    randomize = gr.Checkbox(value=True, label="Randomize seed")
+
+    # ---- wiring ----
+    model_radio.change(
+        on_model_change, inputs=model_radio,
+        outputs=[mode_radio, prompt, negative_prompt, steps, guidance],
+    )
+    reload_btn.click(reload_registry, outputs=[model_radio, reload_status])
+
+    gen_inputs = [model_radio, mode_radio, prompt, negative_prompt, ref_image,
+                  steps, guidance, denoise, ip_scale, width, height, seed, randomize]
+    gen_btn.click(generate, inputs=gen_inputs, outputs=[output, seed, status])
+    prompt.submit(generate, inputs=gen_inputs, outputs=[output, seed, status])
+
+
+if __name__ == "__main__":
+    demo.queue(max_size=12).launch()

models.json

@@ -0,0 +1,79 @@
+{
+  "_comment": "Editable model registry. Add/remove entries freely, then restart the Space (or click 🔄 Reload models). Each entry must keep these fields. See README_TH.md for the field guide.",
+
+  "models": [
+    {
+      "id": "sd15-realistic-base",
+      "label": "SD1.5 · Realistic Base",
+      "base": "sd15",
+      "type": "checkpoint",
+      "repo_id": "stable-diffusion-v1-5/stable-diffusion-v1-5",
+      "single_file_url": null,
+      "trigger": "",
+      "recommended_prompt": "RAW photo, a beautiful woman, detailed skin, soft lighting, 50mm, depth of field",
+      "negative_prompt": "(worst quality, low quality:1.4), deformed, extra fingers, watermark, text",
+      "default_steps": 28,
+      "default_guidance": 6.5,
+      "enabled": true
+    },
+    {
+      "id": "sd15-asian-girls-face-lora",
+      "label": "Asian Girls Face (LoRA · SD1.5)",
+      "base": "sd15",
+      "type": "lora",
+      "repo_id": "stable-diffusion-v1-5/stable-diffusion-v1-5",
+      "lora_url": "https://civitai.com/api/download/models/67980",
+      "lora_repo_id": null,
+      "lora_weight_name": null,
+      "lora_scale": 0.8,
+      "trigger": "",
+      "recommended_prompt": "RAW photo, asian girl, pretty face, natural skin texture, cinematic light",
+      "negative_prompt": "(worst quality, low quality:1.4), deformed, watermark, text",
+      "default_steps": 28,
+      "default_guidance": 6.5,
+      "enabled": true
+    },
+    {
+      "id": "sdxl-base",
+      "label": "SDXL · Base 1.0",
+      "base": "sdxl",
+      "type": "checkpoint",
+      "repo_id": "stabilityai/stable-diffusion-xl-base-1.0",
+      "single_file_url": null,
+      "trigger": "",
+      "recommended_prompt": "cinematic photo of a beautiful woman, 35mm, highly detailed, soft natural light",
+      "negative_prompt": "lowres, bad anatomy, worst quality, watermark, text",
+      "default_steps": 30,
+      "default_guidance": 6.0,
+      "enabled": true
+    },
+    {
+      "id": "flux-schnell",
+      "label": "FLUX.1 · Schnell (fast, open)",
+      "base": "flux",
+      "type": "checkpoint",
+      "repo_id": "black-forest-labs/FLUX.1-schnell",
+      "single_file_url": null,
+      "trigger": "",
+      "recommended_prompt": "a photorealistic portrait of a young woman, studio light, sharp focus, ultra detailed",
+      "negative_prompt": "",
+      "default_steps": 4,
+      "default_guidance": 0.0,
+      "enabled": true
+    },
+    {
+      "id": "flux-dev",
+      "label": "FLUX.1 · Dev (gated · needs HF token)",
+      "base": "flux",
+      "type": "checkpoint",
+      "repo_id": "black-forest-labs/FLUX.1-dev",
+      "single_file_url": null,
+      "trigger": "",
+      "recommended_prompt": "a photorealistic portrait of a young woman, golden hour, 85mm, bokeh, ultra detailed",
+      "negative_prompt": "",
+      "default_steps": 25,
+      "default_guidance": 3.5,
+      "enabled": false
+    }
+  ]
+}

pipeline_manager.py

@@ -0,0 +1,320 @@
+"""
+pipeline_manager.py
+-------------------
+Loads diffusion pipelines from an editable registry (models.json) and runs
+generation across multiple base families (SD1.5 / SDXL / FLUX) and multiple
+input modes (txt2img / img2img / IP-Adapter / Face identity).
+
+Designed for Hugging Face ZeroGPU: pipelines are built/cached on CPU and moved
+to CUDA inside the @spaces.GPU-decorated caller (see app.py). Nothing here calls
+.cuda() at import time.
+"""
+
+import os
+import json
+import gc
+import hashlib
+import urllib.request
+from pathlib import Path
+
+import torch
+
+# ---------------------------------------------------------------------------
+# Constants / paths
+# ---------------------------------------------------------------------------
+HERE = Path(__file__).parent
+REGISTRY_PATH = HERE / "models.json"
+DOWNLOAD_DIR = Path(os.environ.get("CS_CACHE_DIR", "/tmp/cs_models"))
+DOWNLOAD_DIR.mkdir(parents=True, exist_ok=True)
+
+CIVITAI_TOKEN = os.environ.get("CIVITAI_TOKEN", "").strip()
+HF_TOKEN = os.environ.get("HF_TOKEN", "").strip() or None
+
+DTYPE = torch.bfloat16 if torch.cuda.is_available() else torch.float32
+# SD1.5 / SDXL are most stable in float16; FLUX prefers bfloat16.
+DTYPE_SD = torch.float16
+
+DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
+
+# Modes supported per base family. Used by the UI to gate options.
+SUPPORTED_MODES = {
+    "sd15": ["txt2img", "img2img", "ip_adapter", "face_id"],
+    "sdxl": ["txt2img", "img2img", "ip_adapter", "face_id"],
+    "flux": ["txt2img", "img2img"],
+}
+
+MODE_LABELS = {
+    "txt2img": "Text → Image",
+    "img2img": "Image → Image (denoise)",
+    "ip_adapter": "IP-Adapter (style / subject)",
+    "face_id": "Face identity (FaceID)",
+}
+
+# ---------------------------------------------------------------------------
+# Registry
+# ---------------------------------------------------------------------------
+def load_registry():
+    """Read models.json and return the list of enabled model configs."""
+    with open(REGISTRY_PATH, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    models = [m for m in data.get("models", []) if m.get("enabled", True)]
+    return models
+
+
+def get_model(models, model_id):
+    for m in models:
+        if m["id"] == model_id:
+            return m
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Download helpers (Civitai / arbitrary URL → local cache)
+# ---------------------------------------------------------------------------
+def _download_url(url):
+    """Download a (Civitai or other) URL to the local cache and return the path."""
+    if not url:
+        return None
+    fname = hashlib.sha1(url.encode()).hexdigest()[:16] + ".safetensors"
+    dest = DOWNLOAD_DIR / fname
+    if dest.exists() and dest.stat().st_size > 1_000_000:
+        return str(dest)
+
+    dl_url = url
+    if "civitai.com" in url and CIVITAI_TOKEN and "token=" not in url:
+        sep = "&" if "?" in url else "?"
+        dl_url = f"{url}{sep}token={CIVITAI_TOKEN}"
+
+    req = urllib.request.Request(dl_url, headers={"User-Agent": "Mozilla/5.0"})
+    print(f"[download] {url} -> {dest}")
+    with urllib.request.urlopen(req) as resp, open(dest, "wb") as out:
+        while True:
+            chunk = resp.read(1 << 20)
+            if not chunk:
+                break
+            out.write(chunk)
+    return str(dest)
+
+
+# ---------------------------------------------------------------------------
+# Pipeline cache
+# ---------------------------------------------------------------------------
+# Keyed by model id. Stores the base txt2img pipeline (CPU). Adapters are loaded
+# on demand and tracked via the `_cs_adapter` attribute on the pipe.
+_PIPE_CACHE = {}
+_FACE_APP = None  # lazy insightface FaceAnalysis
+
+
+def _free_cache(keep_id=None):
+    """Evict cached pipelines except keep_id to bound memory (simple LRU-ish)."""
+    for k in list(_PIPE_CACHE.keys()):
+        if k != keep_id:
+            del _PIPE_CACHE[k]
+    gc.collect()
+    if torch.cuda.is_available():
+        torch.cuda.empty_cache()
+
+
+def _build_base_pipeline(cfg):
+    """Construct the txt2img pipeline for a model config (on CPU)."""
+    base = cfg["base"]
+    common = dict(token=HF_TOKEN)
+
+    if base == "sd15":
+        from diffusers import StableDiffusionPipeline
+        if cfg.get("single_file_url"):
+            local = _download_url(cfg["single_file_url"])
+            pipe = StableDiffusionPipeline.from_single_file(
+                local, torch_dtype=DTYPE_SD, safety_checker=None
+            )
+        else:
+            pipe = StableDiffusionPipeline.from_pretrained(
+                cfg["repo_id"], torch_dtype=DTYPE_SD, safety_checker=None, **common
+            )
+
+    elif base == "sdxl":
+        from diffusers import StableDiffusionXLPipeline
+        if cfg.get("single_file_url"):
+            local = _download_url(cfg["single_file_url"])
+            pipe = StableDiffusionXLPipeline.from_single_file(local, torch_dtype=DTYPE_SD)
+        else:
+            pipe = StableDiffusionXLPipeline.from_pretrained(
+                cfg["repo_id"], torch_dtype=DTYPE_SD, **common
+            )
+
+    elif base == "flux":
+        from diffusers import FluxPipeline
+        pipe = FluxPipeline.from_pretrained(cfg["repo_id"], torch_dtype=DTYPE, **common)
+
+    else:
+        raise ValueError(f"Unknown base family: {base}")
+
+    # Apply LoRA if this entry is a LoRA model.
+    if cfg.get("type") == "lora":
+        scale = float(cfg.get("lora_scale", 0.8))
+        if cfg.get("lora_repo_id"):
+            kwargs = {}
+            if cfg.get("lora_weight_name"):
+                kwargs["weight_name"] = cfg["lora_weight_name"]
+            pipe.load_lora_weights(cfg["lora_repo_id"], **kwargs)
+        elif cfg.get("lora_url"):
+            local = _download_url(cfg["lora_url"])
+            pipe.load_lora_weights(local)
+        try:
+            pipe.fuse_lora(lora_scale=scale)
+        except Exception as e:  # noqa
+            print(f"[lora] fuse skipped: {e}")
+
+    pipe.set_progress_bar_config(disable=True)
+    pipe._cs_adapter = None  # track loaded IP-Adapter / FaceID state
+    return pipe
+
+
+def get_pipeline(cfg):
+    """Return a cached base pipeline for the model, building it if needed."""
+    mid = cfg["id"]
+    if mid not in _PIPE_CACHE:
+        _free_cache(keep_id=None)  # one big model at a time on ZeroGPU
+        print(f"[pipeline] building {mid} ({cfg['base']})")
+        _PIPE_CACHE[mid] = _build_base_pipeline(cfg)
+    return _PIPE_CACHE[mid]
+
+
+# ---------------------------------------------------------------------------
+# Adapter management (IP-Adapter / FaceID)
+# ---------------------------------------------------------------------------
+_IP_ADAPTER_SPECS = {
+    "sd15": {
+        "ip_adapter": dict(repo="h94/IP-Adapter", subfolder="models",
+                           weight_name="ip-adapter-plus_sd15.bin"),
+        "face_id": dict(repo="h94/IP-Adapter-FaceID", subfolder=None,
+                        weight_name="ip-adapter-faceid_sd15.bin",
+                        image_encoder_folder=None),
+    },
+    "sdxl": {
+        "ip_adapter": dict(repo="h94/IP-Adapter", subfolder="sdxl_models",
+                           weight_name="ip-adapter-plus_sdxl_vit-h.bin"),
+        "face_id": dict(repo="h94/IP-Adapter-FaceID", subfolder=None,
+                        weight_name="ip-adapter-faceid_sdxl.bin",
+                        image_encoder_folder=None),
+    },
+}
+
+
+def _ensure_adapter(pipe, base, mode):
+    """Load the right IP-Adapter for `mode`, unloading any previous one."""
+    want = mode if mode in ("ip_adapter", "face_id") else None
+    if pipe._cs_adapter == want:
+        return
+    try:
+        pipe.unload_ip_adapter()
+    except Exception:
+        pass
+    pipe._cs_adapter = None
+    if want is None:
+        return
+    spec = _IP_ADAPTER_SPECS[base][want]
+    kwargs = {k: v for k, v in spec.items() if k != "repo"}
+    pipe.load_ip_adapter(spec["repo"], **kwargs)
+    pipe._cs_adapter = want
+
+
+def _get_face_app():
+    global _FACE_APP
+    if _FACE_APP is None:
+        from insightface.app import FaceAnalysis
+        app = FaceAnalysis(name="buffalo_l",
+                           providers=["CUDAExecutionProvider", "CPUExecutionProvider"])
+        app.prepare(ctx_id=0, det_size=(640, 640))
+        _FACE_APP = app
+    return _FACE_APP
+
+
+def _face_embeds(image):
+    """Return a torch tensor of FaceID embeddings for the largest face."""
+    import numpy as np
+    import cv2
+    app = _get_face_app()
+    arr = cv2.cvtColor(np.array(image.convert("RGB")), cv2.COLOR_RGB2BGR)
+    faces = app.get(arr)
+    if not faces:
+        raise ValueError("ไม่พบใบหน้าในรูปต้นแบบ / No face detected in the reference image.")
+    faces = sorted(faces, key=lambda f: (f.bbox[2] - f.bbox[0]) * (f.bbox[3] - f.bbox[1]))
+    emb = torch.from_numpy(faces[-1].normed_embedding)  # [512]
+    # diffusers IP-Adapter-FaceID expects [2, 1, 1, 512]: [neg, pos] for CFG.
+    emb = emb.unsqueeze(0).unsqueeze(0).unsqueeze(0)     # [1, 1, 1, 512]
+    return torch.cat([torch.zeros_like(emb), emb], dim=0).to(DTYPE_SD)
+
+
+# ---------------------------------------------------------------------------
+# Generation
+# ---------------------------------------------------------------------------
+def run_generation(cfg, mode, prompt, negative_prompt, ref_image,
+                   steps, guidance, denoise, ip_scale, width, height, seed):
+    """Run one generation. MUST be called inside a @spaces.GPU context."""
+    base = cfg["base"]
+    if mode not in SUPPORTED_MODES[base]:
+        raise ValueError(
+            f"โหมด '{MODE_LABELS.get(mode, mode)}' ใช้กับ base {base.upper()} ไม่ได้ "
+            f"(รองรับ: {', '.join(MODE_LABELS[m] for m in SUPPORTED_MODES[base])})"
+        )
+
+    pipe = get_pipeline(cfg)
+    pipe = pipe.to(DEVICE)
+
+    generator = None
+    if seed is not None and int(seed) >= 0:
+        generator = torch.Generator(device=DEVICE).manual_seed(int(seed))
+
+    full_prompt = prompt
+    if cfg.get("trigger"):
+        full_prompt = f"{cfg['trigger']}, {prompt}".strip(", ")
+
+    call = dict(
+        prompt=full_prompt,
+        num_inference_steps=int(steps),
+        generator=generator,
+        width=int(width),
+        height=int(height),
+    )
+
+    # FLUX uses `guidance_scale` differently and has no negative prompt.
+    if base == "flux":
+        call["guidance_scale"] = float(guidance)
+    else:
+        call["guidance_scale"] = float(guidance)
+        call["negative_prompt"] = negative_prompt or None
+
+    # ----- mode wiring -----
+    if mode == "txt2img":
+        _ensure_adapter(pipe, base, None)
+
+    elif mode == "img2img":
+        _ensure_adapter(pipe, base, None) if base != "flux" else None
+        if ref_image is None:
+            raise ValueError("img2img ต้องอัปโหลดรูปต้นแบบก่อน / Upload a reference image first.")
+        from diffusers import AutoPipelineForImage2Image
+        i2i = AutoPipelineForImage2Image.from_pipe(pipe).to(DEVICE)
+        call.pop("width"); call.pop("height")
+        call["image"] = ref_image.convert("RGB")
+        call["strength"] = float(denoise)
+        out = i2i(**call).images[0]
+        return out
+
+    elif mode == "ip_adapter":
+        if ref_image is None:
+            raise ValueError("IP-Adapter ต้องอัปโหลดรูปต้นแบบก่อน / Upload a reference image first.")
+        _ensure_adapter(pipe, base, "ip_adapter")
+        pipe.set_ip_adapter_scale(float(ip_scale))
+        call["ip_adapter_image"] = ref_image.convert("RGB")
+
+    elif mode == "face_id":
+        if ref_image is None:
+            raise ValueError("Face identity ต้องอัปโหลดรูปใบหน้าก่อน / Upload a face image first.")
+        _ensure_adapter(pipe, base, "face_id")
+        pipe.set_ip_adapter_scale(float(ip_scale))
+        embeds = _face_embeds(ref_image).to(DEVICE)
+        call["ip_adapter_image_embeds"] = [embeds]
+
+    out = pipe(**call).images[0]
+    return out

requirements.txt

@@ -0,0 +1,18 @@
+# ZeroGPU provides the CUDA torch build; do not pin torch hard.
+spaces
+torch
+torchvision
+diffusers>=0.31.0
+transformers>=4.44.0
+accelerate>=0.33.0
+peft>=0.12.0
+safetensors>=0.4.3
+sentencepiece
+protobuf
+huggingface_hub>=0.25.0
+Pillow
+numpy
+opencv-python-headless
+# Face-identity mode (IP-Adapter FaceID). Heavy; comment out if you don't use Face mode.
+insightface==0.7.3
+onnxruntime