Build a Hermes Image Generation Provider Plugin

Add an image backend behind the shared image_generate tool with capability-aware routing, normalized responses, and setup-ready model metadata. This guide focuses on the public implementation contract; the official Hermes documentation remains the source of truth as interfaces evolve.

How the interface works

Image providers subclass the image-generation provider contract, register through ctx.register_image_gen_provider(...), and are selected by image_gen.provider.

The required surface is a stable name and generate(). Production-quality providers also expose availability, display metadata, model catalogs, a default model, setup fields, and capabilities such as image editing or reference-image limits.

Text-to-image and image-to-image share one tool. The provider decides the route from image_url and reference images, then reports the modality actually used.

Return standardized success or error responses. Remote URLs may be returned directly; base64 output should be materialized through the host helper into the Hermes image cache.

Practical checklist

Declare real modalities and reference-image limits.
Resolve aspect ratio and model selection before calling the backend.
Reject empty prompts and normalize reference inputs.
Keep credentials in setup-managed environment values.
Inspect generated pixels independently before treating an asset as publication-ready.

Common pitfalls

Advertising image editing when the backend ignores source images.
Hand-rolling inconsistent response dictionaries.
Leaving base64 blobs in logs or tool output instead of saving them safely.
Equating API success with a visually usable image.

Verification steps

Select the backend and model through hermes tools.
Test one text-to-image call and every advertised image-input path.
Exercise missing-auth and invalid-prompt cases.
Verify the returned URL or local file opens, has expected dimensions, and contains no unintended text or artifacts.

Official reference

https://hermes-agent.nousresearch.com/docs/developer-guide/image-gen-provider-plugin