Skip to main content

Image uploads with opencode-vision-bridge

Z-Code is a text-only model, so OpenCode normally errors when you attach an image to the conversation. The opencode-vision-bridge plugin fixes this — it intercepts images before they reach the model, sends them to a vision model, and replaces them in place with a text description. The text model then just sees prose, fully transparent.

How it works​

  1. You attach an image to your conversation.
  2. The plugin detects the image and sends it to a vision model (zeldoc/gemma-4-31b by default, via https://api.zeldoc.ai/v1).
  3. The vision model returns a text description.
  4. The image is replaced in place with the description — the text model never sees the raw image.

If the vision call fails, the model receives a short [Image: description unavailable] marker instead of an error. Error details go to the log only.

Install​

Add the plugin to your opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-vision-bridge"]
}

OpenCode installs the plugin automatically on next launch.

ZELDOC_API_KEY must be set

The plugin uses your ZELDOC_API_KEY environment variable to call the vision model. Make sure it's exported before starting OpenCode:

export ZELDOC_API_KEY=your-api-key

Without it, the plugin can't describe images and you'll see [Image: description unavailable] instead.

For configuration options, see the README on GitHub.

Troubleshooting: plugin fails to install​

If OpenCode can't install the plugin, check your ~/.npmrc for a min-release-age setting:

min-release-age=7

This prevents npm from installing packages published within the last 7 days. Since opencode-vision-bridge is new, the install will fail until the package is older than your threshold.