sjjUdZddlmZddlZddlZddlZddlZddlmZm Z m Z m Z m Z ddl mZmZmZejeZdddd dd d dddd d d ddddddddddd d d ddddddddddd ddd ddd d!d d"d#d$d%d&d'd d d( d)dd d*d d+d,dd-dd ddd d.d/d d0d d1d2d3ddd4d ddd5id6d7d8d/d9d d:d;dd?d@dAd dBd3dCddDdEdFdGdGdGdGdHdHdIdIdJdKdLdMddNddOddPdd dQd dRdSd dTdUdVd dddWdXdd dYd dZd[d d3d\d-ddddd]d^dd d_d dd`d d$ddaddddWdbdcd ddd dedfdgdhddid d dj dkdd dld dmdndddddd do Zdpedq<drZddvZdd{Zdd|Zed}d~hZddZddZddZdadsed<ej Z!ddZ"da#dsed<da$dsed<ej Z%dZ&dZ'ddZ(ddZ)dZ*dZ+ dddZ,GddeZ-ddZ.dS)uFAL.ai video generation backend. User-facing surface: pick a **model family** (e.g. "Pixverse v6", "Veo 3.1", "Seedance 2.0", "Kling v3 4K", "LTX 2.3", "Happy Horse"). The plugin auto-routes to the family's text-to-video endpoint when called without ``image_url``, and to its image-to-video endpoint when ``image_url`` is provided. The agent never sees the routing — it just calls ``video_generate(prompt=..., image_url=...)``. Model families (most expose both t2v + i2v; gemini-omni-flash is image-to-video only): Cheap tier: ltx-2.3 fal-ai/ltx-2.3-22b/text-to-video / fal-ai/ltx-2.3-22b/image-to-video pixverse-v6 fal-ai/pixverse/v6/text-to-video / fal-ai/pixverse/v6/image-to-video seedance-2.0-mini bytedance/seedance-2.0/mini/text-to-video / bytedance/seedance-2.0/mini/image-to-video Premium tier: veo3.1 fal-ai/veo3.1 / fal-ai/veo3.1/image-to-video seedance-2.0 bytedance/seedance-2.0/text-to-video / bytedance/seedance-2.0/image-to-video seedance-2.5 bytedance/seedance-2.5/text-to-video / bytedance/seedance-2.5/image-to-video minimax-h3 minimax/h3/text-to-video / minimax/h3/image-to-video flux-3 blackforestlabs/flux-3/text-to-video / blackforestlabs/flux-3/image-to-video grok-imagine-1.5 xai/grok-imagine-video/v1.5/text-to-video / xai/grok-imagine-video/v1.5/image-to-video kling-v3-4k fal-ai/kling-video/v3/4k/text-to-video / fal-ai/kling-video/v3/4k/image-to-video happy-horse alibaba/happy-horse/text-to-video / alibaba/happy-horse/image-to-video Image-to-video only (no text_endpoint): gemini-omni-flash google/gemini-omni-flash/image-to-video Selection precedence for the active family: 1. ``model=`` arg from the tool call 2. ``FAL_VIDEO_MODEL`` env var 3. ``video_gen.fal.model`` in ``config.yaml`` 4. ``video_gen.model`` in ``config.yaml`` (when it's one of our family IDs or a full endpoint path that contains a family ID) 5. ``DEFAULT_MODEL`` Authentication via ``FAL_KEY`` or the managed Nous gateway. Output is an HTTPS URL from FAL's CDN; the gateway downloads and delivers it. ) annotationsN)AnyDictListOptionalTuple)VideoGenProvidererror_responsesuccess_responsez LTX 2.3 (22B)z~30-60scheapz322B model with native audio generation. Affordable.z fal-ai/ltx-2.3-22b/text-to-videoz!fal-ai/ltx-2.3-22b/image-to-videoT) displayspeedprice strengthstier text_endpointimage_endpoint aspect_ratios resolutions durationsaudionegativez Pixverse v6z~30-90sz.Affordable. Negative prompts. 1-15s durations.z fal-ai/pixverse/v6/text-to-videoz!fal-ai/pixverse/v6/image-to-video360p540p720p1080p)zSeedance 2.0 MinizAByteDance. Faster/cheaper Seedance tier, audio + lip-sync, 4-15s.z)bytedance/seedance-2.0/mini/text-to-videoz*bytedance/seedance-2.0/mini/image-to-video)21:916:94:31:13:49:16)480pr)rF) r rrrrrrrrrrrseedzVeo 3.1z~60-120spremiumzBGoogle DeepMind. Cinematic, native audio, strong prompt adherence.z fal-ai/veo3.1zfal-ai/veo3.1/image-to-video)r!r%)rr4k)r's) r rrrrrrrrrduration_suffixrrz Seedance 2.0z;ByteDance. Cinematic, synchronized audio + lip-sync, 4-15s.z$bytedance/seedance-2.0/text-to-videoz%bytedance/seedance-2.0/image-to-video)r&rrz Seedance 2.5z~60-180szUByteDance flagship. Native 30s single-pass, audio in the same latent space, lip-sync.z$bytedance/seedance-2.5/text-to-videoz%bytedance/seedance-2.5/image-to-video) aspect_ratio)r')r rrrrrrimage_drop_keysrrrrrr(r z MiniMax H3rrrzCMiniMax frontier. Native 2K (up to 4K), 5-15s, seven aspect ratios.rrzminimax/h3/text-to-videorzminimax/h3/image-to-video duration_intr1rr)768P2K4Kresolution_aliasesr3r4r5)r&rr768pr2kr*2160pr)rrrr(zFLUX 3 (via FAL)zGBlack Forest Labs frontier video. Native audio, 5-20s, 8 aspect ratios.z$blackforestlabs/flux-3/text-to-videoz%blackforestlabs/flux-3/image-to-video)r z2:1r!r"r#r$r%)rr)r:)r rrrrrrr2rrrrrr(zGrok Imagine 1.5 (via FAL)z=xAI. Fast stylized video with audio, 1-15s, cheap per second.z)xai/grok-imagine-video/v1.5/text-to-videoz*xai/grok-imagine-video/v1.5/image-to-video)r!r"z3:2r#z2:3r$r%)r rrrrrrr2r1rrrrrr(zGemini Omni Flash (via FAL)zBGoogle. Image-to-video with audio, physics-grounded motion, 3-10s.z'google/gemini-omni-flash/image-to-video) z Kling v3 4Kz ~120-300sz14K output, native audio (Chinese/English), 3-15s.z&fal-ai/kling-video/v3/4k/text-to-videoz'fal-ai/kling-video/v3/4k/image-to-videostart_image_urlr!r%r#)r<r) r rrrrrrimage_param_keyrrrrrzHappy Horse 1.0uAAlibaba. New model, sparse public docs — conservative defaults.z!alibaba/happy-horse/text-to-videoz"alibaba/happy-horse/image-to-video) zltx-2.3 pixverse-v6zseedance-2.0-minizveo3.1z seedance-2.0z seedance-2.5z minimax-h3zflux-3zgrok-imagine-1.5zgemini-omni-flashz kling-v3-4kz happy-horsezDict[str, Dict[str, Any]] FAL_FAMILIESrArreturnboolct|trt|dkrdStd|DsdS|d|dz dkS)zIHeuristic: a 2-tuple of ints with a gap > 1 is treated as ``(min, max)``.Fc3@K|]}t|tVdSN) isinstanceint).0ds B/home/agent/.hermes/hermes-agent/plugins/video_gen/fal/__init__.py z%_is_duration_range..-s,55az!S!!555555rr)rItuplelenall)rs rM_is_duration_rangerS)se i ' '3y>>Q+>+>u 559555 5 5u Q<)A, & **rOfamilyDict[str, Any]duration Optional[int]c|d}|sSt|rdn|dSt|r#|\}}t|t|S|vrSt|fdS)Nrrc(t|z SrH)abs)rLrVs rMz!_clamp_duration..BsAL(9(9rO)key)getrSmaxmin)rTrVrlohis ` rM_clamp_durationrb2s ;''I  *)44Ftt)A,F)$$*B2s2x(()))9 y9999 : : ::rOc ddlm}|}t|tr|dnd}t|tr|niS#t $r'}t d|icYd}~Sd}~wwxYw)Nr) load_config video_genz#Could not load video_gen config: %s)hermes_cli.configrdrIdictr] Exceptionloggerdebug)rdcfgsectionexcs rM_load_video_gen_sectionrnJs111111kmm*4S$*?*?I#''+&&&T$Wd33;ww;  :C@@@ sAA B!B=BBz text-to-videozimage-to-videocstr Optional[str]c|}|sdS|tvr|StD]5\}}||d|dfvr|cS6g}tD]\}}|d|dfD]}t |t s||dzs1|t|dzdddd}|tvr&| t||fn|r&| dd |ddSt|d}d}d }tD]*}||vr$t||kr|}t|}+|S) a6Try to extract a known family ID from a model string. Handles bare IDs (``seedance-2.5``), full endpoint paths (``bytedance/seedance-2.5/text-to-video``), truncated endpoint stems (``minimax/h3``, ``bytedance/seedance-2.0/mini``), and provider-prefixed names (``bytedance/seedance-2.5``). Nrr/rrc|dS)Nr)items rMr[z'_normalize_family_key..}s QrOT)r\reverse) striprBitemsr]rIrp startswithrQsplit_ENDPOINT_MODALITY_LEAVESappendsortset) rofidmeta stem_hitsendpointfirstpartsbest_fidbest_lens rM_normalize_family_keyrYs  A tL"'')) T /**DHH5E,F,FG G GJJJ H(*I!''))   T/22DHH=M4N4NO  Hh,, &&q3w// SVVaZ[[)//Q77:E111  #a&&#///2//>>>|A   E"HH   %<Decide which FAL family to use. Returns ``(family_id, meta)``.FAL_VIDEO_MODELfalmodel) r~osenvironr]rnrIrgrpryrrB DEFAULT_MODEL)r candidatesrkfal_cfgtoprors rM_resolve_familyrsJ&(Jhbjnn%677888 ! # #C *3775>>4 @ @HcggennnbG'4  0'++g../// '''  C#s# .. a   .!'')) .'**C .L----- ,}5 55rOprompt image_urlr/ resolutionnegative_promptOptional[bool]cNi} |r|| d<|r|dpd} || | <||ddr|| d<|dr||dvr|| d<|d rP|d pi} | |pd |} | |d vr| | d <t||} | O|d r:|dr| | d<n|dd }| || d<|dr|t|| d<|dr|r|| d<|r/|ddD]} | | d| S)zJBuild a family-specific payload, dropping keys the family doesn't declare.rr@rNr(Trr/rr6rrr2rVr.rgenerate_audiorrr1ru)r]lowerrbrDpop)rTrrrVr/rrrr(payloadr\aliasesresolvedclampedsuffixs rM_build_payloadrs !G #"!jj*++:{   FJJvt44 zz/""3 6/2 2 2&2GN #zz-  -**1228b;; 0b7799:FF vm, , ,$,GL !fh//Gvzz+66 ::n % % 7")GJ  ZZ 1266F%,"6f"6"6GJ  zz'0u0$(KK ! zz*5/5%4!"#::/44 # #C KKT " " " " NrO _fal_clientcttSt5ttcdddSddlm}|atcdddS#1swxYwYdS)aoLazy-load the ``fal_client`` SDK and cache it on this module. Delegates the actual import to :func:`tools.fal_common.import_fal_client` so the ``lazy_deps`` ensure-install handling stays in one place. Thread-safe via double-checked locking: concurrent first calls import the SDK exactly once instead of each racing thread re-running the import. Nrimport_fal_client)r_fal_client_locktools.fal_commonrrs rM_load_fal_clientrs   " 766666''))  sAAAA_managed_fal_video_client _managed_fal_video_client_configcddlm}ddlm}m}m}m}|d}||kr)|d}|t|d|d|S|&|st|d|ddS|rdS|dS) uResolve the FAL video route from the stored selection. Plain switch on the stored ``video_gen`` provider string — mirrors the image FAL resolver: ``"nous"`` (or legacy ``use_gateway: true``) → managed only (unentitled ⇒ selection-naming error); any other stored provider → direct only (missing FAL_KEY ⇒ selection-naming error); never-configured category → legacy credential autodetect. rresolve_managed_tool_gateway)NOUS_MANAGED_PROVIDERfal_key_is_configuredread_selectionselection_errorre fal-queueNzDthe Nous Tool Gateway is not available (not entitled or unreachable)zFAL_KEY is not set)tools.managed_tool_gatewayrtools.tool_backend_helpersrrrr ValueError)rrrrrselectedgateways rM"_resolve_managed_fal_video_gatewayrs%HGGGGG~k**H(((..{;; ?__%  $$&& __$  tt ' ' 4 44rOcDddlm}|jd|jf}t 5t t|krt cdddSt|t|j|ja|at cdddS#1swxYwYdS)zQReuse the managed FAL client so its internal httpx.Client is not leaked per call.r)_ManagedFalSyncClientrsN)r\queue_run_origin) rrgateway_originrstripnous_user_token_managed_fal_video_client_lockrrrr)managed_gatewayr client_configs rM_get_managed_fal_video_clientr>s"766666 &--c22'M ( ) ) $ 05UYf5f5f, ) ) ) ) ) ) ) ) $9$9 /,;% % % ! ,9(( ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) )sB3BBBr argumentsctdttji}t }|t |||St|} ||||S#t$r@}ddl m }||}|'d|cxkrdkrnntd|d |d |d}~wwxYw) zSubmit a FAL video request using direct credentials or the managed queue gateway. Returns a request handle whose ``.get()`` blocks until the result is ready. zx-idempotency-keyN)rheadersr)_extract_http_statusiiz-Nous Subscription gateway rejected endpoint 'z' (HTTP u). This model may not yet be enabled on the Nous Portal's FAL proxy. Either: • Set FAL_KEY in your environment to use FAL.ai directly, or • Pick a different model via `hermes tools` → Video Generation.) rrpuuiduuid4rrsubmitrrhrrr)rrrequest_headersrmanaged_clientrmrstatuss rM_submit_fal_video_requestrUs; *C ,=,=>O8::O!!(i!YYY2?CCN$$ #%      999999%%c**  #"5"5"5"5#"5"5"5"5"5YYYYYY     s.B C;C  Ccddlm}ddlm}m}m}|d}||kr |dduS| |S|rdS|dduS)u:True if the FAL video backend selected via `hermes tools` (or, on a never-configured install, any FAL backend) is reachable. Never raises — a stored-but-broken selection reports False here; the honest selection-naming error surfaces at call time from ``_resolve_managed_fal_video_gateway``. rr)rrrrerNT)rrrrrr)rrrrrs rM_check_fal_video_availablervsHGGGGG ~k**H(((++K88DD$$&&&t ' ' 4 4D @@rOzfal-ai/seedvr/upscale/videorF video_urlsource_request_idc tdt|dtd}t|st d||d<t t |}|}n3#t$r&}t d|Yd}~dSd}~wwxYwt|tr|pidnd}t|tr|d r|d St|tr|r|St d dS) u Upscale a generated video via SeedVR2; return the new URL or None. Best-effort: any failure logs and returns ``None`` so the caller falls back to the native-resolution video — an upscale failure must never destroy an already-successful generation. z%Upscaling video with SeedVR2 (%dx)...factor)r upscale_modeupscale_factorNz9Managed SeedVR upscale requires the source FAL request idrzVideo upscale failed: %svideourlzVideo upscaler returned no URL) riinfoUPSCALER_FACTORr RuntimeErrorrUPSCALER_ENDPOINTr]rhwarningrIrgrp)rrrhandleresultrmrs rM_upscale_videorsT ;_MMM"$-% % . / / ;$ `"#^___->I) **+.s/ T Tq T T T T T T TrO0)rrrmodalityr/rVrextra)rrrrrr rpr ImportErrorryrr]rrgetattrrhrirrIrgrrr rJjoin)rrrrrrVr/rrrr(rrrrm family_idrTimage_url_normr modality_usedrrrrrrr upscaled_urlr%s rMgeneratezFALVideoGenProvider.generatesI *++  A A A A A A~k**668888!)!#hh#2!&% "V+             !X/     ,B%%''+E22 6$/r0022:d  zz"233H#M %DiDDD 6")F zz/22H"M %PiPPP 6")F !++i  ! $%!+     .xAAF ' d C C ZZ\\FF    NNC8S4    ";c;;&i)        0:&$/G/GQ2""7+++T! eT " " ))E""CC s # # C !=+i   )#/@AAL "U.68 L L  6&5E" # eT " " >yy%% 8h 8%*;%7k"yy(( >(-n(=n%")77)B)B`jnu`u`uS T TC 0C,D,D T T TTT[X[\\\{|    sJ0 A$AA$A$;B B*)B*5F77 H6G=7H=H)rCrprCrD)rCr)rCrqrCrU)rrprrqrrqrrrVrWr/rprrprrqrrr(rWrrrrrCrU) __name__ __module__ __qualname____doc__propertyrrrrrrr r-rurOrMrrs XX 6         < $#'48"&" )- $""&e e e e e e e e rOrNonecH|tdS)uFPlugin entry point — wire ``FALVideoGenProvider`` into the registry.N)register_video_gen_providerr)ctxs rMregisterr9s###$7$9$9:::::rO)rrrCrD)rTrUrVrWrCrWr/)rorprCrq)rrqrCr)rTrUrrprrqrVrWr/rprrprrqrrr(rWrCrU)rCr)rrprrUr.rH)rrprrqrCrq)rCr5)/r3 __future__rloggingr threadingrtypingrrrrragent.video_gen_providerr r r getLoggerr0rirB__annotations__rrSrbrn frozensetr}rrrrLockrrrrrrrrrrrrrr9rurOrMrCs'''R#"""""  33333333333333  8 $ $6#J;="!E;=8  'XDFF'"Y(8). "R?AG0!&"l?A-F'#&<  Z    3  5  , F" +#$ FFFTD  %, W-. /0 E12 38&^?AM($0TDF,L0!&1YC)$!HAC-0$%X<>IT+T+ TTTTl ++++;;;;0    &I8H&IJJ1111h66668CCCCT !9>##0"&%%%%(, ,,,,!/!1!1'5'5'5T))).BAAAA@2 (,!!!!!R@ @ @ @ @ *@ @ @ P;;;;;;rO