DSH Image2 Draw (gpt-image-2 generation plugin)
Adds Image2 (gpt-image-2) generation to DeepSeek Harness:
text-to-image and image-to-image through any OpenAI Images-compatible relay API.
Configure only a baseURL and an API Key, and generated images appear directly in
the conversation (thumbnails, zoom, Save As) while also landing in outputs/image2/.
Community fork — this repository is a maintained fork of the MIT-licensed
JuneLearn/dsh-image2-draw with
gateway-compatibility fixes (see Fork changes). Upstream
copyright and license are preserved in LICENSE.
Quick install — pick one line and run it in your terminal:
# Already running DSH (web profile):
dsh plugin --profile web add github:oebeliever/dsh-image2-draw
# Brand-new machine, one click (auto-installs Node/pnpm/DSH):
# Windows PowerShell:
irm https://raw.githubusercontent.com/oebeliever/dsh-image2-draw/main/install.ps1 | iex
# macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/oebeliever/dsh-image2-draw/main/install.sh | bash
Then restart DSH (dsh web), open Settings → Plugins → Plugin config → Image2 生图,
enter the API Key and baseURL of any OpenAI-Images-compatible relay (e.g.
https://example.com/v1, /images/generations is appended automatically), and ask the
AI to call image2-generate. 中文说明
Features
- Adds an Image2 Draw settings card under Settings → Plugins → Plugin config.
- Requires only a
baseURL and an API Key; default model is gpt-image-2.
- Multiple endpoints with automatic failover — up to 8 relays; when one fails with a network
error / timeout / 401 / 402 / 403 / 404 / 429 / 5xx, the next is used automatically.
- The same repo is also a Claude Code plugin —
skills/image2-draw provides the skill, sharing
one core implementation with the DSH plugin.
- Accepts a short base URL like
https://example.com/v1 and appends
/images/generations automatically.
- Derives the image-edit endpoint as
/images/edits (optional explicit editURL).
image2-generate — text-to-image, 1–8 images, sequential requests (no concurrency).image2-edit — image-to-image with 1–8 PNG / JPEG / WebP reference images.- Quality levels
low / medium / high / auto (depends on relay support).
- In-conversation tool card with thumbnails, zoom and Save As; files also saved to
outputs/image2/image2-<timestamp>[-N].<ext>, auto-numbered on name collision.
- Chat-dock studio (🎨 above the input box): text-to-image, image-to-image with
click/drag-drop upload, and a multi-view character mode — upload 2–8 photos of
the same person from different angles and generate new shots that keep the person's
face, build and hairstyle consistent (multi-source-image
edits semantics).
- Sizes: adaptive from prompt keywords,
auto passthrough, gateway-friendly presets
(1024x1024 / 1536x1024 / 1024x1536 / 3840x2160 …) and validated custom
WIDTHxHEIGHT (16px multiples, ≤ 3840 edge, 655,360–8,294,400 px², ratio ≤ 3:1).
- API key stored in DSH credentials only — never in the plain settings document and
never returned by the plugin state endpoint. (Or set the
IMAGE2_API_KEY env var.)
- Validates settings writes, response sizes, timeouts and input images; HTTP 524 and
timeouts are not auto-retried, avoiding duplicate upstream charges.
Fork changes
v0.2.1 (preset library)
- Built-in templates: character-design Sheet A (face close-up + shirtless physique +
outfit action pose) and Sheet B (outfit-on-body wear crops) prompts with a
{outfit} variable; the multi-view → per-outfit sheets (confirm each) flow; the
six-outfit list (zh/en) derived from the reference photos.
- User presets persist to
~/.dsh/storages/image2-draw/presets.json; the 🎨 studio gains
a 📚 template bar: load presets with variable filling, save the current prompt as
a template, preview/copy flow & list bodies, delete user presets.
- New chat tool
image2-preset (list / get / save) so the agent can reuse
templates — e.g. run the character-design flow one sheet at a time, waiting for user
confirmation between sheets.
v0.2.0
- Size handling aligned with OpenAI Images spec used by common relays (e.g. zzz /
OpenAI-compatible gateways):
auto is passed through as-is; portrait/landscape
presets moved from 768x1024/1024x768 to gateway-safe 1024x1536/1536x1024;
documented presets 1024x1024 / 1536x1024 / 1024x1536 / 3840x2160 short-circuit
validation and go straight to the API.
/images/edits now always sends repeated standard image fields for multiple
source images (previously a non-standard image[] field for >1 image). This matches
the OpenAI multi-source-image semantics and unblocks multi-view character
consistency (several photos of the same person → one new image of that person).
refs also accepts conversation attachment ids (sha256:…) directly — the
plugin reads them from the attachment store, no local paths or vision tool needed.- New chat-dock 🎨 studio (
conversation.input.dock): text-to-image /
image-to-image / multi-view character tabs, click & drag-drop upload with previews,
an "assemble consistency prompt" helper, background task + polling, and result
gallery with Save As. Studio results live in ~/.dsh/storages/image2-draw/library/
(survives restarts), independent from conversation-tool outputs.
- Clearer "no key / wrong group" message (keys must belong to the relay's Image group
when the relay separates models by token group).
v0.1.1 (vs upstream v0.1.0)
- Removed the non-standard
output_format field from the generations payload — some
OpenAI-compatible gateways reject it (standard params only: model/prompt/size/quality/n).
redirect: 'manual' with clear diagnostics for 3xx responses, including a dedicated
message for upstream region-unavailable (e.g. mainland-China IP blocked — switch to an
overseas proxy node or another relay).- Friendlier "not valid JSON" errors that include the actual upstream snippet (gateway
error page / region block page / wrong baseURL).
- Fixed the settings-card slot registration (
key: 'image2-draw') so the card loads
reliably on current Harness client versions.
Prerequisites
- Node.js — DSH supports Node 22.19.x or ≥ 24 (24 LTS recommended).
- Git — to fetch plugins from GitHub.
- pnpm —
dsh plugin runs pnpm in the profile directory (corepack enable is enough).
- Network access to
registry.npmjs.org and github.com. From restricted networks,
set HTTP_PROXY / HTTPS_PROXY (and npm_config_proxy) in the current shell.
Installation
Method A — brand-new machine, one click
Windows PowerShell:
irm https://raw.githubusercontent.com/oebeliever/dsh-image2-draw/main/install.ps1 | iex
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/oebeliever/dsh-image2-draw/main/install.sh | bash
The script checks Node.js (installs the LTS via winget on Windows if missing), enables
pnpm, globally installs @deepseek-ai/dsh when absent, adds this plugin to the web
profile, then prints the startup guide.
Method B — DSH already installed, one command
dsh plugin --profile web add github:oebeliever/dsh-image2-draw
Restart DSH afterwards (dsh web); the plugin auto-joins the profile bundle layer via
its dsh.bundle declaration — no manual patch editing.
Method C — no global install, via npx (first run is slower)
npx --yes -p @deepseek-ai/dsh dsh plugin --profile web add github:oebeliever/dsh-image2-draw
Launch the same way afterwards: npx --yes -p @deepseek-ai/dsh dsh web.
Upgrade & uninstall
Upgrade = re-run the same install command (fetches the latest commit), then restart dsh.
Uninstall:
dsh plugin --profile web remove dsh-image2-draw
Restart dsh web; the card and tools disappear (images already saved to
outputs/image2/ are kept).
Claude Code installation
This repo doubles as a Claude Code plugin (sharing lib/core.js with the DSH plugin).
Option 1 — plugin marketplace (recommended)
/plugin marketplace add oebeliever/dsh-image2-draw
/plugin install image2-draw@dsh-image2-draw
Option 2 — copy the skill only: put skills/image2-draw/ into ~/.claude/skills/ (all projects)
or <project>/.claude/skills/ (one project).
Option 3 — DSH already configured: nothing to do; the skill falls back to DSH's baseURL and credentials.
Multi-endpoint config lives in ~/.claude/image2-draw.json:
{ "timeoutSeconds": 900,
"endpoints": [
{ "name": "primary", "baseURL": "https://api.example.com/v1", "apiKey": "sk-…", "model": "gpt-image-2" },
{ "name": "backup", "baseURL": "https://backup.example.com/v1", "apiKeyEnv": "IMAGE2_API_KEY_B" }
] }
The endpoint shape and failover rules match the DSH side. Note apiKeyEnv means different things
on each side: here it is an environment-variable name (so keys can stay out of the file);
on the DSH side it is a credential-store reference.
When falling back to DSH settings only the flat single-endpoint fields are read — use the JSON file
or env vars for multiple endpoints.
Usage (just talk to Claude Code):
Use image2-draw to turn this photo into a cartoon figurine: C:\path\to\photo.jpg
Generate a chibi shiba-inu figurine image, square, high quality
Usage
- Settings → Plugins → Plugin config → Image2 生图.
- Fill in
API Key and baseURL (e.g. https://example.com/v1) from your relay.
- Adjust model / edit endpoint / timeout only if needed; defaults usually work.
- Save, start a new session, and ask the model to call
image2-generate, or pass
reference-image paths to image2-edit.
- Prefer the graphical way for image inputs: open the 🎨 Image2 生图工作台 above
the input box, pick a tab (文生图 / 图生图 / 多视角人物), drop images in and generate.
Example prompts:
Call image2-generate to create a portrait cinematic poster of a future city at high quality.
Call image2-edit with D:\images\room.png and restyle the room with light Japanese wood while preserving the layout.
Whether the relay actually supports gpt-image-2, editing, custom sizes and quality
levels is up to the provider. HTTP 400 / 404 → check the provider's model name and
Images endpoint format. Size errors → most gateways accept only auto / 1024x1024 /
1536x1024 / 1024x1536 / 3840x2160; pick a preset instead of a custom WIDTHxHEIGHT.
region-unavailable → the relay blocks your exit IP region;
switch to an overseas proxy or another provider.
Multiple endpoints with automatic failover
Configure up to 8 endpoints in Settings → Plugins → Plugin config. They are tried in order;
when one fails with network error / timeout / 401 / 402 / 403 / 404 / 429 / 5xx (including 524),
the next one is used automatically. Parameter errors such as HTTP 400 never trigger a switch
(401/402/403/404/429 still do) — another endpoint would fail identically.
- Each endpoint has its own credential reference (
IMAGE2_API_KEY, IMAGE2_API_KEY_2, …) and optional model.
- A failing endpoint is moved to the back: the next request starts from the endpoint that last succeeded.
- If the fallback later fails, the primary is retried automatically (self-healing).
- Set
IMAGE2_NO_ROTATE=1 to disable this memory and always start from the first endpoint.
⚠️ A 524/timeout means the upstream may still have generated an image, so failing over can
double-bill. When every endpoint fails, the error message says so explicitly; a failover that
ends in success carries no extra warning — decide accordingly before regenerating.
⚠️ Always reference keys through credentials (apiKeyEnv) — never use the apiKey field.
A literal apiKey lives server-side only: the settings panel can neither see nor edit it, and
editing the endpoint list in the panel replaces the whole array, silently dropping any hand-written
literal (generation then fails with "no key configured"). Need several keys? Create several
credential refs: IMAGE2_API_KEY, IMAGE2_API_KEY_2, …
Limits
- Text-to-image: 1–8 images per call, sent one by one.
- Image-to-image: 1–8 reference images, ≤ 4MB each, ≤ 32MB total.
- References must be PNG / JPEG / WebP; real format is sniffed from magic bytes.
- Relative reference paths resolve against the current session working directory.
- Default timeout 180 s (configurable 1–3600 s); remote result download ≤ 32MB.
Development
node --check lib/index.js
node --check lib/client.js
Unit tests (node tests/plugin.test.mjs) import the @deepseek-ai/* runtime peer
packages, so run them inside an environment where those are installed — a DSH profile's
node_modules or a Harness source workspace — rather than in a bare checkout.
Acknowledgements
Original plugin by JuneLearn (MIT). Parts of the
in-conversation attachment and tool-card implementation were adapted from the
MIT-licensed dsh-multimodal — see
THIRD_PARTY_NOTICES.md.
License
MIT — upstream © 2026 JuneLearn; fork © 2026 oebeliever.
