Image generation & Vision mode

Sonderr generates and edits images the same way it does everything else — through one explicit tool, one explicit permission path, and delivery you can actually keep. This page explains how image work flows end to end: what triggers it, what it costs you (nothing), where the pixels come from, and the exact boundaries that keep it from doing anything surprising.

1 · One tool, one job

All image work in Sonderr runs through a single tool: edit_image. There is no hidden generation path, no side channel, no “the model drew something in the transcript.” When Sonderr produces or edits an image, that tool ran, and its result arrives as a download card in the chat with an inline preview panel — presented automatically, alongside reports, exports and any other deliverable, so the finished image is one click from your file system.

The tool takes two arguments. prompt — the complete description of the desired image or edit — and an optional source_path pointing at an existing workspace or uploaded image to edit instead of generate. That’s the whole surface. Everything else is policy.

2 · What has to be true before pixels happen

Three gates must all pass, and Sonderr will name the missing one if you ask it to draw without meeting them:

• Vision mode is selected. The composer’s task mode is set to Vision — the mode built for attached-image understanding and image work. Ask and Plan never generate; Build handles code, not canvases.
• Tools & Access permits it. The access level selected in Settings must actually expose the edit_image schema. If it isn’t supplied, Sonderr explains the boundary instead of claiming the tool is broken.
• Your current message asks for it. Image analysis alone, a how-to question about prompting, or last week’s “make me a logo” does not authorize a generation. A direct affirmative image request in the present message is required — the same present-turn rule that guards email, wallet and MCP actions.

This is deliberate friction. The strongest image models in a provider catalog sit one mistaken click away from a surprise render, and the three-gate design means generation only ever happens as an explicit, visible, current decision.

3 · Prompts that work

The instruction baked into the tool is worth following even when you’re prompting other tools: put the complete desired result in the prompt. Not “a website banner” but “a wide dark banner for a security company, blue hexagonal emblem on the right third, subtle grid texture, no text.” When editing, the prompt must carry over the details that must survive — the runtime does not silently preserve anything you don’t restate, which is the honest way to run an edit endpoint.

# a generation
prompt: "Minimal line-art logo of a lighthouse holding a beam, single continuous stroke,
blue #1a73e8 on white, vector style, generous whitespace"

# an edit of last week's poster
prompt: "Same layout, same palette and same headline placement as the source image,
but replace the background photo with a flat dark gradient and remove the grain."

4 · Editing existing images

Pass source_path and the call becomes an image-to-image edit: uploaded photos and anything already in the workspace both work. Under the hood that routes to the provider’s multipart /images/edits endpoint with the source file attached; omit source_path and it’s a text-to-image call against /images/generations. Both endpoints are the OpenAI-compatible image API — which means image capability depends on the selected model and provider. Pick a model whose endpoint doesn’t expose an images API and Sonderr returns a clear, bounded error explaining exactly that, rather than a silent failure or a hallucinated picture.

5 · Where delivered images come from — and what Sonderr will fetch

Generated images are delivered locally as files and download cards. When a workflow needs to fetch an image from the web — a reference, an asset, a remote render URL — the fetcher is pinned: public HTTPS only, resolved against DNS answers already validated as public (no rebinding between check and connection), strict image content types, and a 16 MB cap. Private addresses and credential-bearing links are rejected before a byte is rendered. The same discipline applies to provider-returned image URLs — they are fetched through that pinned path, never trusted blind.

6 · Vision mode boundaries

Vision mode is deliberately narrow, and the system guidance the model receives says so out loud: use the attached image for visual questions; edit_image is the only image-work tool and only if it was actually supplied; file, shell, web and workspace inspection tools are not available in Vision. The model is explicitly instructed never to claim it inspected workspace files in Vision, never to switch your mode itself, and — if your request crosses a boundary — to name the exact mode or access setting needed and say what it can still do now. Refusals are final for that route: a denied generation cannot be retried sideways through another tool or a shell command.

7 · When something doesn’t work

• “No image tool available” — Vision isn’t selected, or Tools & Access doesn’t expose edit_image. Fix the selector or the access level; Sonderr will tell you which one is missing.
• “The current model can’t generate images” — the active provider/model pair has no images endpoint. Switch models in the picker.
• Edit came out “different than asked” — the prompt didn’t restate what to keep. Redo it carrying over the surviving details explicitly.
• Remote image refused — non-HTTPS, private host, wrong content type or over 16 MB. That’s the fetcher holding its line, not a bug.