__init__.py 30 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653
  1. """Krea image generation backend: ``Krea 3`` (generates and edits) and ``Krea 2`` Medium / Large / Medium Turbo.
  2. Krea's API is asynchronous: submit returns a ``job_id`` polled at ``GET
  3. /jobs/{job_id}``; ``generate()`` hides that (submit, poll every 2s with light
  4. backoff, cache the result URL locally). Selection: ``model`` kwarg →
  5. ``KREA_IMAGE_MODEL`` → ``image_gen.krea.model`` → ``image_gen.model`` (when one
  6. of our IDs) → :data:`DEFAULT_MODEL`. Docs: https://www.krea.ai/docs/developers/krea-3/overview
  7. and https://docs.krea.ai/developers/krea-2/overview
  8. """
  9. from __future__ import annotations
  10. import base64
  11. import logging
  12. import mimetypes
  13. import time
  14. import uuid
  15. from pathlib import Path
  16. from typing import Any, Callable, Dict, List, Optional, Tuple
  17. import requests
  18. from agent.secret_scope import get_secret
  19. from agent.image_gen_provider import DEFAULT_ASPECT_RATIO, resolve_aspect_ratio, save_url_image, success_response
  20. from plugins.image_gen._common import (
  21. ErrorFn, HttpFailure, StaticImageGenProvider, collect_source_images, error_factory, load_image_gen_config,
  22. post_json, prompt_required_error, resolve_static_model)
  23. logger = logging.getLogger(__name__)
  24. BASE_URL = "https://api.krea.ai"
  25. # ``path`` is Krea's submit path. ``upscale`` (Enhance pass) is opt-in for every tier:
  26. # default-on enhance degraded output quality, and Large is 2K native anyway. ``edit``
  27. # marks Krea 3, which edits the pictures it is given instead of copying their look.
  28. _MODELS: dict[str, dict[str, Any]] = {
  29. "krea-3": {
  30. "display": "Krea 3", "speed": "~5s (1K) / ~40s (2K, high thinking)",
  31. "strengths": "Generates and edits existing images from instructions; keeps products, characters, logos and text consistent.",
  32. "price": "$0.03 (1K) / $0.06 (2K), +$0.02 (1K) or $0.07 (2K) per reference image, +$0.02 high thinking",
  33. "path": "/generate/image/krea/krea-3", "edit": True, "upscale": False,
  34. },
  35. "krea-2-medium": {
  36. "display": "Krea 2 Medium", "speed": "~15-25s",
  37. "strengths": "Illustration, anime, painting, expressive styles. Faster + cheaper.",
  38. "price": "$0.030 (text) / $0.035 (style refs) / $0.040 (moodboards)",
  39. "path": "/generate/image/krea/krea-2/medium", "upscale": False,
  40. },
  41. "krea-2-large": {
  42. "display": "Krea 2 Large", "speed": "~25-60s",
  43. "strengths": "Photorealism, raw textured looks (motion blur, grain), expressive styles.",
  44. "price": "$0.060 (text) / $0.065 (style refs) / $0.070 (moodboards)",
  45. "path": "/generate/image/krea/krea-2/large", "upscale": False,
  46. },
  47. "krea-2-medium-turbo": {
  48. "display": "Krea 2 Medium Turbo", "speed": "~8-15s",
  49. "strengths": "Fastest Krea 2 — medium quality at lower latency / cost.",
  50. "price": "$0.015 (text) / $0.0175 (style refs)", "path": "/generate/image/krea/krea-2/medium-turbo", "upscale": False,
  51. },
  52. }
  53. KREA_MODEL_IDS = frozenset(_MODELS)
  54. DEFAULT_MODEL = "krea-2-medium"
  55. # Hermes' 3 abstract ratios → Krea's enum (1:1, 4:3, 3:2, 16:9, 2.35:1, 4:5, 2:3, 9:16).
  56. _ASPECT_MAP = {"landscape": "16:9", "square": "1:1", "portrait": "9:16"}
  57. DEFAULT_RESOLUTION = "1K" # Krea 2 is priced at 1K only; Krea 3 also takes 2K
  58. # Style refs are objects ({"url", "strength"}); bare URLs get Krea's recommended start (range -2..2).
  59. _DEFAULT_STYLE_REFERENCE_STRENGTH = 0.6
  60. _MAX_STYLE_REFERENCES = 10
  61. _REMOTE_REFERENCE_PREFIXES = ("http://", "https://", "data:")
  62. # Base64 grows a file by a third and the managed gateway rejects bodies over about 4.5 MB,
  63. # so all local references together stay under this.
  64. _MAX_LOCAL_REFERENCE_BYTES = 3 * 1024 * 1024
  65. _VALID_CREATIVITY = {"raw", "low", "medium", "high"}
  66. # Krea 2 generative sliders: integers from -100 to 100, 0 means the slider is off.
  67. _K2_SLIDERS = ("intensity", "complexity", "movement")
  68. # Krea 3 controls. Krea itself takes 8 reference images; the managed gateway caps them at 4 and
  69. # one cap keeps direct and managed behaviour the same.
  70. _KREA3_CONTROLS = ("thinking", "resolution")
  71. _KREA3_RESOLUTIONS = ("1K", "2K")
  72. _MAX_KREA3_REFERENCE_IMAGES = 4
  73. # Polling: Krea recommends 2-5s; 2s backing off to 5s (Large ~1min); ceiling = Krea's 3 min tool timeout.
  74. _POLL_INITIAL_INTERVAL = 2.0
  75. _POLL_MAX_INTERVAL = 5.0
  76. _POLL_BACKOFF = 1.3
  77. _POLL_TIMEOUT_SECONDS = 180.0
  78. # Retryable poll statuses; other 4xx are permanent — surface them instead of burning the deadline.
  79. _RETRYABLE_POLL_STATUSES = frozenset({408, 409, 425, 429, 500, 502, 503, 504})
  80. _TERMINAL_STATES = {"completed", "failed", "cancelled"}
  81. # Krea Enhance — the optional ``upscale`` pass after generation (max 8K).
  82. _ENHANCE_PATH = "/generate/enhance/krea/enhance"
  83. _ENHANCE_SCALE_FACTOR = 2
  84. _USER_AGENT = "Hermes-Agent/1.0 (krea-image-gen)"
  85. # Fatal poll outcome (``_poll_krea_job`` ``kind``) → (error_type, message builder).
  86. _POLL_FAILURES: dict[str, tuple[str, Callable[[str, Any], str]]] = {
  87. "http": ("api_error", lambda job_id, detail: f"Krea poll failed ({detail}) for job {job_id}"),
  88. "timeout": ("timeout", lambda job_id, detail: f"Krea poll timed out for job {job_id}: {detail}"),
  89. "invalid_json": ("invalid_response", lambda job_id, detail: f"Krea poll returned invalid JSON: {detail}"),
  90. "deadline": ("timeout", lambda job_id, detail: (
  91. f"Krea job {job_id} did not complete within "
  92. f"{int(_POLL_TIMEOUT_SECONDS)}s (last status: {detail or 'unknown'})")),
  93. }
  94. # Managed gateway prices base text-to-image and URL style references only.
  95. _MANAGED_UNSUPPORTED = (("trained styles (LoRAs)", "styles"), ("moodboards", "moodboards"))
  96. def _load_krea_config() -> dict[str, Any]:
  97. """Read ``image_gen`` (the krea section lives under ``image_gen.krea``)."""
  98. return load_image_gen_config()
  99. def _krea_section() -> dict[str, Any]:
  100. section = _load_krea_config().get("krea")
  101. return section if isinstance(section, dict) else {}
  102. def fallback_to_fal_enabled() -> bool:
  103. """``image_gen.krea.fallback_to_fal``; on unless set to false."""
  104. return _krea_section().get("fallback_to_fal") is not False
  105. def _fallback_eligible(failure: HttpFailure) -> bool:
  106. """Only failures that prove Krea created no job: no server accepted the request, or the
  107. gateway answered 429, which it documents as "no job was created". A dropped connection,
  108. a timeout or a 5xx may have happened after Krea accepted the job."""
  109. return failure.kind == "unreachable" or (failure.kind == "http" and failure.status == 429)
  110. def _resolve_model(explicit: Optional[str] = None) -> tuple[str, dict[str, Any]]:
  111. return resolve_static_model(
  112. _MODELS, DEFAULT_MODEL, env_var="KREA_IMAGE_MODEL", config_key="krea", explicit=explicit,
  113. config=_load_krea_config())
  114. def _resolve_managed_krea_gateway():
  115. """Managed gateway config on the managed path, else ``None``. Managed when the stored
  116. ``image_gen`` selection is ``nous`` (or legacy ``use_gateway: true``), or never-configured with
  117. no ``KREA_API_KEY``; an explicit vendor selection pins direct. Never raises (discovery scans)."""
  118. try:
  119. from tools.managed_tool_gateway import resolve_managed_tool_gateway
  120. from tools.tool_backend_helpers import NOUS_MANAGED_PROVIDER, read_selection
  121. except Exception as exc:
  122. logger.debug("Managed Krea gateway resolution unavailable: %s", exc)
  123. return None
  124. try:
  125. selected = read_selection("image_gen")
  126. except Exception:
  127. selected = None
  128. if selected is not None and selected != NOUS_MANAGED_PROVIDER:
  129. return None
  130. if selected is None and get_secret("KREA_API_KEY"):
  131. return None
  132. try:
  133. return resolve_managed_tool_gateway("krea")
  134. except Exception as exc:
  135. logger.debug("Managed Krea gateway resolution failed: %s", exc)
  136. return None
  137. def _managed_krea_gateway_ready() -> bool:
  138. """Cheap, offline-friendly probe for managed Krea availability."""
  139. try:
  140. from tools.managed_tool_gateway import is_managed_tool_gateway_ready
  141. return bool(is_managed_tool_gateway_ready("krea"))
  142. except Exception:
  143. return False
  144. def _resolve_creativity(value: Optional[str]) -> str:
  145. """Coerce ``creativity`` kwarg (then config) to a valid Krea value; default ``medium``."""
  146. for candidate in (value, _krea_section().get("creativity")):
  147. if isinstance(candidate, str) and candidate.strip().lower() in _VALID_CREATIVITY:
  148. return candidate.strip().lower()
  149. return "medium"
  150. def _headers(auth_token: str, *, managed: bool, json_body: bool) -> dict[str, str]:
  151. headers = {"Authorization": f"Bearer {auth_token}", "User-Agent": _USER_AGENT}
  152. if json_body:
  153. headers["Content-Type"] = "application/json"
  154. if managed:
  155. # Gateway billing idempotency boundary: a fresh key per submit = one billable execution.
  156. headers["x-idempotency-key"] = str(uuid.uuid4())
  157. return headers
  158. def _submit_error_message(resp: Any, exc: Exception) -> str:
  159. fallback = resp.text[:300] if resp is not None else str(exc)
  160. try:
  161. body = resp.json() if resp is not None else {}
  162. error = body.get("error")
  163. if isinstance(error, dict):
  164. message = error.get("message")
  165. else:
  166. message = body.get("message") or body.get("detail")
  167. return message or fallback
  168. except Exception:
  169. return fallback
  170. def _is_terminal(job: Any) -> bool:
  171. """``completed_at`` is a backstop terminal marker for unfamiliar ``status`` enums (Krea adds
  172. pending states — backlogged/scheduled/sampling — over time)."""
  173. return isinstance(job, dict) and (job.get("status") in _TERMINAL_STATES or bool(job.get("completed_at")))
  174. def _poll_krea_job(
  175. base_url: str, auth_token: str, job_id: str, *, timeout_seconds: float = _POLL_TIMEOUT_SECONDS,
  176. on_error: Optional[Any] = None,
  177. ) -> Any:
  178. """Poll ``/jobs/{job_id}`` until terminal; returns the job dict or ``None`` when it gave up.
  179. With ``on_error(kind, detail)`` (main path) a fatal poll failure returns that callback's
  180. result; without it (best-effort Enhance) failures only log. ``kind`` ∈ ``http`` (detail =
  181. status) / ``timeout`` / ``invalid_json`` / ``deadline`` (detail = last status seen).
  182. """
  183. job_url = f"{base_url}/jobs/{job_id}"
  184. headers = _headers(auth_token, managed=False, json_body=False)
  185. interval = _POLL_INITIAL_INTERVAL
  186. deadline = time.monotonic() + timeout_seconds
  187. last_status: Optional[str] = None
  188. enhance = on_error is None
  189. def give_up(kind: str, detail: Any, warning: str, *warn_args: Any) -> Any:
  190. if on_error is None:
  191. logger.warning(warning, *warn_args)
  192. return None
  193. return on_error(kind, detail)
  194. while True:
  195. time.sleep(interval)
  196. interval = min(interval * _POLL_BACKOFF, _POLL_MAX_INTERVAL)
  197. try:
  198. resp = requests.get(job_url, headers=headers, timeout=30)
  199. resp.raise_for_status()
  200. except requests.HTTPError as exc:
  201. status = exc.response.status_code if exc.response is not None else 0
  202. if not enhance:
  203. logger.error("Krea poll failed (%d) for job %s", status, job_id)
  204. # Fail fast on permanent statuses; retry transient ones.
  205. if status not in _RETRYABLE_POLL_STATUSES or time.monotonic() >= deadline:
  206. return give_up("http", status, "Krea enhance poll failed (%d) for job %s", status, job_id)
  207. continue
  208. except (requests.Timeout, requests.ConnectionError) as exc:
  209. if not enhance:
  210. logger.warning("Krea poll transient error for job %s: %s", job_id, exc)
  211. if time.monotonic() >= deadline:
  212. return give_up("timeout", exc, "Krea enhance poll gave up for job %s: %s", job_id, exc)
  213. continue
  214. except Exception as exc:
  215. if not enhance:
  216. raise
  217. if time.monotonic() >= deadline:
  218. logger.warning("Krea enhance poll gave up for job %s: %s", job_id, exc)
  219. return None
  220. continue
  221. try:
  222. job = resp.json()
  223. except Exception as exc:
  224. if not enhance:
  225. logger.warning("Krea poll returned invalid JSON for job %s: %s", job_id, exc)
  226. if time.monotonic() >= deadline:
  227. return give_up("invalid_json", exc, "Krea enhance poll gave up for job %s: %s", job_id, exc)
  228. continue
  229. if isinstance(job, dict) and isinstance(job.get("status"), str):
  230. last_status = job["status"]
  231. if _is_terminal(job):
  232. return job
  233. if time.monotonic() >= deadline:
  234. return give_up(
  235. "deadline", last_status,
  236. "Krea enhance job %s did not finish in %ds", job_id, int(timeout_seconds))
  237. def _extract_result_url(job: Optional[dict[str, Any]]) -> Optional[str]:
  238. """First result URL: ``result.urls[]`` per Krea's job docs, else ``result.url``."""
  239. result = job.get("result") if isinstance(job, dict) else None
  240. if not isinstance(result, dict):
  241. return None
  242. urls = result.get("urls")
  243. for candidate in [*(urls if isinstance(urls, list) else []), result.get("url")]:
  244. if isinstance(candidate, str) and candidate.strip():
  245. return candidate.strip()
  246. return None
  247. def _enhance_image(
  248. base_url: str, auth_token: str, image_url: str, prompt: str, *, managed: bool
  249. ) -> Optional[str]:
  250. """Krea Enhance on ``image_url`` → enhanced URL, or ``None`` on any failure (best-effort: an
  251. upscale failure must never destroy an already-successful generation)."""
  252. # The prompt guides detail; default ai_strength (0.4) adds detail without redrawing.
  253. payload = {"image_url": image_url, "image_scaling_factor": _ENHANCE_SCALE_FACTOR, "prompt": prompt}
  254. try:
  255. resp = requests.post(
  256. f"{base_url}{_ENHANCE_PATH}", headers=_headers(auth_token, managed=managed, json_body=True),
  257. json=payload, timeout=30)
  258. resp.raise_for_status()
  259. job_id = (resp.json() or {}).get("job_id")
  260. except Exception as exc:
  261. logger.warning("Krea Enhance submit failed: %s", exc)
  262. return None
  263. if not isinstance(job_id, str) or not job_id:
  264. logger.warning("Krea Enhance submit response missing job_id")
  265. return None
  266. job = _poll_krea_job(base_url, auth_token, job_id)
  267. if not isinstance(job, dict) or job.get("status") in {"failed", "cancelled"}:
  268. logger.warning("Krea Enhance job %s did not complete successfully", job_id)
  269. return None
  270. return _extract_result_url(job)
  271. def _collect_style_refs(
  272. image_url: Optional[str], reference_image_urls: Optional[list[str]], legacy_refs: Any
  273. ) -> list[Any]:
  274. """``image_url`` + ``reference_image_urls`` first, then legacy ``image_style_references``
  275. (URL strings or Krea ref objects, passed through); strings deduped in order; capped at 10."""
  276. refs: list[Any] = collect_source_images(image_url, reference_image_urls)
  277. for ref in legacy_refs if isinstance(legacy_refs, list) else []:
  278. if isinstance(ref, str):
  279. if ref.strip():
  280. refs.append(ref.strip())
  281. elif ref:
  282. refs.append(ref)
  283. seen: set = set()
  284. deduped: list[Any] = []
  285. for r in refs:
  286. if isinstance(r, str):
  287. if r in seen:
  288. continue
  289. seen.add(r)
  290. deduped.append(r)
  291. return deduped[:_MAX_STYLE_REFERENCES]
  292. def _inline_local_images(
  293. refs: list[Any], fail: ErrorFn
  294. ) -> tuple[list[Any], Optional[dict[str, Any]]]:
  295. """Embed local image files as data URIs; URLs and data URIs pass through unchanged. A ref is
  296. a Krea 2 ``{url, strength}`` object or a Krea 3 source string; legacy objects pass through."""
  297. from agent.file_safety import raise_if_read_blocked
  298. inlined: list[Any] = []
  299. total_bytes = 0
  300. for ref in refs:
  301. source = ref.get("url") if isinstance(ref, dict) else ref
  302. if not isinstance(source, str) or source.lower().startswith(_REMOTE_REFERENCE_PREFIXES):
  303. inlined.append(ref)
  304. continue
  305. path = Path(source).expanduser()
  306. # Guard first: a denied path must not reveal whether it exists or how large it is.
  307. try:
  308. raise_if_read_blocked(str(path))
  309. except ValueError as exc:
  310. return [], fail(str(exc), "invalid_image_url")
  311. if not path.is_file():
  312. return [], fail(f"Reference image not found: {source}", "invalid_image_url")
  313. # Read at most one byte past the remaining budget: the cap bounds what is sent, not a stat.
  314. try:
  315. with path.open("rb") as fh:
  316. data = fh.read(_MAX_LOCAL_REFERENCE_BYTES - total_bytes + 1)
  317. except OSError as exc: # removed or swapped after the is_file() check
  318. return [], fail(f"Reference image unreadable: {source} ({exc})", "invalid_image_url")
  319. total_bytes += len(data)
  320. if total_bytes > _MAX_LOCAL_REFERENCE_BYTES:
  321. return [], fail(
  322. f"Local reference images total over {_MAX_LOCAL_REFERENCE_BYTES / 2**20:g} MB; "
  323. "resize them or pass public URLs", "source_too_large")
  324. mime = mimetypes.guess_type(path.name)[0] or "image/png"
  325. data_uri = f"data:{mime};base64,{base64.b64encode(data).decode('ascii')}"
  326. inlined.append({**ref, "url": data_uri} if isinstance(ref, dict) else data_uri)
  327. return inlined, None
  328. def _build_payload(
  329. prompt: str, krea_ar: str, creativity: str, style_refs: list[Any], kwargs: dict[str, Any]
  330. ) -> dict[str, Any]:
  331. payload: dict[str, Any] = {
  332. "prompt": prompt, "aspect_ratio": krea_ar, "resolution": DEFAULT_RESOLUTION, "creativity": creativity,
  333. }
  334. if isinstance(kwargs.get("seed"), int):
  335. payload["seed"] = kwargs["seed"]
  336. for slider in _K2_SLIDERS:
  337. value = kwargs.get(slider)
  338. if isinstance(value, int) and not isinstance(value, bool) and -100 <= value <= 100:
  339. payload[slider] = value
  340. styles, moodboards = kwargs.get("styles"), kwargs.get("moodboards")
  341. if isinstance(styles, list) and styles:
  342. payload["styles"] = styles
  343. if style_refs:
  344. # Krea requires objects — a bare string yields 422 "Expected object, received string".
  345. payload["image_style_references"] = [
  346. {"url": ref, "strength": _DEFAULT_STYLE_REFERENCE_STRENGTH} if isinstance(ref, str) else ref
  347. for ref in style_refs
  348. ]
  349. if isinstance(moodboards, list) and moodboards:
  350. payload["moodboards"] = moodboards[:1] # Krea caps at 1 moodboard per request.
  351. return payload
  352. def _submit_job(
  353. base_url: str, auth_token: str, model_path: str, payload: dict[str, Any], managed: bool, model_id: str,
  354. fail: ErrorFn,
  355. ) -> tuple[Optional[str], Optional[dict[str, Any]]]:
  356. """POST the generation request to the model's submit path; ``(job_id, None)`` or ``(None, error)``."""
  357. submit_body, failure = post_json(
  358. f"{base_url}{model_path}",
  359. headers=_headers(auth_token, managed=managed, json_body=True),
  360. payload=payload, timeout=30, label="Krea", error_message=_submit_error_message)
  361. if failure is not None:
  362. def submit_fail(error: str, error_type: str) -> dict[str, Any]:
  363. return {**fail(error, error_type), "fallback_eligible": _fallback_eligible(failure)}
  364. if failure.kind == "http":
  365. status, err_msg = failure.status, failure.message
  366. logger.error("Krea submit failed (%d): %s", status, err_msg)
  367. # Managed 4xx: model not enabled/priced on the Portal, or shared-key concurrency cap (429).
  368. if managed and 400 <= status < 500:
  369. hint = (
  370. "Krea's shared-key concurrency cap was hit — retry shortly." if status == 429 else
  371. f"Model '{model_id}' may not be enabled/priced on the Nous Portal's Krea gateway. "
  372. "Set KREA_API_KEY to use Krea directly, or pick a different model via "
  373. "`hermes tools` → Image Generation.")
  374. return None, submit_fail(
  375. f"Nous Subscription Krea gateway rejected '{model_id}' "
  376. f"(HTTP {status}): {err_msg}. {hint}",
  377. "api_error")
  378. return None, submit_fail(failure.error, "api_error")
  379. if failure.kind == "timeout":
  380. return None, submit_fail("Krea submit timed out (30s)", "timeout")
  381. if failure.kind == "invalid_json":
  382. return None, submit_fail(f"Krea returned invalid JSON on submit: {failure.message}", "invalid_response")
  383. return None, submit_fail(failure.error, failure.error_type)
  384. job_id = submit_body.get("job_id")
  385. if not isinstance(job_id, str) or not job_id:
  386. return None, fail("Krea submit response missing job_id", "invalid_response")
  387. return job_id, None
  388. def _terminal_result_url(
  389. job: dict[str, Any], job_id: str, fail: ErrorFn
  390. ) -> tuple[Optional[str], Optional[dict[str, Any]]]:
  391. """Result URL of a terminal job; ``(url, None)`` or ``(None, error)``."""
  392. result = job.get("result")
  393. if job.get("status") == "failed":
  394. err = result.get("error") if isinstance(result, dict) else None
  395. return None, fail(f"Krea job {job_id} failed: {err or 'unknown error'}", "api_error")
  396. if job.get("status") == "cancelled":
  397. return None, fail(f"Krea job {job_id} was cancelled", "cancelled")
  398. if not isinstance(result, dict):
  399. return None, fail("Krea job completed but result was missing", "empty_response")
  400. result_image_url = _extract_result_url(job)
  401. if result_image_url is None:
  402. return None, fail("Krea result contained no image URL", "empty_response")
  403. return result_image_url, None
  404. def _upscale_requested(explicit: Any, meta: dict[str, Any]) -> bool:
  405. """Precedence: explicit kwarg > ``image_gen.krea.upscale`` config > per-model catalog default."""
  406. if isinstance(explicit, bool):
  407. return explicit
  408. cfg_upscale = _krea_section().get("upscale")
  409. return cfg_upscale if isinstance(cfg_upscale, bool) else bool(meta.get("upscale", False))
  410. def _krea2_payload(
  411. prompt: str, krea_ar: str, image_url: Optional[str], reference_image_urls: Optional[list[str]],
  412. kwargs: dict[str, Any], managed: bool, fail: ErrorFn,
  413. ) -> tuple[dict[str, Any], Optional[dict[str, Any]]]:
  414. """Krea 2 request body: the pictures given are style references whose look is copied."""
  415. style_refs = _collect_style_refs(image_url, reference_image_urls, kwargs.get("image_style_references"))
  416. payload = _build_payload(prompt, krea_ar, _resolve_creativity(kwargs.get("creativity")), style_refs, kwargs)
  417. # LoRAs/moodboards are rejected by the managed gateway: fail fast with guidance, not a raw 400.
  418. if managed:
  419. for what, arg in _MANAGED_UNSUPPORTED:
  420. if arg in payload:
  421. return payload, fail(
  422. f"Managed Krea (Nous Subscription) does not support {what}. "
  423. f"Set KREA_API_KEY to use Krea directly, or omit `{arg}`.",
  424. "unsupported_argument")
  425. # After the fail-fast above, so a request about to be refused never reads local files.
  426. if payload.get("image_style_references"):
  427. payload["image_style_references"], err = _inline_local_images(payload["image_style_references"], fail)
  428. if err is not None:
  429. return payload, err
  430. return payload, None
  431. def _krea3_payload(
  432. prompt: str, krea_ar: str, image_url: Optional[str], reference_image_urls: Optional[list[str]],
  433. kwargs: dict[str, Any], fail: ErrorFn,
  434. ) -> tuple[dict[str, Any], Optional[dict[str, Any]]]:
  435. """Krea 3 request body: the pictures given are edited; resolution and thinking mode are priced.
  436. An edit sends no aspect ratio, so Krea keeps the picture's own framing."""
  437. sources = list(dict.fromkeys(collect_source_images(image_url, reference_image_urls)))
  438. image_urls, err = _inline_local_images(sources[:_MAX_KREA3_REFERENCE_IMAGES], fail)
  439. if err is not None:
  440. return {}, err
  441. resolution = str(kwargs.get("resolution") or "").upper()
  442. payload: dict[str, Any] = {
  443. "prompt": prompt,
  444. "resolution": resolution if resolution in _KREA3_RESOLUTIONS else DEFAULT_RESOLUTION,
  445. "thinking_mode": "high" if kwargs.get("thinking") == "high" else "fast",
  446. }
  447. if image_urls:
  448. payload["image_urls"] = image_urls
  449. else:
  450. payload["aspect_ratio"] = krea_ar
  451. if isinstance(kwargs.get("seed"), int):
  452. payload["seed"] = kwargs["seed"]
  453. return payload, None
  454. class KreaImageGenProvider(StaticImageGenProvider):
  455. """Krea image backend: Krea 3 (generate and edit) and Krea 2 (Medium, Large, Medium Turbo)."""
  456. provider_id = "krea"
  457. label = "Krea"
  458. models = _MODELS
  459. default_model_id = DEFAULT_MODEL
  460. setup = dict(
  461. name="Krea", badge="paid",
  462. tag="Krea 3 — generates and edits images ($0.03 at 1K, $0.06 at 2K) — and Krea 2 Medium ($0.03), Large ($0.06), Medium Turbo ($0.015) with style transfer and moodboards. Direct key or managed Nous Subscription gateway.",
  463. key="KREA_API_KEY", prompt="Krea API key", url="https://www.krea.ai/settings/api-tokens")
  464. def is_available(self) -> bool:
  465. # Direct key OR managed Nous gateway (portal users without a Krea key).
  466. return bool(get_secret("KREA_API_KEY")) or _managed_krea_gateway_ready()
  467. def capabilities(self) -> dict[str, Any]:
  468. # Both dispatchers (managed and direct) name the stored ``image_gen.model`` explicitly; resolve
  469. # the same way so the schema describes the model that will run, whatever KREA_IMAGE_MODEL says.
  470. stored = _load_krea_config().get("model")
  471. _, meta = _resolve_model(stored if isinstance(stored, str) else None)
  472. if meta.get("edit"):
  473. return {
  474. "modalities": ["text", "image"], "max_reference_images": _MAX_KREA3_REFERENCE_IMAGES,
  475. "supports_upscale": True, "creative_controls": list(_KREA3_CONTROLS),
  476. }
  477. return {
  478. "modalities": ["text", "image"], "max_reference_images": _MAX_STYLE_REFERENCES,
  479. "supports_upscale": True, "creative_controls": ["creativity", *_K2_SLIDERS],
  480. "source_image_role": "style",
  481. }
  482. def generate(
  483. self, prompt: str, aspect_ratio: str = DEFAULT_ASPECT_RATIO, *,
  484. image_url: Optional[str] = None, reference_image_urls: Optional[list[str]] = None,
  485. **kwargs: Any,
  486. ) -> dict[str, Any]:
  487. prompt = (prompt or "").strip()
  488. aspect = resolve_aspect_ratio(aspect_ratio)
  489. krea_ar = _ASPECT_MAP.get(aspect, "1:1")
  490. if not prompt:
  491. return prompt_required_error("krea", aspect)
  492. # Managed gateway owns the shared Krea credential and meters per generation (token =
  493. # Nous access token); otherwise direct Krea with a BYO ``KREA_API_KEY``.
  494. managed = _resolve_managed_krea_gateway()
  495. if managed is not None:
  496. base_url = managed.gateway_origin.rstrip("/")
  497. auth_token = managed.nous_user_token
  498. else:
  499. base_url = BASE_URL
  500. auth_token = get_secret("KREA_API_KEY")
  501. if not auth_token:
  502. return error_factory("krea", aspect)(
  503. "KREA_API_KEY not set. Run `hermes tools` → Image "
  504. "Generation → Krea to configure, get a key at "
  505. "https://www.krea.ai/settings/api-tokens, or sign in to "
  506. "a Nous account with the managed Krea gateway enabled "
  507. "(`hermes setup`).",
  508. "auth_required")
  509. model_id, meta = _resolve_model(kwargs.get("model"))
  510. fail = error_factory("krea", aspect, model=model_id, prompt=prompt)
  511. if meta.get("edit"):
  512. payload, err = _krea3_payload(prompt, krea_ar, image_url, reference_image_urls, kwargs, fail)
  513. else:
  514. payload, err = _krea2_payload(
  515. prompt, krea_ar, image_url, reference_image_urls, kwargs, managed is not None, fail)
  516. if err is not None:
  517. return err
  518. # 1. Submit job.
  519. job_id, err = _submit_job(
  520. base_url, auth_token, meta["path"], payload, managed is not None, model_id, fail)
  521. if err is not None:
  522. return err
  523. # 2. Poll — same principal as submit, so the managed path polls the gateway with the Nous token.
  524. poll_errors: list[dict[str, Any]] = []
  525. def poll_error(kind: str, detail: Any) -> dict[str, Any]:
  526. error_type, build = _POLL_FAILURES.get(kind, _POLL_FAILURES["deadline"])
  527. poll_errors.append(fail(build(job_id, detail), error_type))
  528. return poll_errors[-1]
  529. job = _poll_krea_job(base_url, auth_token, job_id, on_error=poll_error)
  530. if poll_errors:
  531. return poll_errors[0]
  532. if not isinstance(job, dict):
  533. return fail("Krea returned non-dict job body", "invalid_response")
  534. # 3. Terminal — extract result.
  535. result_image_url, err = _terminal_result_url(job, job_id, fail)
  536. if err is not None:
  537. return err
  538. # Krea Enhance pass — best-effort: failure falls back to the original image.
  539. upscaled = False
  540. if _upscale_requested(kwargs.get("upscale"), meta):
  541. enhanced_url = _enhance_image(
  542. base_url, auth_token, result_image_url, prompt, managed=managed is not None)
  543. if enhanced_url:
  544. result_image_url = enhanced_url
  545. upscaled = True
  546. else:
  547. logger.warning("Krea Enhance pass failed — returning native-resolution image")
  548. # Materialise locally — Krea result URLs may expire.
  549. try:
  550. # See #26942.
  551. image_ref = str(save_url_image(result_image_url, prefix=f"krea_{model_id}"))
  552. except Exception as exc:
  553. logger.warning(
  554. "Krea image URL %s could not be cached (%s); falling back to bare URL.", result_image_url, exc,
  555. )
  556. image_ref = result_image_url
  557. extra: dict[str, Any] = {"resolution": payload["resolution"], "job_id": job_id, "upscaled": upscaled}
  558. for key, name in (("aspect_ratio", "krea_aspect_ratio"), ("creativity", "creativity"), ("thinking_mode", "thinking_mode")):
  559. if key in payload:
  560. extra[name] = payload[key]
  561. if upscaled:
  562. extra["upscale_factor"] = _ENHANCE_SCALE_FACTOR
  563. if isinstance(job.get("completed_at"), str):
  564. extra["completed_at"] = job["completed_at"]
  565. has_images = bool(payload.get("image_style_references") or payload.get("image_urls"))
  566. return success_response(
  567. image=image_ref, model=model_id, prompt=prompt, aspect_ratio=aspect, provider="krea",
  568. modality="image" if has_images else "text", extra=extra)
  569. def register(ctx) -> None:
  570. """Plugin entry point — wire ``KreaImageGenProvider`` into the registry."""
  571. ctx.register_image_gen_provider(KreaImageGenProvider())