image_generation_catalog.py 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398
  1. """FAL image model catalog + upscaler constants for ``tools.image_generation_tool``.
  2. Each entry translates the unified inputs (prompt + aspect_ratio) into the model's native
  3. payload. ``size_style``: ``"image_size_preset"`` (FAL preset enum), ``"aspect_ratio"`` (ratio
  4. enum), ``"gpt_literal"`` (literal "WxH"). ``supports`` / ``edit_supports`` are whitelists —
  5. other keys are stripped so models never receive rejected parameters. ``upscale`` is False
  6. everywhere: Clarity redraws content (creativity 0.35) and degraded text/CJK/faces when
  7. default-on, so upscaling is strictly per-call opt-in. Pricing strings may drift.
  8. """
  9. from typing import Any, Dict, Optional
  10. _PRESET_SIZES = {"landscape": "landscape_16_9", "square": "square_hd", "portrait": "portrait_16_9"}
  11. _ASPECT_SIZES = {"landscape": "16:9", "square": "1:1", "portrait": "9:16"}
  12. _DEFAULT_SIZES = {"image_size_preset": _PRESET_SIZES, "aspect_ratio": _ASPECT_SIZES}
  13. def _model(
  14. display: str, speed: str, strengths: str, price: str, *, style: str = "image_size_preset",
  15. sizes: Optional[dict[str, Any]] = None, defaults: dict[str, Any], supports: set,
  16. edit_endpoint: Optional[str] = None, edit_supports: Optional[set] = None,
  17. max_reference_images: Optional[int] = None, edit_image_param: Optional[str] = None,
  18. ) -> dict[str, Any]:
  19. """Build one catalog entry; edit keys are present only for edit-capable models. ``edit_image_param``
  20. names the source-image key when the edit endpoint takes a singular ``image_url`` instead of ``image_urls``."""
  21. entry: dict[str, Any] = {
  22. "display": display, "speed": speed, "strengths": strengths, "price": price,
  23. "size_style": style, "sizes": sizes if sizes is not None else _DEFAULT_SIZES[style],
  24. "defaults": defaults, "supports": supports, "upscale": False,
  25. }
  26. if edit_endpoint:
  27. entry["edit_endpoint"] = edit_endpoint
  28. entry["edit_supports"] = edit_supports
  29. entry["max_reference_images"] = max_reference_images
  30. if edit_image_param:
  31. entry["edit_image_param"] = edit_image_param
  32. return entry
  33. FAL_MODELS: dict[str, dict[str, Any]] = {
  34. "fal-ai/flux-2/klein/9b": _model(
  35. "FLUX 2 Klein 9B", "<1s", "Fast, crisp text", "$0.006/MP",
  36. defaults={
  37. "num_inference_steps": 4, "output_format": "png", "enable_safety_checker": False,
  38. },
  39. supports={
  40. "prompt", "image_size", "num_inference_steps", "seed", "output_format", "enable_safety_checker",
  41. },
  42. edit_endpoint="fal-ai/flux-2/klein/9b/edit",
  43. edit_supports={
  44. "prompt", "image_urls", "num_inference_steps", "seed", "output_format", "enable_safety_checker",
  45. },
  46. max_reference_images=9,
  47. ),
  48. "fal-ai/flux-2-pro": _model(
  49. "FLUX 2 Pro", "~6s", "Studio photorealism", "$0.03/MP",
  50. defaults={
  51. "num_inference_steps": 50, "guidance_scale": 4.5, "num_images": 1,
  52. "output_format": "png", "enable_safety_checker": False, "safety_tolerance": "5",
  53. "sync_mode": True,
  54. },
  55. supports={
  56. "prompt", "image_size", "num_inference_steps", "guidance_scale", "num_images", "output_format",
  57. "enable_safety_checker", "safety_tolerance", "sync_mode", "seed",
  58. },
  59. edit_endpoint="fal-ai/flux-2-pro/edit",
  60. edit_supports={
  61. "prompt", "image_urls", "num_inference_steps", "guidance_scale", "num_images", "output_format",
  62. "enable_safety_checker", "safety_tolerance", "sync_mode", "seed",
  63. },
  64. max_reference_images=9,
  65. ),
  66. "fal-ai/z-image/turbo": _model(
  67. "Z-Image Turbo", "~2s", "Bilingual EN/CN, 6B", "$0.005/MP",
  68. defaults={ # prompt expansion off: avoids the extra per-request charge
  69. "num_inference_steps": 8, "num_images": 1, "output_format": "png",
  70. "enable_safety_checker": False, "enable_prompt_expansion": False,
  71. },
  72. supports={
  73. "prompt", "image_size", "num_inference_steps", "num_images", "seed", "output_format",
  74. "enable_safety_checker", "enable_prompt_expansion",
  75. },
  76. ),
  77. "fal-ai/nano-banana-pro": _model(
  78. "Nano Banana Pro (Gemini 3 Pro Image)", "~8s", "Gemini 3 Pro, reasoning depth, text rendering", "$0.15/image (1K)",
  79. style="aspect_ratio",
  80. # "1K" is the cheapest tier; 4K doubles the per-image cost (Nous Subscription billing).
  81. defaults={
  82. "num_images": 1, "output_format": "png", "safety_tolerance": "5",
  83. "resolution": "1K",
  84. },
  85. supports={
  86. "prompt", "aspect_ratio", "num_images", "output_format", "safety_tolerance", "seed", "sync_mode",
  87. "resolution", "enable_web_search", "limit_generations",
  88. },
  89. edit_endpoint="fal-ai/nano-banana-pro/edit",
  90. edit_supports={
  91. "prompt", "image_urls", "aspect_ratio", "num_images", "output_format", "safety_tolerance", "seed",
  92. "sync_mode", "resolution", "enable_web_search", "limit_generations",
  93. },
  94. max_reference_images=2,
  95. ),
  96. "fal-ai/nano-banana-2": _model(
  97. "Nano Banana 2 (Gemini 3.1 Flash Image)", "~3s", "Fast reasoning, multilingual text, infographics", "Lower-cost Flash tier",
  98. style="aspect_ratio",
  99. defaults={
  100. "num_images": 1, "output_format": "png", "safety_tolerance": "4",
  101. "resolution": "1K", "limit_generations": True,
  102. },
  103. supports={
  104. "prompt", "aspect_ratio", "num_images", "output_format", "safety_tolerance", "seed", "sync_mode",
  105. "system_prompt", "resolution", "enable_web_search", "limit_generations", "thinking_level",
  106. },
  107. edit_endpoint="fal-ai/nano-banana-2/edit",
  108. edit_supports={
  109. "prompt", "image_urls", "aspect_ratio", "num_images", "output_format", "safety_tolerance", "seed",
  110. "sync_mode", "system_prompt", "resolution", "enable_web_search", "limit_generations",
  111. "thinking_level",
  112. },
  113. max_reference_images=14,
  114. ),
  115. "fal-ai/gpt-image-1.5": _model(
  116. "GPT Image 1.5", "~15s", "Prompt adherence", "$0.034/image",
  117. style="gpt_literal", sizes={
  118. "landscape": "1536x1024", "square": "1024x1024", "portrait": "1024x1536",
  119. },
  120. # quality pinned to medium (also for gpt-image-2) so portal billing stays
  121. # predictable: low is too rough, high is 3-6x the per-image cost.
  122. defaults={"quality": "medium", "num_images": 1, "output_format": "png"},
  123. supports={
  124. "prompt", "image_size", "quality", "num_images", "output_format", "background", "sync_mode",
  125. },
  126. edit_endpoint="fal-ai/gpt-image-1.5/edit",
  127. edit_supports={
  128. "prompt", "image_urls", "image_size", "quality", "num_images", "output_format", "sync_mode",
  129. },
  130. max_reference_images=16,
  131. ),
  132. # GPT Image 2 uses FAL's preset enum (unlike 1.5's literal dims) mapped to the
  133. # 4:3 variants: the 16:9 presets (1024x576) fall below its 655,360 min-pixel
  134. # requirement. openai_api_key (BYOK) is deliberately not in `supports` — all
  135. # users go through the shared FAL billing path. Its edit endpoint lives under
  136. # the OpenAI namespace (NOT fal-ai/) and auto-infers size, so no image_size.
  137. "fal-ai/gpt-image-2": _model(
  138. "GPT Image 2", "~20s", "SOTA text rendering + CJK, world-aware photorealism", "$0.04–0.06/image",
  139. style="image_size_preset", sizes={
  140. "landscape": "landscape_4_3", "square": "square_hd", "portrait": "portrait_4_3",
  141. },
  142. defaults={"quality": "medium", "num_images": 1, "output_format": "png"},
  143. supports={
  144. "prompt", "image_size", "quality", "num_images", "output_format", "sync_mode",
  145. },
  146. edit_endpoint="openai/gpt-image-2/edit",
  147. edit_supports={
  148. "prompt", "image_urls", "quality", "num_images", "output_format", "sync_mode", "mask_image_url",
  149. },
  150. max_reference_images=16,
  151. ),
  152. # Same minimum pixel count as GPT Image 2; keep medium quality explicit
  153. # rather than inheriting FAL's higher-cost high default.
  154. **{
  155. f"openai/gpt-image-2.5/{variant}/text-to-image": _model(
  156. f"GPT Image 2.5 {variant.title()}", speed, strengths, "Token-based pricing",
  157. sizes={
  158. "landscape": "landscape_4_3", "square": "square_hd", "portrait": "portrait_4_3",
  159. },
  160. defaults={"quality": "medium", "num_images": 1, "output_format": "png"},
  161. supports={
  162. "prompt", "image_size", "quality", "num_images", "output_format", "background",
  163. "output_compression", "sync_mode",
  164. },
  165. edit_endpoint=f"openai/gpt-image-2.5/{variant}/edit",
  166. edit_supports={
  167. "prompt", "image_urls", "image_size", "quality", "num_images", "output_format",
  168. "background", "output_compression", "sync_mode", "mask_url", "input_fidelity",
  169. },
  170. max_reference_images=16,
  171. )
  172. for variant, speed, strengths in (
  173. ("flare", "Fast", "Everyday creation, natural lighting and textures"),
  174. ("sunburst", "Slower", "Precision editing, subject and composition consistency"),
  175. )
  176. },
  177. "fal-ai/ideogram/v3": _model(
  178. "Ideogram V3", "~5s", "Best typography", "$0.03-0.09/image",
  179. defaults={"rendering_speed": "BALANCED", "expand_prompt": True, "style": "AUTO"},
  180. supports={
  181. "prompt", "image_size", "rendering_speed", "expand_prompt", "style", "seed",
  182. },
  183. edit_endpoint="fal-ai/ideogram/v3/edit",
  184. edit_supports={
  185. "prompt", "image_urls", "rendering_speed", "expand_prompt", "style", "seed",
  186. },
  187. max_reference_images=1,
  188. ),
  189. "fal-ai/recraft/v4/pro/text-to-image": _model(
  190. "Recraft V4 Pro", "~8s", "Design, brand systems, production-ready", "$0.25/image",
  191. defaults={"enable_safety_checker": False}, # V4 Pro dropped V3's required `style` enum
  192. supports={
  193. "prompt", "image_size", "enable_safety_checker", "colors", "background_color",
  194. },
  195. ),
  196. "fal-ai/qwen-image": _model(
  197. "Qwen Image", "~12s", "LLM-based, complex text", "$0.02/MP",
  198. defaults={
  199. "num_inference_steps": 30, "guidance_scale": 2.5, "num_images": 1,
  200. "output_format": "png", "acceleration": "regular",
  201. },
  202. supports={
  203. "prompt", "image_size", "num_inference_steps", "guidance_scale", "num_images", "output_format",
  204. "acceleration", "seed", "sync_mode",
  205. },
  206. edit_endpoint="fal-ai/qwen-image-2/pro/edit",
  207. edit_supports={
  208. "prompt", "image_urls", "num_inference_steps", "guidance_scale", "num_images", "output_format",
  209. "acceleration", "seed", "sync_mode",
  210. },
  211. max_reference_images=3,
  212. ),
  213. # Krea 2 on FAL — same family as ``plugins/image_gen/krea`` but billed through
  214. # FAL / the FAL managed gateway. Native ``krea-2-*`` ids route to the plugin.
  215. "fal-ai/krea/v2/medium/text-to-image": _model(
  216. "Krea 2 Medium", "~15-25s", "Illustration, anime, painting, expressive/artistic styles", "$0.030 (text) / $0.035 (style refs)",
  217. style="aspect_ratio",
  218. defaults={"creativity": "medium"},
  219. supports={
  220. "prompt", "aspect_ratio", "creativity", "seed", "image_style_references",
  221. },
  222. ),
  223. "fal-ai/krea/v2/large/text-to-image": _model(
  224. "Krea 2 Large", "~25-60s", "Photorealism, raw textured looks (motion blur, grain, film)", "$0.060 (text) / $0.065 (style refs)",
  225. style="aspect_ratio",
  226. defaults={"creativity": "medium"},
  227. supports={
  228. "prompt", "aspect_ratio", "creativity", "seed", "image_style_references",
  229. },
  230. ),
  231. # Entries below take endpoint ids, `supports` whitelists and enum defaults from
  232. # each model's FAL OpenAPI schema; paired `/edit` apps hang off their
  233. # text-to-image entry rather than appearing as separate picker rows.
  234. # Seedream Pro requires total pixels between 1024² and 2048² — explicit
  235. # ImageSize dicts keep every aspect inside that window.
  236. "bytedance/seedream/v5/pro/text-to-image": _model(
  237. "Seedream 5.0 Pro", "~10s", "ByteDance flagship, dense layouts, native text in 14 languages", "$0.0675/image (≤1536²)",
  238. style="image_size_preset", sizes={
  239. "landscape": {"width": 2048, "height": 1152},
  240. "square": {"width": 1536, "height": 1536},
  241. "portrait": {"width": 1152, "height": 2048},
  242. },
  243. defaults={
  244. "num_images": 1, "output_format": "png", "enable_safety_checker": False,
  245. },
  246. supports={
  247. "prompt", "image_size", "num_images", "output_format", "sync_mode", "enable_safety_checker",
  248. },
  249. edit_endpoint="bytedance/seedream/v5/pro/edit",
  250. edit_supports={
  251. "prompt", "image_urls", "image_size", "num_images", "output_format", "sync_mode",
  252. "enable_safety_checker",
  253. },
  254. max_reference_images=10,
  255. ),
  256. # Lite wants 2560x1440..4096x4096 total pixels: use the documented presets (FAL
  257. # auto-scales under the floor) rather than hand-rolled dicts that drift.
  258. "bytedance/seedream/v5/lite/text-to-image": _model(
  259. "Seedream 5.0 Lite", "~5s", "Fast/cheap Seedream tier, high-res output", "$0.035/image",
  260. defaults={"num_images": 1, "enable_safety_checker": False},
  261. supports={
  262. "prompt", "image_size", "num_images", "max_images", "sync_mode", "enable_safety_checker",
  263. },
  264. ),
  265. "ideogram/v4/instant": _model(
  266. "Ideogram V4 (Instant)", "<1s", "Latest Ideogram typography, posters/logos, instant", "$0.0075/MP",
  267. defaults={
  268. "expansion_model": "Medium", "output_format": "png",
  269. "enable_safety_checker": False,
  270. },
  271. supports={
  272. "prompt", "image_size", "expansion_model", "num_images", "seed", "sync_mode",
  273. "enable_safety_checker", "output_format",
  274. },
  275. ),
  276. "ideogram/v4/fast": _model(
  277. "Ideogram V4 (Fast)", "~1s", "Ideogram V4 quality tiers via rendering_speed", "$0.005-0.018/MP",
  278. defaults={"expansion_model": "Medium", "rendering_speed": "BALANCED"},
  279. supports={
  280. "prompt", "image_size", "expansion_model", "rendering_speed", "num_images", "seed", "sync_mode",
  281. },
  282. ),
  283. "alibaba/qwen-image-3/text-to-image": _model(
  284. "Qwen Image 3", "~8s", "Complex CN/EN text rendering, prompt-guided resolution", "$0.04 (1K) / $0.075 (2K) per image",
  285. defaults={
  286. "num_images": 1, "output_format": "png", "enable_prompt_expansion": False,
  287. "enable_safety_checker": False,
  288. },
  289. supports={
  290. "prompt", "negative_prompt", "image_size", "num_images", "seed", "sync_mode", "output_format",
  291. "enable_prompt_expansion", "enable_safety_checker",
  292. },
  293. edit_endpoint="alibaba/qwen-image-3/edit",
  294. edit_supports={
  295. "prompt", "image_urls", "negative_prompt", "num_images", "seed", "sync_mode", "output_format",
  296. "enable_prompt_expansion", "enable_safety_checker",
  297. },
  298. max_reference_images=3,
  299. ),
  300. "microsoft/mai-image-2.5-pro": _model(
  301. "MAI Image 2.5 Pro", "~10s", "Microsoft flagship, hero imagery, precise typography", "~$0.17/image",
  302. style="aspect_ratio",
  303. defaults={"num_images": 1, "output_format": "png"},
  304. supports={"prompt", "aspect_ratio", "num_images", "output_format", "sync_mode"},
  305. ),
  306. "google/nano-banana-2-lite": _model(
  307. "Nano Banana 2 Lite", "<2s", "Gemini image family, sub-2s, 14 aspect ratios incl. extreme", "~$0.04/image (1K fixed)",
  308. style="aspect_ratio",
  309. defaults={"num_images": 1, "output_format": "png", "safety_tolerance": "5"},
  310. supports={
  311. "prompt", "aspect_ratio", "num_images", "seed", "output_format", "safety_tolerance", "sync_mode",
  312. "system_prompt", "limit_generations", "thinking_level",
  313. },
  314. edit_endpoint="google/nano-banana-2-lite/edit",
  315. edit_supports={
  316. "prompt", "image_urls", "aspect_ratio", "num_images", "seed", "output_format", "safety_tolerance",
  317. "sync_mode", "system_prompt",
  318. },
  319. max_reference_images=4,
  320. ),
  321. "fal-ai/recraft/v4.1/text-to-image": _model(
  322. "Recraft V4.1", "~8s", "Design-first raster, brand systems, editorial", "$0.035/image",
  323. defaults={"enable_safety_checker": False},
  324. supports={
  325. "prompt", "image_size", "enable_safety_checker", "colors", "background_color",
  326. },
  327. ),
  328. "xai/grok-imagine-image/v2.0/text-to-image": _model(
  329. "Grok Imagine Image 2.0", "~5s", "xAI. Design-grade typography/layout, instruction following", "$0.06/image (1K medium)",
  330. style="aspect_ratio",
  331. # 1k + medium is the cheapest sensible tier; 2k is roughly +33%/image. 1k native
  332. # is sub-2MP — pass upscale=true per call when needed. Edits omit aspect_ratio
  333. # (defaults to "auto", following the first input image).
  334. defaults={
  335. "num_images": 1, "output_format": "png", "resolution": "1k", "quality": "medium",
  336. },
  337. supports={
  338. "prompt", "aspect_ratio", "num_images", "output_format", "resolution", "quality", "sync_mode",
  339. },
  340. edit_endpoint="xai/grok-imagine-image/v2.0/edit",
  341. edit_supports={
  342. "prompt", "image_urls", "num_images", "output_format", "resolution", "quality", "sync_mode",
  343. },
  344. max_reference_images=3,
  345. ),
  346. # 1K and 2K cost the same ($0.028/img) so 2K is the default. The i2i endpoint takes a SINGULAR
  347. # `image_url` (one reference image), unlike every other FAL edit endpoint's `image_urls` list.
  348. "fal-ai/kling-image/v3/text-to-image": _model(
  349. "Kling Image v3", "~10s", "Kuaishou. Realistic detail, cheap native 2K, wide AR set", "$0.028/image",
  350. style="aspect_ratio",
  351. defaults={"num_images": 1, "output_format": "png", "resolution": "2K"},
  352. supports={
  353. "prompt", "aspect_ratio", "num_images", "output_format", "resolution", "negative_prompt", "sync_mode",
  354. },
  355. edit_endpoint="fal-ai/kling-image/v3/image-to-image",
  356. edit_supports={
  357. "prompt", "image_url", "aspect_ratio", "num_images", "output_format", "resolution", "sync_mode",
  358. },
  359. max_reference_images=1, edit_image_param="image_url",
  360. ),
  361. "meta/muse-image/text-to-image": _model(
  362. "Meta Muse Image", "~5s", "Meta. Realism + typography at commodity price", "$0.01/image",
  363. style="aspect_ratio",
  364. # Muse accepts 21:9…9:21; aspect_ratio is always sent on text-to-image for deterministic
  365. # framing and omitted on edits so Muse follows the input image. No seed in the vendor
  366. # schema (like Grok Imagine 2.0) — the supports whitelist filters it.
  367. defaults={"num_images": 1, "output_format": "png"},
  368. supports={"prompt", "aspect_ratio", "num_images", "output_format", "sync_mode"},
  369. edit_endpoint="meta/muse-image/edit",
  370. edit_supports={"prompt", "image_urls", "num_images", "output_format", "sync_mode"},
  371. max_reference_images=10,
  372. ),
  373. }
  374. # Fastest reasonable option; cheap and sub-1s.
  375. DEFAULT_MODEL = "fal-ai/flux-2/klein/9b"
  376. DEFAULT_ASPECT_RATIO = "landscape"
  377. VALID_ASPECT_RATIOS = ("landscape", "square", "portrait")
  378. # Clarity Upscaler settings.
  379. UPSCALER_MODEL = "fal-ai/clarity-upscaler"
  380. UPSCALER_FACTOR = 2
  381. UPSCALER_SAFETY_CHECKER = False
  382. UPSCALER_DEFAULT_PROMPT = "masterpiece, best quality, highres"
  383. UPSCALER_NEGATIVE_PROMPT = "(worst quality, low quality, normal quality:2)"
  384. UPSCALER_CREATIVITY = 0.35
  385. UPSCALER_RESEMBLANCE = 0.6
  386. UPSCALER_GUIDANCE_SCALE = 4
  387. UPSCALER_NUM_INFERENCE_STEPS = 18