One tool, generate_image, turns a text prompt into a picture. SoAI does not generate images itself. It
hands the work to one of three backends and returns the result to the conversation, so the setup effort goes into
the backend rather than into SoAI.
In the SoAI WebUI, open a chat and select Chat configuration in its header, then Tools. Turn on
Tools enabled, select generate_image in Execute mode, and select
Save. The account needs MCP usage (MCP_USE), the selected model must support tool calling,
and the selected image engine must be configured and reachable. Plan mode refuses this destructive tool.
Calling it
Only prompt is required, and the tool contract requires English (even when the user writes in another language). Its description tells the model to
translate or rewrite other languages before calling because non-English prompts can produce poor output. A user can
ask in any language; the prompt sent to the backend should be English.
| Argument | Range | Default |
|---|---|---|
prompt |
1 to 2000 characters | Required |
negative_prompt |
Up to 2000 characters | TOOLS.MCP.GENERATE_IMAGE.NEGATIVE_PROMPT, empty |
width, height |
64 to 2048, in steps of 8 | 704 by 704 |
steps |
1 to 150 | 20 |
cfg_scale |
1.0 to 30.0 | 7.0 |
seed |
0 to 2,147,483,647 | Random |
A fixed seed asks the selected engine for deterministic generation. Reproducibility still depends on
the same backend, model, workflow, and engine version. The catalog requires approval for this tool, so with
when Require tool approval is on, you see the prompt before anything is generated.
The three backends
| Engine | Runs where | Trade-off |
|---|---|---|
| AI Horde | Somebody else's GPU, via a volunteer network | No local GPU needed. You queue behind other people and wait. |
| Automatic1111 | Your machine, on your GPU | The default. Widely documented, and the simplest to point SoAI at. |
| ComfyUI | Your machine, on your GPU | Node graphs give far more control, and need a workflow exported first. |
An administrator with Configuration changes (CONFIG_PATCH) chooses one through
TOOLS.MCP.GENERATE_IMAGE.ENGINE:
select the Settings button at the right of the header, then Settings, then select
Advanced in the Settings page header. The page becomes Advanced settings and the
control changes to Basic. Search for the key, choose an engine, and select Save.
Each engine reads its own block of settings, so switching back and forth does not mean re-entering them.
Automatic1111
Start Automatic1111 with its API enabled, then set
TOOLS.MCP.GENERATE_IMAGE.AUTOMATIC1111.BASE_URL. The default already points at
http://127.0.0.1:7860, so a local install on the standard port needs nothing changed. The remaining
controls in that block cover basic authentication, sampler and scheduler selection, and extra API parameters.
ComfyUI
ComfyUI needs more than a URL because the graph is the configuration. Build your workflow in ComfyUI, export it in
API format, and paste it into TOOLS.MCP.GENERATE_IMAGE.COMFYUI.WORKFLOW_JSON. In
TOOLS.MCP.GENERATE_IMAGE.COMFYUI.WORKFLOW_NODES, add mapping objects that name a node, its input field,
and the request value to insert. Supported values include the prompt, negative prompt, dimensions, steps, guidance
scale, seed, model, and a literal. Use TOOLS.MCP.GENERATE_IMAGE.COMFYUI.OUTPUT_NODE_IDS to prefer
particular output nodes. When that list is empty, SoAI scans every output for the first image.
AI Horde
AI Horde runs on donated GPUs. Leave TOOLS.MCP.GENERATE_IMAGE.AI_HORDE.API_KEY empty and SoAI uses the
shared anonymous key. SoAI limits anonymous requests to nine per minute. A registered key avoids that local
anonymous limit, but the provider still schedules work through its queue. Set
TOOLS.MCP.GENERATE_IMAGE.AI_HORDE.MODEL to a model the network currently offers, and expect long waits
when it is busy. TOOLS.MCP.GENERATE_IMAGE.AI_HORDE.MAX_GENERATION_WAIT_SEC gives up after an hour by
default.
This is the one engine that sends your prompts to a third party. Every prompt goes to a volunteer's machine, so keep private or identifying detail out of them.
Shared settings
| Setting | Default | What it does |
|---|---|---|
TOOLS.MCP.GENERATE_IMAGE.BLOCK_PRIVATE_NETWORK_EGRESS |
true |
Blocks private addresses, with an exception for local endpoints |
TOOLS.MCP.GENERATE_IMAGE.ENABLED |
true |
Off means the tool refuses to run and names the key |
TOOLS.MCP.GENERATE_IMAGE.ENGINE |
Automatic1111 | Which backend to use |
TOOLS.MCP.GENERATE_IMAGE.MAX_IMAGE_BYTES |
128 MiB | Largest image SoAI will accept back |
TOOLS.MCP.GENERATE_IMAGE.POLL_INTERVAL_SEC |
1.0 |
How often SoAI checks a queued job |
TOOLS.MCP.GENERATE_IMAGE.TIMEOUT_SEC |
3600 |
Ceiling on one generation |
Local endpoint policy
TOOLS.MCP.GENERATE_IMAGE.BLOCK_PRIVATE_NETWORK_EGRESS defaults to true, and both local
engines default to a 127.0.0.1 address. The endpoint policy treats loopback differently from other
private addresses.
SoAI treats an endpoint that resolves to the local machine as local and allows it over plain
http://. It requires https:// for any other host. While the private-network block is on,
SoAI also rejects hosts in private address ranges. A local Automatic1111 or ComfyUI works out of the box, as does a
remote service over HTTPS. Another machine on your LAN requires you to turn the block off.