dsh-fal-image-gen

Image generation for DeepSeek Harness (dsh): a generate_image tool with pluggable providers — the FAL REST queue API (default model fal-ai/flux-2/klein/9b) or any OpenAI-compatible images API.

A generated image is:

• shown inline in the conversation, in the plugin's own tool card;
• saved into the session working directory (<session cwd>/generated/images/*.png);
• returned to the model with its path, size and seed.

Providers

provider	What it is	Protocol
fal (default)	the FAL queue	submit, poll, download
custom	any OpenAI-compatible API	POST {customBaseURL}/images/generations, one request

The named sizes stay the same whichever provider runs — they are the tool's language. FAL takes them as they are; for an OpenAI-compatible API they are translated (square_hd → 1024x1024, landscape_4_3 → 1024x768, and so on). An API picky about sizes gets customSize, which is sent verbatim instead.

response_format is deliberately not sent: newer OpenAI models reject it, and the answer is accepted either way — base64 inline, or a link that gets downloaded.

Example: OpenAI

- id: dsh-fal-image-gen
  config:
    provider: custom
    customBaseURL: https://api.openai.com/v1
    customModel: gpt-image-1
    customKeyEnv: OPENAI_API_KEY

An empty customKeyEnv means no authorization header at all, for a local gateway that needs none.

Two delivery modes

The picture appears in the conversation either way. What differs is what the chat model receives — and that decides whether the turn survives a text-only model.

	link (default)	image
The model receives	text and a link	the image itself
Shown in the chat	yes, the card renders it from the link	yes
Works with a text-only chat model	yes, on its own	no — needs dsh-vision-bridge or a vision-capable chat model
The model can reason about the picture	no, only about the prompt and the link	yes
The link points to	this plugin's own route, as durable as the attachment	fal.media, which expires

Pick image when the conversation should be able to discuss what was drawn — "make the cat bluer" needs a model that can actually see it. Without a vision model in the chat that mode fails the turn with does not support image input, which is precisely what dsh-vision-bridge exists to prevent: it swaps the picture for a description from a vision model you choose.

Set it in Settings → Plugins → FAL Image Generation → How the image reaches the chat, or in the profile:

- id: dsh-fal-image-gen
  config:
    deliverAs: image

Install

# From npm after publishing:
dsh plugin --profile web add @goodandready/dsh-fal-image-gen

# From GitHub:
dsh plugin --profile web add github:GooDAnDReaDY/dsh-fal-image-gen

# Locally from a checkout:
dsh plugin --profile web add /path/to/dsh-fal-image-gen

Restart the Web UI afterwards.

Configure (Web GUI)

All settings live in Settings → Plugins → Plugin configuration → FAL Image Generation:

Field	Default	Description
provider	fal	Which provider generates the image: fal or custom.
model	fal-ai/flux-2/klein/9b	FAL model id, called as {baseURL}/{model}. Used when provider is fal.
apiKeyEnv	FAL_API_KEY	API key reference (credentials / env var).
baseURL	https://queue.fal.run	FAL queue base URL.
defaultSize	landscape_4_3	Default image size.
defaultFormat	png	Default output format.
pollIntervalMs	2000	Job status poll interval.
timeoutMs	180000	Total generation timeout.
deliverAs	link	link — the result is text with a link, works with any chat model. image — the result carries the picture, needs dsh-vision-bridge or a vision-capable model.
customBaseURL	—	provider=custom: API root, e.g. https://api.openai.com/v1.
customModel	—	provider=custom: model id, e.g. gpt-image-1.
customKeyEnv	OPENAI_API_KEY	provider=custom: key reference. Empty means no authorization header.
customSize	—	provider=custom: fixed size sent verbatim. Empty means the named size is translated.
outputDir	generated/images	Output folder. A relative path resolves against the session working directory; an absolute path is used as given.

Equivalent values can be set in $DSH_HOME/settings.yaml under dsh-fal-image-gen: — the GUI writes to the same settings document, so both ways are equivalent.

API key

Store your key in Credentials (Web: Settings → Credentials, name FAL_API_KEY) or in $DSH_HOME/.credentials.yaml:

FAL_API_KEY: <your key from https://fal.ai/dashboard/keys>

The plugin prepends the Key auth prefix automatically.

Usage

Just ask the model to draw an image:

Generate an image: neon cyberpunk city at night in the rain, 16:9

Tool parameters (all except prompt are optional):

Parameter	Description
prompt	required, detailed image description
image_size	square_hd / square / portrait_4_3 / portrait_16_9 / landscape_4_3 / landscape_16_9
seed	seed for reproducibility
output_format	png (default) / jpeg / webp
output_name	file name without extension

Structure

dsh-fal-image-gen/
├── package.json            # dsh bundle/plugin metadata + peerDependencies
├── cordis.patch.yml        # bundle layer: inserts the plugin row
├── lib/index.js            # host: generate_image tool, attachment and file handling
├── lib/providers.js        # host: the providers — FAL queue, OpenAI-compatible API
├── lib/client.js           # browser: settings card + the generate_image tool card
├── test/                   # unit tests for the providers, on a fake fetch
├── README.md
└── LICENSE                 # MIT

Why the plugin ships its own tool card

Tool cards in dsh do not render image blocks — only user and assistant messages do — so a picture returned by a tool would otherwise show up as JSON. The plugin registers a keyed tool.call.toolview entry for generate_image and serves the stored bytes from its own route (GET /dsh-fal-image-gen/image), which is what puts the image in the conversation.

No npm runtime dependencies (the @deepseek-ai/* peer deps resolve from the dsh install), no build step — plain ESM.

License

MIT