DeepSeek Harness Plugin: dsh-tool-imagegen

Introduction¶

The plugin mechanism in DeepSeek Harness (DSH) allows developers to extend functionality and enhance workflows. For agents or workflows that require visual output, the dsh-tool-imagegen plugin provides a solution. It integrates text-to-image and image-to-image capabilities into DSH through OpenRouter’s unified image generation API.

Core Scope¶

Author: Pappet
License: MIT
Features: Text-to-image and image-to-image generation
Dependencies: Node.js >= 22.19
Interface: OpenRouter’s POST /api/v1/images (a non-OpenAI-compatible endpoint)

Installation¶

Run the following command in your terminal to install the plugin for the web profile:

dsh plugin --profile web add dsh-tool-imagegen

After installation, the plugin appears in dsh.profile.bundles and automatically inserts a plugin entry.

Configuration and Enablement¶

After installing the plugin, configure the API key. Storing the key in a credentials file is recommended; environment variables are the secondary option.

Configure credentials: Add the following to $DSH_HOME/.credentials.yaml:

   refs:
     OPENROUTER_API_KEY: sk-or-...

Or export the environment variable in your shell:

   export OPENROUTER_API_KEY=sk-or-...

Configure aliases and parameters: Add configuration overrides in cordis.patch.yml. Because configuration uses whole-entry replacement rather than deep merging, all keys that need to be overridden must be listed explicitly. Example configuration:

   - id: imagegen
     config:
       apiKeyEnv: OPENROUTER_API_KEY
       baseURL: https://openrouter.ai/api/v1
       outputDir: .dsh/images
       defaultModel: seedream
       capabilityTtlMs: 86400000
       maxImagesPerCall: 4
       maxReferenceBytes: 8388608
       maxReferenceTotalBytes: 33554432
       showInChat: true
       models:
         seedream:
           id: bytedance-seed/seedream-4.5
           defaults: { resolution: "2K", aspect_ratio: "16:9" }

Usage¶

In DSH conversations or tool calls, you can invoke the generate_image tool using JSON.

Basic Text-to-Image¶

{
  "prompt": "一只在太空中的猫",
  "model": "seedream"
}

Image-to-Image¶

Pass file paths or URLs through the input_references parameter:

{
  "prompt": "Turn this into a soft watercolor painting, same composition.",
  "input_references": ["bilder/vorlage.png", "https://example.com/style.jpg"]
}

Key Features and Notes¶

1. Model Aliases and Capability Gating¶

Model aliases are not just a vocabulary; they also act as an allowlist. The plugin dynamically validates parameters based on the model’s capability records (GET /api/v1/images/models) rather than using hardcoded assumptions. If the model does not support a requested parameter (for example, unsupported resolution), it returns a specific error message.

2. Output Path and Encoding¶

The file extension in output_path is advisory only. The actual encoding format is determined by the model. For example, if you request a .png but the model returns JPEG, the file name is renamed to .jpg. The plugin does not fail because of a mismatched file name.

3. Configuration Override Mechanism¶

Configuration overrides in cordis.patch.yml perform whole-entry replacement rather than deep merging. This means that if a key is not listed, it uses the default value for that entry instead of inheriting a value from other configurations.

4. Runtime Editability¶

The plugin registers a settings card in the browser, allowing aliases and tunable parameters to be edited at runtime without restarting the DSH process.

5. Image Reference Handling¶

Image references (input_references) support workspace paths or URLs. The plugin detects the format by reading a file’s magic bytes, ignoring the file extension. The number and size of reference images are constrained by model capabilities (for example, Seedream 4.5 supports 14 images, while the GPT-Image series supports 16 images).

Summary¶

dsh-tool-imagegen is a tool for integrating OpenRouter image generation capabilities into DeepSeek Harness. Through dynamic capability checking and flexible configuration, it enables developers to directly generate and edit images within agent workflows.