From ff888fd3da43463a204c3cfdf50c816a412030e8 Mon Sep 17 00:00:00 2001
From: Daniel Han <danielhanchen@gmail.com>
Date: Fri, 17 Jul 2026 12:52:01 +0000
Subject: [PATCH] Surface HunyuanImage 2.1 in the image model catalog

Catalog group with the open bf16 mirror pipeline (~50 GB resident, so a
bare click on a consumer card routes to the QuantStack GGUF quants, which
load and render through the generic GGUF path, verified live) plus the
images page defaults (50 steps, guidance 3.25 feeding
distilled_guidance_scale).
---
 .../model-selector/model-catalog.check.ts     | 19 +++++++++++++++++++
 .../model-selector/model-catalog.ts           | 13 +++++++++++++
 .../src/features/images/images-page.tsx       |  3 +++
 3 files changed, 35 insertions(+)

diff --git a/studio/frontend/src/components/assistant-ui/model-selector/model-catalog.check.ts b/studio/frontend/src/components/assistant-ui/model-selector/model-catalog.check.ts
index 4050784d41..4c98115703 100644
--- a/studio/frontend/src/components/assistant-ui/model-selector/model-catalog.check.ts
+++ b/studio/frontend/src/components/assistant-ui/model-selector/model-catalog.check.ts
@@ -380,6 +380,25 @@ assert.equal(
   "Alpha-VLLM/Lumina-Image-2.0",
 );
 assert.equal(loadSpecFor("Alpha-VLLM/Lumina-Image-2.0", IMAGE_CATALOG)?.kind, "pipeline");
+// HunyuanImage 2.1: the 50 GB bf16 pipeline does NOT fit a 24 GB card, so a bare
+// click routes to the QuantStack GGUF; on a large GPU the bf16 wins. The mirror id
+// and the GGUF id resolve to one group.
+const hyimage = groupForRepoId(
+  "hunyuanvideo-community/HunyuanImage-2.1-Diffusers",
+  IMAGE_CATALOG,
+);
+assert.ok(hyimage);
+assert.equal(
+  pickDefaultArtifact(hyimage, { gpuGb: 24, systemRamGb: 64, isDownloaded: notDownloaded })
+    .repoId,
+  "QuantStack/HunyuanImage-2.1-GGUF",
+);
+assert.equal(
+  pickDefaultArtifact(hyimage, { gpuGb: 141, systemRamGb: 128, isDownloaded: notDownloaded })
+    .format,
+  "bf16",
+);
+assert.equal(groupForRepoId("QuantStack/HunyuanImage-2.1-GGUF", IMAGE_CATALOG), hyimage);
 // FLUX.1-schnell is Apache-2.0 (not gated): its BF16 IS auto-routed on a GPU that fits it.
 const fluxSchnellRoute = groupForRepoId("unsloth/FLUX.1-schnell", IMAGE_CATALOG);
 assert.ok(fluxSchnellRoute);
diff --git a/studio/frontend/src/components/assistant-ui/model-selector/model-catalog.ts b/studio/frontend/src/components/assistant-ui/model-selector/model-catalog.ts
index aa1f5946b0..5374a07678 100644
--- a/studio/frontend/src/components/assistant-ui/model-selector/model-catalog.ts
+++ b/studio/frontend/src/components/assistant-ui/model-selector/model-catalog.ts
@@ -263,6 +263,19 @@ export const IMAGE_CATALOG: CatalogGroup[] = [
     scope: "image",
     artifacts: [bf16Pipeline("Alpha-VLLM/Lumina-Image-2.0", 11)],
   },
+  {
+    // 17B dual-stream 2K-native DiT with a Qwen2.5-VL encoder; the mirror's guider
+    // components load natively on diffusers 0.39. ~50 GB bf16-resident, so consumer
+    // GPUs route to the QuantStack GGUF quants.
+    canonicalId: "hunyuanvideo-community/HunyuanImage-2.1-Diffusers",
+    displayName: "HunyuanImage 2.1",
+    description: "Text-to-image",
+    scope: "image",
+    artifacts: [
+      bf16Pipeline("hunyuanvideo-community/HunyuanImage-2.1-Diffusers", 50),
+      gguf("QuantStack/HunyuanImage-2.1-GGUF"),
+    ],
+  },
   {
     // No bf16 repo exists for Ideogram 4: -fp8 stores its two DiTs as raw
     // float8 (~46 GB resident after the bf16 cast); -nf4-diffusers is the
diff --git a/studio/frontend/src/features/images/images-page.tsx b/studio/frontend/src/features/images/images-page.tsx
index 43929e454d..ee2df72ea7 100644
--- a/studio/frontend/src/features/images/images-page.tsx
+++ b/studio/frontend/src/features/images/images-page.tsx
@@ -170,6 +170,9 @@ const MODEL_DEFAULTS: Array<{ match: string; steps: number; guidance: number }>
   { match: "ideogram", steps: 48, guidance: 7 },
   // Lumina Image 2.0 model-card recipe (the backend adds cfg_trunc_ratio itself).
   { match: "lumina", steps: 50, guidance: 4 },
+  // HunyuanImage 2.1: 50 steps; the guidance value feeds distilled_guidance_scale
+  // (default 3.25), real CFG runs inside the repo's guider components.
+  { match: "hunyuanimage", steps: 50, guidance: 3.25 },
   // SDXL: Turbo is distilled (few steps, no CFG); base/full SDXL wants ~30 steps and
   // real CFG (~7). "sdxl-turbo" must precede the generic "sdxl" substring match.
   { match: "sdxl-turbo", steps: 3, guidance: 0 },