@dsh-extension/dsh-generation-image
On-demand image generation for DeepSeek Harness (DSH) sessions.
中文文档
A DSH plugin that gives a DeepSeek session on-demand image generation:
the agent gets a generate_image tool that calls your own OpenAI-compatible
image URL + API key (POST /images/generations or /images/edits) and delivers
the generated image into the session.
- Text-to-image and image-to-image — generate from a prompt, or edit and
combine one or more DSH image attachments through an OpenAI-compatible
/images/edits endpoint.
- Bring your own image endpoint — OpenAI-compatible image services such as
OpenAI, xiaoyaoapi, vLLM image models, or local gateways.
- The image lands in the session UI — generated bytes are durably saved as
DSH attachments, surfaced as an assistant-side image message, and rendered as a
clickable thumbnail in the conversation. Click it to enlarge, then
download or close from the enlarged view.
- The text model stays safe — DeepSeek is a text-only model, so image blocks
are rewritten to text markers for every text-model request (same mechanism as
dsh-vision-bridge); the session
log and UI keep the real image.
- Mirrors the proven GPT2Image request shape —
stream: true,
partial_images: 1, SSE image_generation.completed events (with a plain
JSON fallback), the exact endpoint used by the GPT2Image app
(https://api.xiaoyaoapi.cc/v1, model gpt-image-2).
- b64_json and url results both supported — channels that return the image
inline (
b64_json, SSE or plain JSON) work as before; channels that return a
remote url (e.g. data[].url or url-carrying SSE events) are handled
transparently by downloading the image bytes before saving the attachment.
How it works
agent calls generate_image(prompt, size?, quality?, count?, referenceImageIds?)
│
▼
referenceImageIds omitted → POST {baseUrl}/images/generations (JSON)
referenceImageIds provided → attachments.readImage() → POST {baseUrl}/images/edits
(multipart, repeated image[] fields)
│
▼
SSE (image_generation.partial_image / .completed → b64_json or url)
or plain JSON (data[].b64_json / data[].url)
│ (url results are downloaded automatically)
▼
magic-byte sniff → attachments.saveImage() → durable image ref
│
▼
tool result: text envelope + image block(s), plus an assistant-side display
message → the conversation renders a clickable thumbnail on the left
│
▼
thumbnail click → built-in lightbox (enlarge) with 下载原图 (download) + close
│
▼
deriveMessages() rewrites image blocks to text markers (text model never
sees image blocks); llm.resolveModelInfo admission bypass lets the messages
enter the agent.
Viewing generated images
The DSH Web UI renders every generated image as a thumbnail in the
conversation (an assistant-side image message). Click it to open the enlarged
lightbox:
- 下载原图 — a download button injected by this plugin's client (top-right of
the enlarged view) saves the full-resolution image to disk. It applies to
every image lightbox in the session, so uploaded images and screenshots get
the same download affordance.
- 关闭 — the built-in close control (and
Esc / clicking the mask).
No extra configuration is needed; the thumbnail, enlarge, download and close
behaviors are enabled as soon as the plugin's client bundle is loaded (refresh
the DSH web page after upgrading the plugin).
Installation
Install from the npm registry (not a local checkout) — one command:
# if you already have the `dsh` CLI on PATH:
dsh plugin --profile web add @dsh-extension/dsh-generation-image
# or, if you have been using npx all along:
npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add @dsh-extension/dsh-generation-image
The --profile flag targets the profile you boot (web is the browser UI
profile). Omit it or adapt it if your profile has a different name.
After a new client bundle is added, restart dsh web once so the UI picks it up.
Local development (like vision-bridge)
From a local checkout, link it into your profile like the sibling plugins, then
restart dsh web:
// ~/.dsh/profiles/web/package.json → dependencies
{
"@dsh-extension/dsh-generation-image": "link:/path/to/dsh-generation-image"
}
// ~/.dsh/profiles/web/package.json → dsh.profile.bundles
"@dsh-extension/dsh-generation-image"
or, for a running instance, use the DSH super-injector:
dsh plugin inject /path/to/dsh-generation-image
Configuration
Configure it in Settings → Generation Image (DSH Web), or edit
~/.dsh/generation-image.json. The plugin ships with empty credentials by
default — you supply your own endpoint URL + API key (via the Settings page,
env vars, or the config file):
{
"enabled": true,
"baseUrl": "https://your-image-endpoint.example/v1",
"apiKey": "sk-xxxx",
"model": "gpt-image-2",
"size": "",
"quality": "auto"
}
baseUrl — OpenAI-compatible image API root (.../v1); empty by default,
the plugin normalizes it and calls ${baseUrl}/images/generations or
${baseUrl}/images/edits according to the tool arguments.apiKey / apiKeyEnv — empty by default, mutually exclusive. A directly
entered key is synced to the DSH credential store and referenced as
DSH_GENERATION_IMAGE_API_KEY.model — the image model id (default gpt-image-2).size — default size hint, empty by default = unrestricted: the model
passes any size per call, or "auto" to let the API decide. No value is
hardcoded or restricted.quality — default quality hint: auto (default; omitted from the request,
the API decides) or any value the model/endpoint accepts.enabled: false disables the whole chain: no tool registration, no image
rewriting, no admission bypass (native behavior restored).
Precedence (highest wins): Settings page (with schema defaults) →
environment variables → config file.
Environment overrides: DSH_GENERATION_IMAGE_BASE_URL,
DSH_GENERATION_IMAGE_API_KEY, DSH_GENERATION_IMAGE_API_KEY_ENV,
DSH_GENERATION_IMAGE_MODEL, DSH_GENERATION_IMAGE_SIZE,
DSH_GENERATION_IMAGE_QUALITY, DSH_GENERATION_IMAGE_ENABLED.
generate_image tool
- Arguments
prompt (required): a detailed description of the image to generate;size (optional, unrestricted): pass any size the endpoint accepts
(e.g. 1024x1024, 1024x1792, 1792x1024), or "auto"/omit to let the
API decide;quality (optional, unrestricted): common values are auto (default),
low, medium, high, or any value your endpoint accepts;count (optional, 1–4): how many images to generate (default 1).referenceImageIds (optional): ordered, unique image attachment ids from
the current conversation. Omit for text-to-image; provide one or more for
image-to-image editing or combining references. The deployment's DSH image
count limit applies.
- Behavior: calls the configured image endpoint → parses the SSE stream
(or plain JSON) → sniffs the real media type from magic bytes → durably saves
each image through the DSH attachment service → returns a text envelope plus
one image block per generated image.
- Result: the generated image(s) appear in the session log and Web UI. The
text model receives a text marker instead of the image block.
- Image-to-image usage: upload one or more images and ask to modify,
restyle, or combine them. The bundled Skill extracts their attachment ids and
passes
referenceImageIds. If no reference exists, the agent asks for an
upload instead of silently falling back to text-to-image.
Verify
npm test
The suite covers: tool registration gating, the image-API call (SSE + plain
JSON), multi-reference /images/edits multipart requests, attachment isolation,
canonical value + rendered output, nested run_code behavior,
image-marker rewriting (session log untouched), admission bypass on/off,
tool visibility after downstream filters, disabled behavior, and config/env
precedence.
Development
From a local checkout:
dsh plugin inject /path/to/dsh-generation-image
Search keywords
deepseek · deepseek-harness · dsh · plugin · image generation ·
text-to-image · image-to-image · img2img · generate image · gpt-image · OpenAI-compatible ·
images API · xiaoyaoapi · LLM agent
License
MIT
