Tencent Hunyuan Image Generation · Native DSH Plugin
Languages: English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Português · Español · Русский
Bring Tencent Hunyuan's Hy-Image-3.5-preview and Hy-Image-3.0 into
DSH (DeepSeek Harness) — with a generation panel, local gallery,
the official two-step size picker and batch generation.
Zero native dependencies. Runs on macOS, Windows and Linux.
✨ Features
-
Two models
hy-image-v3.5-preview — Chat/Messages protocol; multimodal input, multi-turn editing,
chain-of-thought rewriting; up to 4K (4096×4096) outputhy-image-v3 — classic text-to-image; prompt rewriting and the official 37 preset sizes
-
Official two-step size picker — resolution tier × aspect ratio, the same interaction as
the Tencent TokenHub web console. The plugin converts your choice into the WxH string the API
expects and guarantees it satisfies the official constraints
(v3.5: edges in [256, 8192], area ≤ 16,777,216; v3.0: edges in [512, 2048], area ≤ 1,048,576).
The UI shows the exact size that will be sent.
-
Batch generation — generate 1 / 2 / 4 images in one request (issued in parallel);
results are shown one by one with a 1/4 index badge. Partial failures are reported explicitly.
-
Local gallery
- Every successful generation is stored automatically (plain-JS JSON storage — no SQLite, no native module)
- Thumbnail grid and list views
- Keyword search (matches the prompt and the rewritten prompt) plus filtering by model and time range
- Detail drawer with the full prompt, model, size, timestamp and local path
- 🔁 Generate again — refills the original prompt and parameters in one click
- Multi-select batch delete (also removes the local files), copy prompt, copy image
-
Customisable output folder — defaults to ~/Pictures/DSH-Hunyuan-Image, but you can point it
anywhere (a non-system drive is recommended). Clicking "Choose…" opens the native OS folder picker.
Changes take effect immediately, no plugin restart needed. Files are bucketed by month under
<folder>/<YYYY-MM>/ to avoid piling thousands of files into one directory.
-
Official advanced parameters (session-scoped on purpose — see Roadmap)
| Parameter | Applies to | Description |
|---|
Seed seed | both | Reproduce the same result |
Watermark footnote footnote | both | ≤ 16 characters, rendered in the bottom-right corner |
External search augmentation use_search_tool | v3.5 | Let the model search the web before drawing |
Reference-image area cap resize_max_pixels | v3.5 | Caps the token cost of large (4K/6K) reference images |
Automatic prompt rewriting revise | v3.0 | Adds ~11 s; recommended on by default |
-
Reference images — upload from disk (converted to a data URL) or pass a public URL.
v3.5 accepts up to 20 (≤ 20 MB each); v3.0 up to 3 (≤ 10 MB each).
-
Callable by the model — the plugin registers a hunyuan_generate_image tool, so you can
just say "draw a cat" in a conversation and the model will call it.
-
Durable images — Tencent's remote URLs expire after 12 hours; the plugin downloads every
generated image to disk immediately, so gallery entries never break.
📌 Unimplemented features are listed honestly in
Known limitations & roadmap.
This README only describes what the current version actually does.
📦 Installation
Option 1 — Install from the Release (recommended, no build step)
-
Download dsh-plugin-hunyuan-image-1.0.0.tgz from the Releases page.
-
Extract it into a permanent folder, e.g. ~/dsh-plugins/:
mkdir -p ~/dsh-plugins
tar -xzf dsh-plugin-hunyuan-image-1.0.0.tgz -C ~/dsh-plugins
-
In the DSH chat, tell the assistant:
Please install ~/dsh-plugins/package as a DSH plugin (use plugin_manager with install_bundle).
-
Restart DSH.
Step-by-step reinstall / new-machine instructions: INSTALL.md
(also available in 简体中文).
Option 2 — Build from source (developers)
Requires Node ≥ 20 and pnpm.
git clone https://github.com/rayyugz/dsh-plugin-hunyuan-image.git
cd dsh-plugin-hunyuan-image
pnpm install
pnpm build # compile the host half + bundle the client half
node scripts/smoke-activate.mjs # smoke test — should print "全部通过"
# Link into the DSH profile
# macOS / Linux:
ln -s "$(pwd)" ~/.dsh/profiles/desktop/node_modules/dsh-plugin-hunyuan-image
# Windows (PowerShell, administrator):
# New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-plugin-hunyuan-image" -Target "$PWD"
Then add the plugin name to the profile's package.json (in both dependencies and
dsh.profile.bundles) and restart DSH.
⚙️ Configuration
1. Get an API Key
- Sign up / log in at Tencent Cloud
- Activate the TokenHub service
- Create a Key on the API Key page — it looks like
sk-...
- Enable pay-as-you-go for
hy-image-v3.5-preview and hy-image-v3 under
Online inference → Vision models
2. Fill in the plugin settings
Open the plugin panel (🖼 Hunyuan Image button under the composer) → Settings tab:
| Field | Description | Default |
|---|
| API Key | The Key created above | — |
| Output folder | Anywhere you like; a non-system drive is recommended | ~/Pictures/DSH-Hunyuan-Image |
| Default model | hy-image-v3.5-preview or hy-image-v3 | v3.5-preview |
| Default resolution | See Sizes | 1K |
| Default aspect ratio | See Sizes | 1:1 |
| Watermark footnote | ≤ 16 characters, bottom-right corner | empty |
Click Save, then 🔌 Test connection to verify the Key works.
⚠️ Note: images are stored under a month sub-folder, e.g.
AI-images/2026-10/1791629683045-xxxx.png — not directly in the folder root.
🖼 Sizes
The plugin mirrors the official TokenHub picker: pick a resolution tier and an aspect ratio.
Hy-Image-3.5-preview
| Tier | Aspect ratios | Notes |
|---|
1K / 1.5K / 2K | 21:9 16:9 4:3 1:1 2:3 3:2 3:4 9:16 | Area ≈ 1M / 2.36M / 4.19M px |
4K | same | Area ≤ 16,777,216 px; e.g. 16:9 → 5461x3072 |
Auto | — | No size is sent; the model decides |
Hy-Image-3.0
| Tier | Aspect ratios | Notes |
|---|
720P / 1K | 1:1 3:4 4:3 9:16 16:9 3:5 5:3 | Must satisfy edges ∈ [512, 2048] and area ≤ 1,048,576 |
Auto | — | The model picks from the official 37 presets |
Rough size reference (what actually gets sent):
v3.5 1K 16:9 = 1365x768 1:1 = 1024x1024
2K 16:9 = 2731x1536 1:1 = 2048x2048
4K 16:9 = 5461x3072 1:1 = 4096x4096
v3.0 720P 16:9 = 1280x720 1:1 = 960x960
1K 16:9 = 1365x768 1:1 = 1024x1024
All 62 combinations are validated programmatically against the official constraints.
📚 Using the gallery
| Action | How |
|---|
| Search | Search box at the top (300 ms debounce; matches prompt / rewritten prompt / keywords) |
| Filter | By model, and by time range |
| Multi-select | Checkbox on the card, or via the hover overlay |
| Batch delete | Select items → the batch action bar appears at the top |
| Inspect one image | Hover overlay, or open the detail drawer |
| Generate again | 🔁 in the detail drawer — switches back to the generator and refills the prompt and parameters |
| Copy prompt | 📋 in the detail drawer |
| Copy image | 🖼 in the detail drawer (falls back to copying the local path when the browser lacks ClipboardItem) |
⚠️ Known limitations & roadmap
Limitations (imposed by the Tencent API or the DSH host)
| Item | Detail |
|---|
| Remote image URL lifetime | Only 12 hours — this plugin downloads every image to disk immediately, so gallery entries are permanent |
| Reference image size | v3.5 ≤ 20 MB each; v3.0 ≤ 10 MB each |
| Reference image count | v3.5 ≤ 20; v3.0 ≤ 3 |
| Watermark footnote | ≤ 16 UTF-8 characters |
generate_max_pixels caps at 2K | Higher resolutions must go through size (this plugin does that via the resolution tier) |
| Multi-turn editing | v3.5 only. The plugin stores the server-returned assembled_history, but there is no UI for multi-turn editing yet |
| Advanced parameters are not persisted | The external-search, reference-area-cap and rewrite toggles apply to the current session only and reset when the panel is reopened. This is deliberate — it avoids hidden state that is hard to diagnose later |
Not implemented yet
| Feature | Status | Why |
|---|
| Auto "open gallery" button when you mention the gallery | ❌ | Requires listening to session message events and injecting an action button; not wired up in v1.0 |
| Export / Save-as dialog | ⚠️ stub | DSH does not expose a "save as" dialog to plugins yet; the call returns an explicit reason rather than failing silently |
| WeChat / Feishu sharing | ⚠️ stub | DSH does not expose an IM sharing channel to plugins yet |
| Drag an image into the conversation | ❌ | Depends on DSH exposing drag events |
| Multi-turn editing UI | ❌ | The data layer is ready (assembledHistory); only the UI is missing |
| DSH official plugin marketplace | ❌ | Requires review by the DSH team |
| Localised panel UI | ❌ | The in-panel UI is currently Chinese-only; only the plugin title and description are localised (EN/ZH). These translated READMEs are a stopgap |
Feedback and pull requests are very welcome — please open an Issue.
🛠 Development
Project layout
dsh-plugin-hunyuan-image/
├── package.json # plugin manifest (dsh.bundle.patch + dsh.client)
├── cordis.patch.yml # Cordis loader patch: declares the host plugin row
├── icon.svg / locale/ # display metadata (icon + EN/ZH title & description)
├── scripts/
│ ├── build-client.mjs # bundles TS/TSX into the DSH client module-table format
│ └── smoke-activate.mjs # activation smoke test (run before restarting DSH)
├── src/
│ ├── server.ts # ★ Host half: Cordis plugin entry (apply + inject)
│ ├── client.ts # ★ Client half: registers the composer dock + panel overlay
│ ├── types.ts # cross-module data contracts
│ ├── size-presets.ts # resolution tier + aspect ratio → "WxH" (with constraint checks)
│ ├── host/
│ │ └── routes.ts # host HTTP endpoints: /hunyuan/api/* and /hunyuan/file
│ ├── client-services/
│ │ ├── rpc.ts # client → host fetch wrapper
│ │ ├── config-client.ts # config cache + updates
│ │ ├── bus.ts # event bus (folder picker, file picker, …)
│ │ └── file-url.ts # local image path → loadable URL
│ ├── services/
│ │ ├── config.ts # config persistence (JSON, atomic write)
│ │ ├── storage.ts # local file management + image download (path follows config live)
│ │ ├── hunyuan.ts # Hunyuan API gateway (v3 + v3.5)
│ │ └── gallery.ts # JSON gallery (in-memory index + atomic write, no native deps)
│ └── slots/
│ ├── generator-panel.tsx # generator panel (overlay "Generate" tab)
│ ├── gallery-panel.tsx # gallery panel (overlay "Gallery" tab)
│ └── settings-panel.tsx # settings panel (overlay "Settings" tab)
├── README.md + 7 translations (.zh-CN · .zh-TW · .ja · .ko · .pt · .es · .ru)
├── INSTALL.md / INSTALL.zh-CN.md
└── LICENSE
Architecture notes
- Two entries:
dist/server.js is the Host half (Node.js process) and dist/client.js is the
Client half (browser). The latter must be in window.__ModuleLoader__.load({id, factory}) format,
produced by scripts/build-client.mjs via esbuild; JSX is force-compiled to
React.createElement because the DSH module table provides React but not react/jsx-runtime.
- UI entry point: the client registers a single
conversation.composer.dock slot (a button).
Clicking it opens an overlay with three tabs: Generate / Gallery / Settings.
- Client ↔ host: the client calls the host through
fetch('/hunyuan/api/<method>'); images are
served back through /hunyuan/file?path=<absolute path> (restricted to files inside the
configured output folder, to prevent path traversal).
- Zero native dependencies: the gallery is a JSON file rather than SQLite, so it loads fine under
the macOS code-signing / hardened-runtime restrictions of the DSH app, and needs no rebuild on
Windows or Linux.
Local build
pnpm install
pnpm build # tsc → dist/ (host), esbuild → dist/client.js (client)
pnpm typecheck # tsc --noEmit
node scripts/smoke-activate.mjs
Debug mode
Start DSH with --plugin-debug=hunyuan-image for verbose logging.
🤝 Contributing
Issues and pull requests are welcome.
📄 License
MIT © rayyugz
🙏 Acknowledgements
- The Tencent Hunyuan team for the API
- The DSH team for the plugin platform
- Everyone who files issues and helps improve this plugin
