@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](./LICENSE)