ouyangbo/hermes-agent
1
0
Fork 0
Code Issues Pull Requests Actions 10 Packages Projects Releases Wiki Activity
Files
cf60ebbdfd264c3fc067b9e3230df8752c50d2ec
hermes-agent/plugins/image_gen/openrouter/__init__.py
T

1148 lines
47 KiB
Python
Raw Blame History

"""OpenRouter-compatible image generation backend (OpenRouter + Nous Portal).
Both OpenRouter and the Nous Portal inference endpoint speak the same
OpenAI-style ``/chat/completions`` image-generation protocol: send
``modalities: ["image", "text"]`` with an image-output model, pass reference
images as ``image_url`` content parts for grounding, and read generated
images back from ``choices[0].message.images[].image_url.url`` (a base64 data
URI). Nous Portal proxies OpenRouter, so one implementation services both —
only the resolved ``(base_url, api_key)`` differs, obtained through
:func:`~hermes_cli.runtime_provider.resolve_runtime_provider` (which already
understands OpenRouter's key pool and the Nous OAuth token).
Reference grounding matters for pet sprite generation: every animation row
must stay the same character as the base frame, which only works on models
that accept image input.
Two request surfaces
--------------------
OpenRouter also ships a separate **Dedicated Image API** at
``POST /api/v1/images/generations`` with its own catalog
(``GET /api/v1/images/models``) and the full OpenAI-style parameter set;
``openai/gpt-image-2``, ``krea/krea-2-*``, ``qwen/qwen-image-3-pro``,
``microsoft/mai-image-2.5*`` … are reachable *only* there.
Routing is not "is it in the image catalog?" — the two catalogs overlap and
``/images/models`` lists this backend's own chat-completions defaults. Routing
on membership alone would silently move every default call off
``/chat/completions`` and change how references are passed (content parts vs
``input_references``). So :func:`_select_surface` decides conservatively:
``image_gen.openrouter.surface`` / ``OPENROUTER_IMAGE_API_SURFACE`` force a
surface; otherwise curated :data:`_IMAGE_API_MODELS` take the Image API, the
chat defaults stay pinned to chat-completions, and an id in neither table is
checked against the cached live catalog. On the Image API path the request
gains exact per-model aspect ratios plus ``resolution`` / ``quality`` /
``background`` / ``seed`` / ``n`` / ``output_compression`` and up to 16
reference images instead of 3.
The Image API is OpenRouter-only: Nous Portal has no ``/images/generations``
route, so the surface is enabled per provider (``supports_image_api``).
"""
from __future__ import annotations
import base64
import json
import logging
import mimetypes
import os
import time
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple
from agent.image_gen_provider import (
DEFAULT_ASPECT_RATIO,
ImageGenProvider,
error_response,
resolve_aspect_ratio,
save_b64_image,
save_url_image,
success_response,
)
from plugins.image_gen._common import (
HttpFailure as HttpFailure,
error_factory,
load_image_gen_config,
post_json,
)
logger = logging.getLogger(__name__)
# Quality-first default chain: try the highest-fidelity OpenAI image model,
# then fall back to Gemini 3 Pro Image if it is access-gated / unavailable /
# times out. Any explicit override (env, scoped config, or ``image_gen.model``
# from ``hermes tools``) means "use exactly that model", no auto fallback.
DEFAULT_MODEL = "openai/gpt-5.4-image-2"
_FALLBACK_MODEL = "google/gemini-3-pro-image"
_DEFAULT_MODEL_CHAIN = (DEFAULT_MODEL, _FALLBACK_MODEL)
_MODEL_PRIORITY = {DEFAULT_MODEL: 0, _FALLBACK_MODEL: 1}
# Semantic aspect ratio → OpenRouter ``image_config.aspect_ratio``.
_ASPECT_RATIOS = {"square": "1:1", "landscape": "16:9", "portrait": "9:16"}
# Gemini Flash Image accepts up to 3 input images per prompt.
_MAX_REFERENCE_IMAGES = 3
# Per single image call. The quality-first default is genuinely slow — a cold
# row can run past 3 minutes — so give each call real headroom before we treat
# it as hung and fall back / retry.
_REQUEST_TIMEOUT = 300.0
# Curated metadata for well-known chat-completions image models; anything else
# discovered via the live catalog gets a generic strengths line.
_KNOWN_MODEL_META = {
DEFAULT_MODEL: {
"display": "OpenAI GPT-5.4 Image 2",
"strengths": "Highest fidelity; best prompt adherence; slower on OpenRouter",
},
_FALLBACK_MODEL: {
"display": "Gemini 3 Pro Image",
"strengths": "Fast, reliable fallback with good layout adherence",
},
}
# Router pseudo-models advertise image output but are not image models.
_EXCLUDED_MODEL_PREFIXES = ("openrouter/auto",)
_LIVE_CACHE_TTL = 300.0
_LIVE_TIMEOUT = 10.0
_load_image_gen_config = load_image_gen_config
def _to_image_url_part(ref: str) -> Optional[str]:
"""Turn a reference (local path or http URL) into an ``image_url`` value.
Remote URLs pass through; local files are inlined as base64 data URIs so
the request is self-contained. ``None`` when the reference can't be read.
"""
ref = str(ref or "").strip()
if not ref:
return None
if ref.startswith(("http://", "https://", "data:")):
return ref
path = Path(ref)
# Enforce the shared credential-read guard before inlining local bytes.
from agent.file_safety import raise_if_read_blocked
raise_if_read_blocked(ref)
try:
raw = path.read_bytes()
except OSError as exc:
logger.debug("could not read reference image %s: %s", ref, exc)
return None
mime = mimetypes.guess_type(path.name)[0] or "image/png"
return f"data:{mime};base64,{base64.b64encode(raw).decode('ascii')}"
def _extract_images(payload: Dict[str, Any]) -> List[str]:
"""Generated image URLs from ``choices[].message.images[].image_url.url``."""
out: List[str] = []
choices = payload.get("choices") if isinstance(payload, dict) else None
for choice in choices if isinstance(choices, list) else []:
message = choice.get("message") if isinstance(choice, dict) else None
images = message.get("images") if isinstance(message, dict) else None
for image in images if isinstance(images, list) else []:
image_url = image.get("image_url") if isinstance(image, dict) else None
url = image_url.get("url") if isinstance(image_url, dict) else None
if isinstance(url, str) and url.strip():
out.append(url.strip())
return out
def _access_error_hint(
display: str, model_id: str, env_var: str, status: int, err_msg: str
) -> Optional[str]:
"""One actionable line when an access-gated OpenAI image model is unreachable.
Some OpenAI image models on OpenRouter need account enablement / BYOK, so
the key is valid but the *model* is unreachable and "check your key" would
mislead. ``None`` when this isn't that case.
"""
if not model_id.startswith("openai/"):
return None
low = (err_msg or "").lower()
gated = status in (402, 403, 404) or any(
s in low for s in ("no endpoints", "no allowed", "not a valid model", "data policy")
)
if not gated:
return None
return (
f"{display} can't reach image model '{model_id}' ({status}) — enable OpenAI "
f"image access in your {display} account, or set {env_var}={_FALLBACK_MODEL}."
)
def _fetch_catalog(
base_url: str, api_key: str, *, path: str, meta: Dict[str, Dict[str, Any]],
generic: str, image_output_only: bool,
) -> List[Dict[str, Any]]:
"""Picker rows from ``GET {base_url}{path}``; raises on failure.
``image_output_only`` keeps entries whose ``architecture.output_modalities``
includes ``image`` and drops router pseudo-models. Curated ``meta`` wins
for known ids; unknown ones get the API name and ``generic`` strengths.
"""
import requests
response = requests.get(
f"{base_url}{path}",
headers={"Authorization": f"Bearer {api_key}"} if api_key else {},
timeout=_LIVE_TIMEOUT,
)
response.raise_for_status()
out: List[Dict[str, Any]] = []
for entry in response.json().get("data") or []:
if not isinstance(entry, dict):
continue
model_id = entry.get("id")
if not isinstance(model_id, str) or not model_id.strip():
continue
model_id = model_id.strip()
arch_raw = entry.get("architecture")
arch: Dict[str, Any] = arch_raw if isinstance(arch_raw, dict) else {}
if image_output_only and (
model_id.startswith(_EXCLUDED_MODEL_PREFIXES)
or "image" not in (arch.get("output_modalities") or [])
):
continue
known = meta.get(model_id, {})
out.append({
"id": model_id,
"display": known.get("display", entry.get("name") or model_id),
"strengths": known.get("strengths", generic),
"input_modalities": arch.get("input_modalities") or [],
})
return out
# ===========================================================================
# OpenRouter Dedicated Image API (POST /images/generations)
# ===========================================================================
#: Env prefix for the Image API knobs (``OPENROUTER_IMAGE_API_QUALITY`` …),
#: distinct from ``OPENROUTER_IMAGE_MODEL`` which selects the model on either surface.
_IMAGE_API_ENV_PREFIX = "OPENROUTER_IMAGE_API_"
#: Connect budget, separate from the read budget: if DNS + TCP + TLS hasn't
#: completed in 20s the endpoint is down, and waiting out the generation
#: timeout only delays the error.
_IMAGE_API_CONNECT_TIMEOUT = 20.0
#: How long a fetched ``/images/models`` catalog stays usable. It only grows,
#: and a stale entry costs one wasted 404 at worst.
_CATALOG_TTL_SECONDS = 900.0
#: Cached catalog probes keyed by base URL: ``(fetched_at, model_ids)``. Empty
#: sets are cached too, so a failing endpoint is probed once per TTL.
_CATALOG_CACHE: Dict[str, Tuple[float, frozenset]] = {}
_GEMINI_RATIOS = (
"1:1", "1:4", "1:8", "2:3", "3:2", "3:4", "4:1", "4:3",
"4:5", "5:4", "8:1", "9:16", "16:9", "21:9",
)
_MAI_RATIOS = ("1:1", "4:3", "3:4", "16:9", "9:16", "3:2", "2:3", "auto")
_KREA_RATIOS = ("1:1", "4:3", "3:2", "16:9", "4:5", "2:3", "9:16")
_NO_KNOBS = {"quality": (), "background": (), "output_format": (), "compression": False, "seed": False}
def _image_api_model(display: str, strengths: str, **spec: Any) -> Dict[str, Any]:
"""Curated Image API model entry; unspecified knobs default to "not supported"."""
return {"display": display, "strengths": strengths, **_NO_KNOBS, "resolutions": (), **spec}
#: Curated Image API models and the parameters each declares in
#: ``GET /images/models``. The catalog is larger and keeps growing; an id
#: missing here still works — it just gets no per-model parameter filtering
#: and costs one cached catalog probe to recognise. Keys mirror the payload
#: field they gate; an empty tuple means the model has no such knob.
_IMAGE_API_MODELS: Dict[str, Dict[str, Any]] = {
"google/gemini-3.1-flash-lite-image": _image_api_model(
"Nano Banana 2 Lite (Gemini 3.1 Flash Lite Image)",
"Cheap and fast; 14 exact aspect ratios; 14 reference images",
aspect_ratios=_GEMINI_RATIOS, resolutions=("1K",), max_n=1, max_refs=14,
),
"google/gemini-3.1-flash-image": _image_api_model(
"Nano Banana 2 (Gemini 3.1 Flash Image)",
"Same ratios as Lite plus resolution control (512/1K/2K/4K)",
aspect_ratios=_GEMINI_RATIOS, resolutions=("512", "1K", "2K", "4K"), max_n=1, max_refs=14,
),
"openai/gpt-image-2": _image_api_model(
"OpenAI GPT Image 2",
"Best editing fidelity; up to 16 references; strongest prompt adherence",
aspect_ratios=("1:1", "3:2", "2:3", "4:3", "3:4", "16:9", "9:16", "21:9", "auto"),
quality=("auto", "low", "medium", "high"), background=("auto", "opaque"),
compression=True, max_n=10, max_refs=16,
),
"openai/gpt-image-1-mini": _image_api_model(
"OpenAI GPT Image 1 Mini",
"The only model here with background=transparent (cut-out PNG)",
aspect_ratios=("1:1", "3:2", "2:3", "auto"),
quality=("auto", "low", "medium", "high"), background=("auto", "transparent", "opaque"),
compression=True, max_n=10, max_refs=16,
),
"microsoft/mai-image-2.5": _image_api_model(
"Microsoft MAI-Image-2.5", "Standard ratios; a good second opinion next to Gemini",
aspect_ratios=_MAI_RATIOS, max_n=1, max_refs=1,
),
"microsoft/mai-image-2.5-pro": _image_api_model(
"Microsoft MAI-Image-2.5 Pro", "Reach for it when gpt-image-2 misses the brief",
aspect_ratios=_MAI_RATIOS, max_n=1, max_refs=1,
),
"x-ai/grok-imagine-image-quality": _image_api_model(
"Grok Imagine (Image Quality)",
"Photoreal; widest exotic-ratio set (9:19.5, 20:9, 2:1 …); 1K/2K",
aspect_ratios=(
"1:1", "3:4", "4:3", "9:16", "16:9", "2:3", "3:2",
"9:19.5", "19.5:9", "9:20", "20:9", "1:2", "2:1", "auto",
),
resolutions=("1K", "2K"), max_n=1, max_refs=3,
),
"krea/krea-2-medium": _image_api_model(
"Krea 2 Medium", "Realistic, expressive styles; deterministic via seed",
aspect_ratios=_KREA_RATIOS, resolutions=("1K",), seed=True, max_n=1, max_refs=1,
),
"krea/krea-2-medium-turbo": _image_api_model(
"Krea 2 Medium Turbo", "Cheapest here — bulk content, cards, thumbnails; seed support",
aspect_ratios=_KREA_RATIOS, resolutions=("1K",), seed=True, max_n=1, max_refs=1,
),
"qwen/qwen-image-3-pro": _image_api_model(
"Qwen Image 3 Pro", "Precise small text and detail rendering; n up to 6; 1K/2K; seed",
aspect_ratios=(
"1:1", "1:2", "1:4", "2:1", "2:3", "3:2", "3:4",
"4:1", "4:3", "4:5", "5:4", "9:16", "16:9",
),
resolutions=("1K", "2K"), seed=True, max_n=6, max_refs=4,
),
}
#: Applied to a catalog model the table doesn't describe, so a newly released
#: id still generates. Empty ``aspect_ratios`` means "enum unknown" and the
#: field is omitted rather than guessed.
_UNKNOWN_IMAGE_API_MODEL = _image_api_model("", "", aspect_ratios=(), max_n=1, max_refs=16)
#: Union of exact ratios the endpoint's validator accepts across all models;
#: sanity-checks an override aimed at a model whose own enum we don't know.
_ENDPOINT_ASPECT_RATIOS = frozenset({
"1:1", "1:2", "1:4", "1:8", "2:1", "2:3", "3:2", "3:4", "4:1", "4:3",
"4:5", "5:4", "8:1", "9:16", "16:9", "9:19.5", "19.5:9", "9:20", "20:9",
"9:21", "21:9", "auto",
})
#: Semantic ratio → exact ratios, best first. ``landscape`` lands on 16:9 where
#: it exists and degrades to 3:2 on ``gpt-image-1-mini``, which has no 16:9.
_ASPECT_PREFERENCES: Dict[str, Tuple[str, ...]] = {
"landscape": ("16:9", "3:2", "4:3", "5:4", "21:9", "2:1", "19.5:9", "20:9", "4:1", "8:1"),
"portrait": ("9:16", "2:3", "3:4", "4:5", "9:21", "1:2", "9:19.5", "9:20", "1:4", "1:8"),
"square": ("1:1",),
}
_MEDIA_TYPE_EXTENSIONS = {
"image/png": "png",
"image/jpeg": "jpg",
"image/jpg": "jpg",
"image/webp": "webp",
"image/gif": "gif",
"image/svg+xml": "svg",
}
#: HTTP statuses worth retrying on the next model of the chain. 400 is our own
#: payload and would repeat; 401/403 are account-level and answered before this
#: set is consulted. 502 matters because the Image API bills all-or-nothing and
#: reports a failed (unbilled) generation that way.
_IMAGE_API_FALLBACK_STATUSES = frozenset({402, 404, 408, 409, 425, 429, 500, 502, 503, 504})
#: Ids that stay on ``/chat/completions`` whatever the image catalog says —
#: they are this backend's tested defaults (see the module docstring).
_CHAT_ONLY_MODELS = frozenset({DEFAULT_MODEL, _FALLBACK_MODEL})
def _image_api_model_meta(model_id: str) -> Dict[str, Any]:
"""Catalog metadata for *model_id*, or permissive defaults when unknown."""
return _IMAGE_API_MODELS.get(model_id, _UNKNOWN_IMAGE_API_MODEL)
def _fetch_image_api_catalog(base_url: str, api_key: str) -> frozenset:
"""Model ids served by ``GET {base_url}/images/models``, cached per base URL.
Best-effort by design: any failure caches and returns an empty set, which
routes the call to chat-completions. Guessing the other way would send a
chat-completions id to ``/images/generations`` and turn a working setup
into a 404.
"""
import requests
cached = _CATALOG_CACHE.get(base_url)
if cached and (time.monotonic() - cached[0]) < _CATALOG_TTL_SECONDS:
return cached[1]
ids: set = set()
try:
response = requests.get(
f"{base_url}/images/models",
headers={"Authorization": f"Bearer {api_key}"},
timeout=(_IMAGE_API_CONNECT_TIMEOUT, 30.0),
)
response.raise_for_status()
body = response.json()
entries = body.get("data") if isinstance(body, dict) else None
for entry in entries if isinstance(entries, list) else []:
model_id = entry.get("id") if isinstance(entry, dict) else None
if isinstance(model_id, str) and model_id.strip():
ids.add(model_id.strip())
except Exception as exc: # noqa: BLE001 - probe must never break generation
logger.debug("image API catalog probe failed for %s: %s", base_url, exc)
resolved = frozenset(ids)
_CATALOG_CACHE[base_url] = (time.monotonic(), resolved)
return resolved
def _select_surface(model_id: str, base_url: str, api_key: str, config_key: str) -> str:
"""Return ``"images"`` or ``"chat"`` for *model_id*.
Deterministic and offline for curated ids (:data:`_IMAGE_API_MODELS`,
:data:`_CHAT_ONLY_MODELS`). An id in neither table is checked against the
cached live ``/images/models`` catalog — a positive probe must route there,
since staying on chat would 404/400 a model the live picker offered.
Offline the probe is empty and unknown ids stay on chat-completions.
"""
if not model_id:
return "chat"
forced = _image_api_setting("surface", None, config_key)
if isinstance(forced, str) and forced.strip().lower() in {"images", "chat"}:
return forced.strip().lower()
if model_id in _CHAT_ONLY_MODELS:
return "chat"
if model_id in _IMAGE_API_MODELS or model_id in _fetch_image_api_catalog(base_url, api_key):
return "images"
return "chat"
def _image_api_setting(name: str, explicit: Any, config_key: str) -> Any:
"""Resolve one Image API knob: call kwarg → ``OPENROUTER_IMAGE_API_<NAME>``
env → scoped config. Blank strings count as unset."""
if explicit is not None and not (isinstance(explicit, str) and not explicit.strip()):
return explicit
env_value = os.environ.get(f"{_IMAGE_API_ENV_PREFIX}{name.upper()}", "").strip()
if env_value:
return env_value
scoped = _load_image_gen_config().get(config_key)
value = scoped.get(name) if isinstance(scoped, dict) else None
if isinstance(value, str):
return value.strip() or None
return value
def _coerce_int(value: Any) -> Optional[int]:
"""Best-effort int (env vars arrive as strings); ``None`` when not numeric."""
if isinstance(value, bool):
return None
if isinstance(value, int):
return value
if isinstance(value, float):
return int(value)
if isinstance(value, str):
try:
return int(value.strip())
except ValueError:
return None
return None
def _pick_exact_aspect_ratio(
semantic: str,
meta: Dict[str, Any],
forced: Optional[str],
notes: List[str],
) -> Optional[str]:
"""Exact ``aspect_ratio`` to send, or ``None`` to omit it.
*forced* (an exact ratio from config/env/kwarg) wins when the model
supports it; otherwise the downgrade is noted and the per-model mapping of
*semantic* applies.
"""
supported: Tuple[str, ...] = tuple(meta.get("aspect_ratios") or ())
if isinstance(forced, str) and forced.strip():
value = forced.strip()
if (supported and value in supported) or (not supported and value in _ENDPOINT_ASPECT_RATIOS):
return value
notes.append(
f"requested aspect_ratio '{value}' is unsupported by this model; "
f"used the '{semantic}' mapping instead"
)
if not supported:
# Unknown enum: an out-of-enum aspect_ratio is a hard 400 (unlike an
# unknown *parameter*, which the endpoint ignores), so omit the field
# and let the model apply its own default.
notes.append(
"model is not in this backend's catalog, so its aspect_ratio enum is "
f"unknown; the field was omitted and '{semantic}' was not applied"
)
return None
for candidate in _ASPECT_PREFERENCES.get(semantic, ()):
if candidate in supported:
return candidate
return "auto" if "auto" in supported else supported[0]
def _image_api_enum(
name: str,
explicit: Any,
meta: Dict[str, Any],
config_key: str,
notes: List[str],
*,
meta_key: Optional[str] = None,
) -> Optional[str]:
"""Resolve an enum knob and drop it when this model doesn't accept it."""
value = _image_api_setting(name, explicit, config_key)
if not isinstance(value, str) or not value.strip():
return None
value = value.strip()
allowed: Tuple[str, ...] = tuple(meta.get(meta_key or name) or ())
if not allowed:
notes.append(f"'{name}' is not supported by this model; dropped")
return None
if value not in allowed:
notes.append(
f"'{name}={value}' is not valid for this model "
f"(accepts {', '.join(allowed)}); dropped"
)
return None
return value
def _build_image_api_payload(
*,
model_id: str,
prompt: str,
semantic_aspect: str,
references: List[str],
config_key: str,
kwargs: Dict[str, Any],
) -> Tuple[Dict[str, Any], List[str]]:
"""Assemble the ``/images/generations`` body. Returns ``(payload, notes)``.
Every optional knob is filtered against what the model declares, because a
parameter the model doesn't know is silently *ignored* by the endpoint —
which would let a caller believe ``background=transparent`` took effect on
a model that has no transparency.
"""
meta = _image_api_model_meta(model_id)
notes: List[str] = []
payload: Dict[str, Any] = {"model": model_id, "prompt": prompt}
forced_ratio = _image_api_setting("aspect_ratio", kwargs.get("aspect_ratio_exact"), config_key)
ratio = _pick_exact_aspect_ratio(semantic_aspect, meta, forced_ratio, notes)
if ratio:
payload["aspect_ratio"] = ratio
for enum_name, meta_key in (
("resolution", "resolutions"), ("quality", None), ("background", None), ("output_format", None),
):
value = _image_api_enum(
enum_name, kwargs.get(enum_name), meta, config_key, notes, meta_key=meta_key
)
if value:
payload[enum_name] = value
for name, gate, clamp in (
("output_compression", "compression", lambda v: max(0, min(100, v))),
("seed", "seed", lambda v: v),
):
value = _coerce_int(_image_api_setting(name, kwargs.get(name), config_key))
if value is not None:
if meta.get(gate):
payload[name] = clamp(value)
else:
notes.append(f"'{name}' is not supported by this model; dropped")
count = _coerce_int(_image_api_setting("n", kwargs.get("n"), config_key))
if count is not None and count > 1:
max_n = int(meta.get("max_n") or 1)
if count > max_n:
notes.append(f"'n={count}' exceeds this model's cap of {max_n}; clamped")
payload["n"] = max(1, min(count, max_n))
if references:
max_refs = int(meta.get("max_refs") or 0)
usable = references[:max_refs] if max_refs else []
if len(references) > len(usable):
notes.append(
f"{len(references)} reference image(s) supplied but this model "
f"accepts {max_refs}; extras dropped"
)
if usable:
payload["input_references"] = [
{"type": "image_url", "image_url": {"url": url}} for url in usable
]
return payload, notes
def _extract_image_api_error(response: Any, fallback: str) -> str:
"""Flatten either error shape this endpoint produces into one line.
``{"error": {"message", "code"}}`` covers routing / auth / unknown model;
``{"success": false, "error": {"name": "ZodError", "message": "<json>"}}``
covers request validation, where ``message`` is a JSON-encoded issue array.
"""
if response is None:
return fallback
try:
body = response.json()
except Exception: # noqa: BLE001 - non-JSON error body
text = getattr(response, "text", "") or ""
return text[:300] or fallback
error = body.get("error") if isinstance(body, dict) else None
if isinstance(error, str) and error.strip():
return error.strip()
if not isinstance(error, dict):
return json.dumps(body)[:300] if body else fallback
message = error.get("message")
if error.get("name") == "ZodError" and isinstance(message, str):
try:
issues = json.loads(message)
except Exception: # noqa: BLE001
return message[:300]
parts: List[str] = []
for issue in issues if isinstance(issues, list) else []:
if not isinstance(issue, dict):
continue
field = ".".join(str(p) for p in (issue.get("path") or [])) or "request"
parts.append(f"{field}: {issue.get('message') or 'invalid'}")
return "; ".join(parts)[:400] or message[:300]
if isinstance(message, str) and message.strip():
return message.strip()[:300]
return json.dumps(error)[:300]
def _extension_for(media_type: Optional[str], fallback: str = "png") -> str:
if isinstance(media_type, str):
return _MEDIA_TYPE_EXTENSIONS.get(media_type.split(";", 1)[0].strip().lower(), fallback)
return fallback
def _model_slug(model_id: str) -> str:
"""Filename-safe fragment for the cache prefix (``openai/gpt-image-2`` …)."""
return "".join(ch if ch.isalnum() or ch in "-_" else "_" for ch in model_id)
def _save_image_api_entry(entry: Dict[str, Any], prefix: str) -> Optional[str]:
"""Persist one ``data[]`` entry to the image cache; ``None`` when it carries
neither base64 nor a URL. Raises on write failure (caller reports ``io_error``)."""
b64 = entry.get("b64_json")
if isinstance(b64, str) and b64.strip():
return str(save_b64_image(b64, prefix=prefix, extension=_extension_for(entry.get("media_type"))))
url = entry.get("url")
if isinstance(url, str) and url.strip():
return str(save_url_image(url.strip(), prefix=prefix))
return None
class OpenRouterCompatImageProvider(ImageGenProvider):
"""Image generation over an OpenRouter-compatible chat-completions endpoint.
Instantiated once per backend (OpenRouter, Nous Portal); they differ only
in which runtime provider supplies ``(base_url, api_key)``, the config
namespace for the model override, and Image API support.
"""
def __init__(
self,
*,
provider_name: str,
display_name: str,
runtime_name: str,
config_key: str,
model_env_var: str,
setup_schema: Dict[str, Any],
supports_image_api: bool = False,
) -> None:
self._name = provider_name
self._display = display_name
self._runtime_name = runtime_name
self._config_key = config_key
self._model_env_var = model_env_var
self._setup_schema = setup_schema
self._live_models_cache: Optional[tuple] = None
self._image_api_models_cache: Optional[tuple] = None
# OpenRouter only: Nous Portal has no /images/generations route.
self._supports_image_api = supports_image_api
@property
def name(self) -> str:
return self._name
@property
def display_name(self) -> str:
return self._display
def _resolve_runtime(self) -> Dict[str, Any]:
"""Resolve ``(base_url, api_key)`` via the shared runtime resolver."""
from hermes_cli.runtime_provider import resolve_runtime_provider
return resolve_runtime_provider(requested=self._runtime_name)
def _credentials(self) -> Tuple[str, str]:
"""``(api_key, base_url)`` — either may be ``""``; raises on resolution failure."""
runtime = self._resolve_runtime()
return (
str(runtime.get("api_key") or "").strip(),
str(runtime.get("base_url") or "").strip().rstrip("/"),
)
def is_available(self) -> bool:
try:
return bool(self._credentials()[0])
except Exception as exc: # noqa: BLE001 - treat resolution failure as unavailable
logger.debug("%s runtime resolution failed: %s", self._name, exc)
return False
def capabilities(self) -> Dict[str, Any]:
# Text-to-image and image-to-image (reference grounding). Image API
# models take far more references than chat-completions, so report the
# cap of the model that would service the next call.
max_refs = _MAX_REFERENCE_IMAGES
if self._supports_image_api:
chain = self._resolve_model_chain()
resolved = chain[0] if chain else ""
if resolved in _IMAGE_API_MODELS:
max_refs = int(_image_api_model_meta(resolved).get("max_refs") or max_refs)
return {"modalities": ["text", "image"], "max_reference_images": max_refs}
def list_models(self) -> List[Dict[str, Any]]:
"""Picker catalog: the endpoint's full live image-model surface.
OpenRouter: union of ``GET /images/models`` (40+ models) and the
chat-completions image models, so every image model the endpoint serves
— including ones released after this code shipped — is selectable. Nous
Portal (no ``/images`` route) lists the chat-completions catalog only.
Offline fallback: the static default chain plus the curated Image API snapshot.
"""
merged: Dict[str, Dict[str, Any]] = {}
if self._supports_image_api:
for entry in self._image_api_live_models():
merged[entry["id"]] = entry
for entry in self._live_models():
merged.setdefault(entry["id"], entry)
if merged:
return sorted(
merged.values(), key=lambda m: (_MODEL_PRIORITY.get(m["id"], 2), m["id"])
)
models = [{"id": model_id, **meta} for model_id, meta in _KNOWN_MODEL_META.items()]
if self._supports_image_api:
# Curated snapshot keeps the Image API models pickable offline.
models.extend(
{"id": model_id, "display": meta["display"], "strengths": f"{meta['strengths']} (Image API)"}
for model_id, meta in _IMAGE_API_MODELS.items()
)
return models
def _cached_catalog(self, attr: str, label: str, **fetch: Any) -> List[Dict[str, Any]]:
"""Cached (per TTL) live catalog rows for this backend; ``[]`` when unreachable."""
cached = getattr(self, attr)
if cached is not None and time.monotonic() - cached[1] < _LIVE_CACHE_TTL:
return cached[0]
models: List[Dict[str, Any]] = []
try:
api_key, base_url = self._credentials()
if base_url:
models = _fetch_catalog(base_url, api_key, **fetch)
except Exception as exc: # noqa: BLE001 - offline/unauth → fallback path
logger.debug("%s live %s unavailable: %s", self._name, label, exc)
models = []
setattr(self, attr, (models, time.monotonic()))
return models
def _image_api_live_models(self) -> List[Dict[str, Any]]:
"""Cached live ``GET /images/models`` entries; curated metadata for known ids."""
return self._cached_catalog(
"_image_api_models_cache", path="/images/models", meta=_IMAGE_API_MODELS,
generic="Image API model (from live OpenRouter catalog)", image_output_only=False,
label="Image API catalog",
)
def _live_models(self) -> List[Dict[str, Any]]:
"""Cached image-output models from the endpoint's ``/models`` catalog."""
return self._cached_catalog(
"_live_models_cache", path="/models", meta=_KNOWN_MODEL_META,
generic="Image-output model (from live OpenRouter catalog)", image_output_only=True,
label="image model catalog",
)
def default_model(self) -> Optional[str]:
# The catalog default, not the effective runtime model
# (that is _resolve_model_chain()).
return DEFAULT_MODEL
def get_setup_schema(self) -> Dict[str, Any]:
return dict(self._setup_schema)
def _resolve_model(self, explicit: Optional[str] = None) -> str:
"""Pick the image model (first of :meth:`_resolve_model_chain`)."""
return self._resolve_model_chain(explicit)[0]
def _resolve_model_chain(self, explicit: Optional[str] = None) -> list[str]:
"""Ordered model attempts: explicit ``model`` kwarg → ``*_IMAGE_MODEL``
env → ``image_gen.<provider>.model`` → top-level ``image_gen.model`` →
the quality-first default chain. Any explicit selection means "use
exactly this model", so only the bare default chain carries a fallback."""
for candidate in (explicit, os.environ.get(self._model_env_var)):
if isinstance(candidate, str) and candidate.strip():
return [candidate.strip()]
cfg = _load_image_gen_config()
scoped = cfg.get(self._config_key)
for candidate in ((scoped or {}).get("model") if isinstance(scoped, dict) else None, cfg.get("model")):
if isinstance(candidate, str) and candidate.strip():
return [candidate.strip()]
return list(_DEFAULT_MODEL_CHAIN)
def _generate_via_image_api(
self,
*,
model_id: str,
prompt: str,
semantic_aspect: str,
references: List[str],
base_url: str,
headers: Dict[str, str],
kwargs: Dict[str, Any],
) -> Dict[str, Any]:
"""Serve one model through ``POST {base_url}/images/generations``.
A failure the caller may retry on the next model of the chain carries a
private ``_retryable`` flag, which :meth:`generate` strips.
"""
base_fail = error_factory(self._name, semantic_aspect, model=model_id, prompt=prompt)
def _fail(error: str, error_type: str, retryable: bool = False) -> Dict[str, Any]:
response = base_fail(error, error_type)
if retryable:
response["_retryable"] = True
return response
# References become data URIs here rather than reusing the chat path's
# `content`, because that one is clamped to 3 and these models take up to 16.
usable_refs: List[str] = []
unreadable: List[str] = []
try:
for ref in references:
part = _to_image_url_part(ref)
if part:
usable_refs.append(part)
else:
unreadable.append(str(ref))
except Exception as exc: # noqa: BLE001 - blocked by the file-safety guard
return _fail(f"Could not load reference image: {exc}", "io_error")
# An edit whose every source image failed to load must not quietly
# become a text-to-image generation: that bills an unrelated picture
# and success=True hides it.
if unreadable and not usable_refs:
return _fail(
"Could not read the reference image(s) requested for editing: "
+ ", ".join(unreadable)
+ ". Refusing to silently fall back to text-to-image.",
"io_error",
)
payload, notes = _build_image_api_payload(
model_id=model_id, prompt=prompt, semantic_aspect=semantic_aspect,
references=usable_refs, config_key=self._config_key, kwargs=kwargs,
)
if unreadable:
notes.insert(0, f"dropped unreadable reference image(s): {', '.join(unreadable)}")
timeout = _REQUEST_TIMEOUT
configured = _image_api_setting("timeout", kwargs.get("timeout"), self._config_key)
try:
if configured is not None:
timeout = max(1.0, float(configured))
except (TypeError, ValueError):
logger.debug("%s: ignoring non-numeric image API timeout %r", self._name, configured)
# (connect, read): an unreachable endpoint fails in seconds instead of
# burning the whole read budget.
body, failure = post_json(
f"{base_url}/images/generations", headers=headers, payload=payload,
timeout=(min(_IMAGE_API_CONNECT_TIMEOUT, timeout), timeout), label=self._display,
error_message=lambda resp, exc: _extract_image_api_error(resp, str(exc)),
catch_request_exception=True,
)
if failure is not None:
if failure.kind != "http":
return _fail(failure.error, failure.error_type, retryable=failure.kind == "timeout")
status, message = failure.status, failure.message
logger.error(
"%s image API generation failed (%s) on %s: %s", self._name, status, model_id, message,
)
# 401/403 first so one account-level rejection does not get two
# different error_types depending on where in the chain it landed.
if status in (401, 403):
return _fail(f"{self._display} rejected the API key ({status}): {message}", "auth_error")
if status == 404:
return _fail(
f"Model '{model_id}' does not exist on the OpenRouter Image API "
f"(its catalog is separate from chat-completions — check "
f"GET {base_url}/images/models).",
"model_access",
retryable=True,
)
return _fail(failure.error, "api_error", retryable=status in _IMAGE_API_FALLBACK_STATUSES)
entries = body.get("data") if isinstance(body, dict) else None
entries = [e for e in entries if isinstance(e, dict)] if isinstance(entries, list) else []
if not entries:
return _fail(
f"{self._display} returned no image data for '{model_id}'.",
"empty_response",
retryable=True,
)
prefix = f"{self._name}_{_model_slug(model_id)}"
try:
saved = [p for p in (_save_image_api_entry(e, prefix) for e in entries) if p]
except Exception as exc: # noqa: BLE001
return _fail(f"Could not save generated image: {exc}", "io_error")
if not saved:
return _fail(f"{self._display} response carried neither b64_json nor url.", "empty_response")
extra: Dict[str, Any] = {
"endpoint": "images/generations",
"exact_aspect_ratio": payload.get("aspect_ratio"),
}
for key in ("resolution", "quality", "background", "output_format", "seed", "n"):
if key in payload:
extra[key] = payload[key]
if len(saved) > 1:
extra["additional_images"] = saved[1:]
if usable_refs:
extra["reference_images_used"] = len(payload.get("input_references") or [])
if notes:
extra["notes"] = notes
usage = body.get("usage") if isinstance(body, dict) else None
if isinstance(usage, dict):
if isinstance(usage.get("cost"), (int, float)):
extra["cost_usd"] = usage["cost"]
if isinstance(usage.get("total_tokens"), int):
extra["total_tokens"] = usage["total_tokens"]
return success_response(
image=saved[0],
model=model_id,
prompt=prompt,
aspect_ratio=semantic_aspect,
provider=self._name,
modality="image" if usable_refs else "text",
extra=extra,
)
def generate(
self,
prompt: str,
aspect_ratio: str = DEFAULT_ASPECT_RATIO,
*,
image_url: Optional[str] = None,
reference_image_urls: Optional[List[str]] = None,
**kwargs: Any,
) -> Dict[str, Any]:
try:
api_key, base_url = self._credentials()
except Exception as exc: # noqa: BLE001
return error_response(
error=f"Could not resolve {self._display} credentials: {exc}",
error_type="missing_api_key",
provider=self._name,
aspect_ratio=aspect_ratio,
)
if not api_key or not base_url:
return error_response(
error=(
f"No {self._display} credentials found. "
f"Configure {self._display} in `hermes tools` → Image Generation."
),
error_type="missing_api_key",
provider=self._name,
aspect_ratio=aspect_ratio,
)
model_chain = self._resolve_model_chain(kwargs.get("model"))
aspect = resolve_aspect_ratio(aspect_ratio)
# The pet generator passes local paths via ``reference_images``; the
# generic tool surface uses ``image_url`` / ``reference_image_urls``.
references: List[str] = [str(ref) for ref in kwargs.get("reference_images") or []]
if image_url:
references.append(str(image_url))
references.extend(str(ref) for ref in reference_image_urls or [])
content: List[Dict[str, Any]] = [{"type": "text", "text": prompt}]
for ref in references[:_MAX_REFERENCE_IMAGES]:
part = _to_image_url_part(ref)
if part:
content.append({"type": "image_url", "image_url": {"url": part}})
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
# OpenRouter attribution headers (harmless against Nous Portal).
"HTTP-Referer": "https://github.com/NousResearch/hermes-agent",
"X-Title": "Hermes Agent",
}
last_error: Optional[Dict[str, Any]] = None
for i, model_id in enumerate(model_chain):
is_last = i == len(model_chain) - 1
fail = error_factory(self._name, aspect, model=model_id, prompt=prompt)
def retry_with_fallback(reason: str) -> None:
logger.info(
"%s model %s %s; retrying with fallback %s",
self._name, model_id, reason, model_chain[i + 1],
)
# An Image API model cannot be served by /chat/completions (and vice
# versa), so this is a routing decision, not a preference.
if self._supports_image_api and _select_surface(
model_id, base_url, api_key, self._config_key
) == "images":
outcome = self._generate_via_image_api(
model_id=model_id, prompt=prompt, semantic_aspect=aspect,
references=references, base_url=base_url, headers=headers, kwargs=kwargs,
)
retryable = outcome.pop("_retryable", False)
if outcome.get("success") or is_last or not retryable:
return outcome
retry_with_fallback("failed on the image API")
last_error = outcome
continue
payload: Dict[str, Any] = {
"model": model_id,
"modalities": ["image", "text"],
"messages": [{"role": "user", "content": content}],
"image_config": {"aspect_ratio": _ASPECT_RATIOS.get(aspect, "1:1")},
}
result, failure = post_json(
f"{base_url}/chat/completions", headers=headers, payload=payload,
timeout=_REQUEST_TIMEOUT, label=self._display,
)
if failure is not None:
if failure.kind == "http":
logger.error(
"%s image gen failed (%d) on %s: %s",
self._name, failure.status, model_id, failure.message,
)
hint = _access_error_hint(
self._display, model_id, self._model_env_var, failure.status, failure.message
)
if hint and not is_last:
retry_with_fallback("unavailable")
continue
last_error = fail(hint or failure.error, "model_access" if hint else "api_error")
return last_error
if failure.kind == "timeout" and not is_last:
retry_with_fallback("timed out")
continue
return fail(failure.error, failure.error_type)
images = _extract_images(result)
if not images:
if not is_last:
retry_with_fallback("returned no image")
continue
# Text but no image usually means the model didn't honor image
# output (wrong model or modalities); surface that.
return fail(
f"{self._display} returned no image. Ensure the model "
f"'{model_id}' supports image output.",
"empty_response",
)
first = images[0]
try:
if first.startswith("data:"):
b64 = first.split(",", 1)[1] if "," in first else ""
saved_path = save_b64_image(b64, prefix=f"{self._name}_gen")
else:
saved_path = save_url_image(first, prefix=f"{self._name}_gen")
except Exception as exc: # noqa: BLE001
return fail(f"Could not save generated image: {exc}", "io_error")
return success_response(
image=str(saved_path),
model=model_id,
prompt=prompt,
aspect_ratio=aspect,
provider=self._name,
)
return last_error or error_response(
error=f"{self._display} image generation failed after trying all candidate models.",
error_type="api_error",
provider=self._name,
model=model_chain[-1] if model_chain else "",
prompt=prompt,
aspect_ratio=aspect,
)
def _build_providers() -> List[OpenRouterCompatImageProvider]:
return [
OpenRouterCompatImageProvider(
provider_name="openrouter",
display_name="OpenRouter",
runtime_name="openrouter",
config_key="openrouter",
model_env_var="OPENROUTER_IMAGE_MODEL",
supports_image_api=True,
setup_schema={
"name": "OpenRouter (image)",
"badge": "paid",
"tag": "Gemini Flash Image, gpt-image-2, Krea 2, Qwen Image 3 & more via OpenRouter; uses OPENROUTER_API_KEY",
"env_vars": [
{
"key": "OPENROUTER_API_KEY",
"prompt": "OpenRouter API key",
"url": "https://openrouter.ai/keys",
}
],
},
),
OpenRouterCompatImageProvider(
provider_name="nous",
display_name="Nous Portal",
runtime_name="nous",
config_key="nous",
model_env_var="NOUS_IMAGE_MODEL",
setup_schema={
"name": "Nous Portal (image)",
"badge": "subscription",
"tag": "Reference-grounded image generation via Nous Portal (OpenRouter-backed)",
"env_vars": [],
"requires_nous_auth": True,
},
),
]
def register(ctx: Any) -> None:
"""Register the OpenRouter + Nous Portal image gen providers."""
for provider in _build_providers():
ctx.register_image_gen_provider(provider)
Reference in New Issue View Git Blame Copy Permalink