| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354 |
- """OpenRouter video generation backend.
- OpenRouter fronts every major video model (Veo, Sora, Kling, Seedance, Wan, Hailuo, Grok
- Imagine, FLUX Video, …) behind one asynchronous API: ``POST /api/v1/videos`` → poll
- ``GET /api/v1/videos/{id}`` → download ``GET /api/v1/videos/{id}/content`` with the
- bearer key. The catalog and each model's limits come live from ``GET /api/v1/videos/models``
- (public, no key), so new releases are selectable without a patch and a retired model drops
- out on its own. ``capabilities()`` reflects the *selected* model so the dynamic
- ``video_generate`` schema advertises only what that model honours.
- Docs: https://openrouter.ai/docs/guides/overview/multimodal/video-generation
- """
- from __future__ import annotations
- import logging
- import time
- from typing import Any, Dict, List, Optional, Tuple
- from agent.video_gen_provider import VideoGenProvider, error_response, save_url_video, success_response
- logger = logging.getLogger(__name__)
- DEFAULT_MODEL = "minimax/hailuo-3-max"
- DEFAULT_BASE_URL = "https://openrouter.ai/api/v1"
- _CATALOG_TTL_S = 300.0
- _CATALOG_TIMEOUT_S = 10.0
- _TERMINAL_STATUSES = frozenset({"completed", "failed", "cancelled", "canceled", "expired"})
- # Every value the API accepts (docs "Supported Resolutions / Aspect Ratios"); the union fallback
- # when the live catalog is unreachable. Heights drive nearest-match clamping.
- _RESOLUTION_HEIGHT = {"480p": 480, "540p": 540, "720p": 720, "768p": 768, "1080p": 1080, "1K": 1024, "2K": 1440, "4K": 2160}
- _ALL_ASPECT_RATIOS = ("16:9", "9:16", "1:1", "4:3", "3:4", "3:2", "2:3", "21:9", "9:21")
- _MAX_REFERENCE_IMAGES = 3 # image references are accepted by every provider per the API schema
- # Offline snapshot so the picker/default work before the first successful catalog fetch.
- _FALLBACK_CATALOG: list[dict[str, Any]] = [
- {"id": DEFAULT_MODEL, "name": "MiniMax: Hailuo 3 Max", "supported_durations": list(range(5, 16)),
- "supported_resolutions": ["768p", "480p"], "supported_aspect_ratios": ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16"],
- "supported_frame_images": ["first_frame", "last_frame"], "generate_audio": False, "seed": False,
- "pricing_skus": {"duration_seconds_480p": "0.05", "duration_seconds_768p": "0.08"}},
- ]
- def _price_label(skus: Any) -> str:
- """Compact per-second price from ``pricing_skus`` (``$0.10/s`` or ``$0.05–0.28/s``); ``""`` when the
- SKU shape is token- or megapixel-priced (Seedance, FLUX upscale) — a wrong number is worse than none."""
- if not isinstance(skus, dict):
- return ""
- per_second: list[float] = []
- for key, value in skus.items():
- try:
- amount = float(value)
- except (TypeError, ValueError):
- continue
- if key.startswith("duration_seconds"):
- per_second.append(amount)
- elif key.startswith(("cents_per_second_output", "cents_per_video_output_second")):
- per_second.append(amount / 100)
- if not per_second:
- return ""
- lo, hi = min(per_second), max(per_second)
- return f"${lo:.2f}/s" if lo == hi else f"${lo:.2f}–{hi:.2f}/s"
- def _ratio(value: Any) -> Optional[float]:
- try:
- w, h = str(value).split(":")
- return float(w) / float(h)
- except (ValueError, ZeroDivisionError):
- return None
- def _nearest(value: Any, supported: list[Any], height: Optional[dict[str, int]] = None) -> Any:
- """Closest supported value (durations by distance, resolutions by pixel height, aspect ratios by
- numeric ratio); the request is otherwise a guaranteed 400 because the tool always sends a default
- resolution/aspect ratio."""
- if not supported or value in supported:
- return value
- if height is not None:
- target = height.get(str(value))
- if target is None:
- return supported[0]
- scored = [(abs(height[str(s)] - target), i, s) for i, s in enumerate(supported) if str(s) in height]
- return min(scored)[2] if scored else supported[0]
- if ":" in str(value):
- target = _ratio(value)
- if target is None:
- return supported[0]
- scored = [(abs(r - target), i, s) for i, s in enumerate(supported) if (r := _ratio(s)) is not None]
- return min(scored)[2] if scored else supported[0]
- try:
- return min(supported, key=lambda s: (abs(int(s) - int(value)), s))
- except (TypeError, ValueError):
- return supported[0]
- def _is_generative(entry: dict[str, Any]) -> bool:
- """Text/image-to-video models declare durations; edit, upscale and avatar models (video/audio input)
- do not and are outside the unified ``video_generate`` surface."""
- return bool(entry.get("supported_durations"))
- def _entry_capabilities(entry: dict[str, Any]) -> dict[str, Any]:
- durations = [int(d) for d in entry.get("supported_durations") or [] if isinstance(d, (int, float))]
- return {
- "modalities": ["text", "image"] if entry.get("supported_frame_images") else ["text"],
- "aspect_ratios": list(entry.get("supported_aspect_ratios") or _ALL_ASPECT_RATIOS),
- "resolutions": list(entry.get("supported_resolutions") or _RESOLUTION_HEIGHT),
- "max_duration": max(durations) if durations else 30, "min_duration": min(durations) if durations else 1,
- "supports_audio": bool(entry.get("generate_audio")), "supports_negative_prompt": False,
- "supports_seed": bool(entry.get("seed")), "supports_upscale": False,
- "max_reference_images": _MAX_REFERENCE_IMAGES,
- }
- def _image_part(url: str) -> dict[str, Any]:
- return {"type": "image_url", "image_url": {"url": url}}
- def _acceptable_image_ref(value: str) -> bool:
- """OpenRouter fetches the frame itself, so it needs a public HTTPS URL or an inline ``data:image/`` URL
- (what the sandbox confinement chokepoint hands us for local files)."""
- lowered = value.lower()
- return lowered.startswith("https://") or lowered.startswith("data:image/")
- def _build_payload(
- entry: dict[str, Any], *, model: str, prompt: str, image_url: Optional[str], reference_image_urls: Optional[list[str]],
- duration: Optional[int], aspect_ratio: str, resolution: str, audio: Optional[bool], seed: Optional[int],
- ) -> dict[str, Any]:
- """Unified inputs → OpenRouter body, clamped to the model's live limits; unsupported toggles are dropped
- rather than sent (the API 400s on ``seed``/``generate_audio`` for models that lack them)."""
- payload: dict[str, Any] = {"model": model, "prompt": prompt}
- if aspect_ratio:
- payload["aspect_ratio"] = _nearest(aspect_ratio, list(entry.get("supported_aspect_ratios") or []))
- if resolution:
- payload["resolution"] = _nearest(resolution, list(entry.get("supported_resolutions") or []), _RESOLUTION_HEIGHT)
- if duration:
- payload["duration"] = int(_nearest(int(duration), list(entry.get("supported_durations") or [])))
- if image_url:
- payload["frame_images"] = [{**_image_part(image_url), "frame_type": "first_frame"}]
- if reference_image_urls:
- payload["input_references"] = [_image_part(u) for u in reference_image_urls[:_MAX_REFERENCE_IMAGES]]
- if audio is not None and entry.get("generate_audio"):
- payload["generate_audio"] = bool(audio)
- if seed is not None and entry.get("seed"):
- payload["seed"] = int(seed)
- return payload
- class OpenRouterVideoGenProvider(VideoGenProvider):
- """Every generative model on OpenRouter's video API, catalog and limits discovered live."""
- name = "openrouter"
- display_name = "OpenRouter"
- _poll_interval_s = 10.0
- _poll_deadline_s = 900.0
- _request_timeout_s = 60.0
- def __init__(self) -> None:
- self._catalog_cache: Optional[tuple[list[dict[str, Any]], float]] = None
- # ---- credentials / transport -------------------------------------------------------------
- def _credentials(self) -> tuple[str, str]:
- """``(api_key, base_url)`` from the runtime resolver chat uses, so a pooled or OAuth credential counts
- and a multiplexed profile never spends the launch profile's ``os.environ`` key; raises on failure."""
- from hermes_cli.runtime_provider import resolve_runtime_provider
- runtime = resolve_runtime_provider(requested="openrouter")
- return (str(runtime.get("api_key") or "").strip(),
- (str(runtime.get("base_url") or "").strip() or DEFAULT_BASE_URL).rstrip("/"))
- def _headers(self, api_key: str) -> dict[str, str]:
- return {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json",
- "HTTP-Referer": "https://github.com/NousResearch/hermes-agent", "X-Title": "Hermes Agent"}
- def _session(self) -> Any:
- import requests
- return requests.Session()
- def is_available(self) -> bool:
- try:
- return bool(self._credentials()[0])
- except Exception as exc:
- logger.debug("OpenRouter video credential resolution failed: %s", exc)
- return False
- # ---- catalog -------------------------------------------------------------------------------
- def _catalog(self) -> list[dict[str, Any]]:
- """Live ``/videos/models`` entries (public endpoint), cached per TTL; the snapshot when unreachable."""
- if self._catalog_cache and time.monotonic() - self._catalog_cache[1] < _CATALOG_TTL_S:
- return self._catalog_cache[0]
- entries: list[dict[str, Any]] = []
- try:
- import requests
- response = requests.get(f"{self._credentials()[1]}/videos/models", timeout=_CATALOG_TIMEOUT_S)
- response.raise_for_status()
- data = response.json().get("data")
- entries = [e for e in (data if isinstance(data, list) else []) if isinstance(e, dict) and e.get("id")]
- except Exception as exc:
- logger.debug("OpenRouter video catalog unavailable: %s", exc)
- if not entries:
- return _FALLBACK_CATALOG
- self._catalog_cache = (entries, time.monotonic())
- return entries
- def _entry(self, model_id: str) -> dict[str, Any]:
- """Catalog row for *model_id*; ``{}`` for an unknown id (request passes through unclamped so a
- brand-new model works before our cache refreshes — the API validates)."""
- return next((e for e in self._catalog() if e.get("id") == model_id), {})
- def _configured_model(self) -> str:
- try:
- from hermes_cli.config import cfg_get, load_config
- value = cfg_get(load_config(), "video_gen", "model")
- except Exception as exc:
- logger.debug("Could not read video_gen.model: %s", exc)
- value = None
- return value.strip() if isinstance(value, str) and value.strip() else DEFAULT_MODEL
- def list_models(self) -> list[dict[str, Any]]:
- rows = []
- for entry in self._catalog():
- if not _is_generative(entry):
- continue
- caps = _entry_capabilities(entry)
- extras = [f"{caps['min_duration']}-{caps['max_duration']}s", "/".join(caps["resolutions"])]
- extras += ["audio"] if caps["supports_audio"] else []
- extras += ["i2v"] if "image" in caps["modalities"] else []
- rows.append({"id": entry["id"], "display": entry.get("name") or entry["id"], "strengths": ", ".join(extras),
- "price": _price_label(entry.get("pricing_skus")), "modalities": caps["modalities"],
- "min_duration": caps["min_duration"], "max_duration": caps["max_duration"]})
- return rows
- def default_model(self) -> Optional[str]:
- return DEFAULT_MODEL
- def capabilities(self) -> dict[str, Any]:
- """The selected model's live surface; the API-wide union when the id is unknown or the catalog is down.
- ``supports_seed``/``supports_audio`` are per-model (Veo/Wan/Seedance: yes; Hailuo/Grok: no)."""
- entry = self._entry(self._configured_model())
- if entry:
- return _entry_capabilities(entry)
- return {"modalities": ["text", "image"], "aspect_ratios": list(_ALL_ASPECT_RATIOS),
- "resolutions": list(_RESOLUTION_HEIGHT), "max_duration": 30, "min_duration": 1,
- "supports_audio": True, "supports_negative_prompt": False, "supports_seed": True,
- "supports_upscale": False, "max_reference_images": _MAX_REFERENCE_IMAGES}
- def get_setup_schema(self) -> dict[str, Any]:
- return {"name": "OpenRouter", "badge": "paid",
- "tag": "Veo 3.1, Sora 2 Pro, Kling 3, Seedance 2, Wan 3, Hailuo 3, Grok Imagine & more — live catalog; "
- "text-to-video, image-to-video & reference-to-video; uses OPENROUTER_API_KEY",
- "env_vars": [{"key": "OPENROUTER_API_KEY", "prompt": "OpenRouter API key", "url": "https://openrouter.ai/settings/keys"}]}
- # ---- generation ----------------------------------------------------------------------------
- def _poll(self, session: Any, job_id: str, base_url: str, headers: dict[str, str]) -> dict[str, Any]:
- deadline = time.monotonic() + self._poll_deadline_s
- url = f"{base_url}/videos/{job_id}"
- last_status = "unknown"
- while True:
- remaining = deadline - time.monotonic()
- if remaining <= 0:
- raise TimeoutError(f"video job {job_id} did not finish within {int(self._poll_deadline_s)}s (last status={last_status})")
- response = session.get(url, headers=headers, timeout=max(0.001, min(self._request_timeout_s, remaining)))
- response.raise_for_status()
- payload = response.json()
- last_status = str(payload.get("status") or "").lower() or "unknown"
- if last_status in _TERMINAL_STATUSES:
- return payload
- time.sleep(min(self._poll_interval_s, max(0.0, deadline - time.monotonic())))
- def _save_completed_video(self, job_id: str, base_url: str, headers: dict[str, str]) -> str:
- # The content endpoint is derived from our configured origin, never from ``unsigned_urls``: the
- # bearer key must only ever be sent to the host the operator selected. That origin is operator
- # chosen (a LAN relay is legitimate), so the first hop is trusted for the private-address check.
- return str(save_url_video(f"{base_url}/videos/{job_id}/content", prefix="openrouter",
- headers=headers, require_video_content_type=True,
- trusted_origin=True))
- def generate(
- self, prompt: str, *, model: Optional[str] = None, image_url: Optional[str] = None,
- reference_image_urls: Optional[list[str]] = None, duration: Optional[int] = None,
- aspect_ratio: str = "16:9", resolution: str = "720p", negative_prompt: Optional[str] = None,
- audio: Optional[bool] = None, seed: Optional[int] = None, **kwargs: Any,
- ) -> dict[str, Any]:
- del negative_prompt, kwargs # no top-level negative_prompt on this API; unknown kwargs are ignored per the ABC
- prompt = (prompt or "").strip()
- model_id = (model or "").strip() or self._configured_model()
- def fail(error: str, error_type: str) -> dict[str, Any]:
- return error_response(error=error, error_type=error_type, provider=self.name, model=model_id, prompt=prompt,
- aspect_ratio=aspect_ratio)
- if not prompt:
- return fail("prompt is required", "invalid_request")
- try:
- api_key, base_url = self._credentials()
- except Exception as exc:
- return fail(f"Could not resolve OpenRouter credentials: {exc}", "missing_credentials")
- if not api_key:
- return fail("No OpenRouter credential: set OPENROUTER_API_KEY or run `hermes auth add openrouter`",
- "missing_credentials")
- # Resolved once: a rotating pool must not submit under one key and poll or download under another.
- headers = self._headers(api_key)
- image_url = (image_url or "").strip() or None
- refs = [r.strip() for r in (reference_image_urls or []) if isinstance(r, str) and r.strip()]
- for ref in ([image_url] if image_url else []) + refs:
- if not _acceptable_image_ref(ref):
- return fail("image inputs must be public HTTPS URLs or data:image/ URLs (OpenRouter fetches them itself)",
- "invalid_request")
- entry = self._entry(model_id)
- payload = _build_payload(entry, model=model_id, prompt=prompt, image_url=image_url, reference_image_urls=refs,
- duration=duration, aspect_ratio=aspect_ratio, resolution=resolution, audio=audio, seed=seed)
- session = self._session()
- try:
- submitted = session.post(f"{base_url}/videos", headers=headers, json=payload,
- timeout=self._request_timeout_s)
- if submitted.status_code >= 400:
- detail = ""
- try:
- detail = str((submitted.json().get("error") or {}).get("message") or "")
- except Exception:
- detail = ""
- return fail(f"OpenRouter rejected the request (HTTP {submitted.status_code}): {detail or submitted.text[:300]}",
- "api_error")
- job_id = str(submitted.json().get("id") or "").strip()
- if not job_id:
- return fail("OpenRouter submit response did not contain a job id", "api_error")
- job = self._poll(session, job_id, base_url, headers)
- status = str(job.get("status") or "").lower()
- if status != "completed":
- return fail(str(job.get("error") or f"video job ended with status={status!r}"), "job_failed")
- video_path = self._save_completed_video(job_id, base_url, headers)
- except Exception as exc:
- logger.debug("OpenRouter video generation failed", exc_info=True)
- return fail(f"OpenRouter video generation failed: {exc}", "api_error")
- finally:
- close = getattr(session, "close", None)
- if callable(close):
- close()
- raw_usage = job.get("usage")
- usage: dict[str, Any] = raw_usage if isinstance(raw_usage, dict) else {}
- extra: dict[str, Any] = {"job_id": job_id, **({"cost": usage["cost"]} if usage.get("cost") is not None else {})}
- return success_response(
- video=video_path, model=model_id, prompt=prompt, modality="image" if image_url else "text",
- aspect_ratio=str(payload.get("aspect_ratio") or ""), duration=int(payload.get("duration") or 0),
- provider=self.name, extra=extra)
- def register(ctx) -> None:
- """Plugin entry point — wire ``OpenRouterVideoGenProvider`` into the registry."""
- ctx.register_video_gen_provider(OpenRouterVideoGenProvider())
|