Pmj .dZddlmZddlZddlZddlZddlZddlZddlm Z ddl m Z ddl m Z mZmZmZmZejeZdZdZdZd Zd Zejd Zejd Zd ZddZddZddZ dddZ!ddddZ"d Z#d!Z$dZ%d"Z&d#Z'd$Z(d%Z)e*hd&Z+dd(Z,dd)Z-dd*Z.dd-Z/dd/Z0dd4Z1dd5Z2dd8Z3d9Z4d:Z5d"Z6d;Z7dZ9dd?Z:dd@Z;ddAZdDZ?ddFZ@dGZAddIZBddKZCddLZDddMZEddNZFddOZGddPZHddRZIddSZJddTZKddUZLddVZMddWZNgdXZOdYgZPdZZQd[ZRd\ZSdd]ZTd^eQd_zeSzd`eTdagdbdcddZUdeeQdfzeRzdgzeSzd`ieTdhdidjdkdlidadhgdbdcddZVdmeQdnzeRzdgzeSzd`ieTdodidjdpdjd dqdrdodsddtdudjd dvdrdwgdxdbdcddZWdyeQdzzeRzdgzeSzd`ieTd{didjd|dlidad{gdbdcddZXd}d~d`didjddldiddddgdbdcddZYddd`idbdddZZdZ[e j\d^eeUeEeNgdde j\deeeVeFeNgdde j\dmeeWeGeNgdde j\dyeeXeHeNgdde j\d}eeYeKeNgdde j\deeZeLeNgdddS)uNative BFL FLUX 3 video generation tools, backed by the Nous tool gateway. These are native tools in the ``image_generate`` mold: schemas and descriptions are pinned here as build-time facts, the handlers speak the gateway's own REST contract, and ``check_fn`` hides the whole toolset only when there is no Nous sign-in to call it with — never on entitlement, which is the gateway's to rule on. No runtime discovery, and no server-supplied schema is ever consulted — that is the point of the design. The wire is two calls against the gateway's managed mount, and it names the vendor but not the vendor's API: - ``POST {base}/generations`` with ``{mode, prompt, ...}`` -> ``{id, status, guidance}`` - ``GET {base}/generations/`` -> the job state plus ``guidance`` ``guidance`` is the gateway's live policy channel: exact waits, what to do next, and how to deliver a finished clip ship from the server so they cannot drift from what it actually enforces. Handlers surface it verbatim as the tool's result text, and surface ``error.message`` the same way on a refusal. Media inputs: handlers know their own media fields explicitly. A local file path is resolved through :func:`tools.image_source.resolve_image_source` (sandbox confinement, credential guard) and delivered via the Nous upload protocol (presign, direct PUT to storage, ``nous-upload:`` reference). URLs pass through untouched. ) annotationsN)Optional)registry)build_managed_media_uploadermanaged_gateway_auth_headersmanaged_vendor_endpointspeek_nous_access_tokenread_nous_access_tokenbflgf@g$@zuBFL video generation needs a Nous Portal sign-in. Ask the user to run `hermes model` and sign in to Nous, then retry.z^[A-Za-z]:[\\/]z!^[A-Za-z0-9+/\r\n]+={0,2}[\r\n]*$valuestrreturnboolcft|tkrt|rdS|drdS|dks|drdS|drdSt |s|drdSdS)u@True for things we should read off disk rather than forward as-is. Deliberately narrow: only explicitly rooted paths and ``file://`` qualify. Bare names are ambiguous with opaque ids, URLs pass through, and base64 payloads (checked first — a JPEG's base64 starts ``/9j/``) fall through untouched. Fzfile://T~)z~/z~\)/z./z../z.\z..\z\\)len_MIN_BASE64_PAYLOAD_LENGTH_BASE64_PAYLOADmatch startswith_WINDOWS_DRIVE_PATH)r s r1r0clientresponseexcpayloadr,r6outr;s r _call_gatewayrSss&LLL*3//G 7z7$456660GNmm*0<0D , ,,G $$W$55 Z Z Z Z Z Z Z#^^FCy^YYYYYYYYH Z Z Z Z Z Z Z Z Z Z Z Z Z Z Z Z Z Z Z Z Z Z Z Z Z Z Z    zad3iiFXaa\_aa#           s""z$4dKKLLL--//  gt $ $ zr8CWrrr#     s""(27;;w3G3G(N(NV G$$$TV))I&&j*jS[Sg*j*j*jc'll+ eii **D 1 1 ."9-C Nz#E2222{{:t,,H :22wGG   sTB>: B,B>, B66B>9B6:B>> D.C<6D<D,E EE)image)video) input_image input_images input_video gn@g@g?gN@>Task not foundContent ModeratedRequest ModeratedErrorReadyrawcF tj|}n#t$rYdSwxYwt|trd|vrdS|d}t|tr|dnd}t|t  p|tvS)zETrue when there is nothing to wait for: done, refused, or unreadable.Tr,r8statusN)r2loadsrFrJrKrLr_TERMINAL_POLL_STATUSES)r`rQr8rbs r_poll_is_finishedres*S// tt gt $ $7(:(: tkk)$$G&0$&?&? IW[[ " " "TF&#&& & K&4K*KK  %%c tj|}n#t$rYdSwxYwt|trd|vrdS|d}t|tr|dnd}t|t s"t|ttfr|dkrdSt|S)uHow long the gateway asked us to wait, when a refusal is a throttle. A throttle is the one refusal worth absorbing here rather than handing back. Returning it ends the call, and the model it lands on has no clock — told to wait, it asks again immediately — so a rate limit answered that way produces a tighter loop than the one that tripped it. The gateway sends the wait as a number alongside the message, so there is nothing to parse out of prose. Nr,r8retryAfterSecondsr) r2rcrFrJrKrLrintfloat)r`rQr8r s r_retry_after_secondsrks*S// tt gt $ $w(>(>tkk)$$G0:7D0I0I SGKK+ , , ,tE%je &E&ERSt <<rfc tj|}n#t$rYdSwxYwt|to|dduS)zTrue when the gateway did not answer, as opposed to answering "no". Set by ``_call_gateway`` on the paths where nothing readable came back, so this reads a flag rather than matching on the text of a message. Fr4T)r2rcrFrJrKrL)r`rQs r_is_transport_errorrm%s_ *S// uu gt $ $ O5F)G)G4)OOrfsecondsrjcKddlm}|}|dkrF|rdStt|}t j|d{V||z}|dkFdS)zFHold the call open until the next look; False if the user interrupted.r)is_interruptedFNT)tools.interruptrpmin_POLL_WAIT_SLICE_SECONDSasynciosleep)rnrp remaining this_slices r_wait_between_looksrx2s......I a-- >   519== mJ'''''''''Z a-- 4rNonec tdS#t$r&}td|Yd}~dSd}~wwxYw)aERefresh the Nous token once, before any parallel upload needs it. ``read_nous_access_token`` takes no lock and, when a refresh fails, falls back to returning the stale cached token. Uploading in parallel therefore had every request discover the token was expiring at the same instant and fire its own refresh; the rotating refresh token means the first wins and the rest quietly send the stale bearer, which the gateway answers with 401. One warm-up call first puts a fresh token in the cache, so the fan-out all reads it instead of racing for it. z5Nous token warm-up failed before parallel uploads: %sN)r rFloggerdebug)rPs r_warm_nous_tokenr}@sdS     SSS LcRRRRRRRRRSs A=AargsrKtask_id Optional[str]c Kt|pi}ttD]\}||}|t |t rtt|tkr*t|dtdt|dt tj fd|Dd{V||<t|d{V||<|S)uReplace local paths with upload references in every media field. Deliberately covers all media fields rather than the one this mode expects. The gateway accepts `input_image` and `input_images` interchangeably, so a value left unsanitized in the "wrong" field still reaches the vendor — as a raw local path, which both fails the generation and discloses the user's directory layout to a third party. Nz takes at most z images; you passed .c3:K|]}t|VdSN)_deliver_media).0entry permittedrs r z!_prepare_media..gs0&d&dUZ~eY'P'P&d&d&d&d&d&dr) rKr} _MEDIA_FIELDSitemsrLrJlistr _MAX_IMAGES ValueErrorrtgatherr)r~rpreparedfieldr rs ` @r_prepare_mediarQs3DJBH)//11NNy U## =  eT " " N5zzK'' E!h!h+!h!h[^_d[e[e!h!h!hiii#n&d&d&d&d&d^c&d&d&deeeeeeeHUOO%35)W$M$MMMMMMMHUOO Orc\dt|piDS)uDrop media fields entirely — for the mode that takes none. The gateway ignores them for text-to-video, so stripping here matches its behaviour while avoiding an upload the caller never needed. c,i|]\}}|tv||Sr$)rrkvs r z"_without_media..ts( P P PTQ-9O9OAq9O9O9OrrKr)r~s r_without_mediarns1 Q PT$*"--3355 P P PPrrtuplec(Kt|trt|s|Sddlm}m}m} |||||d{V}n0#|$r(}tdt|d||d}~wwxYwt}d} |t|d|d } | td  | |j |j d{VS#t$r(}td t|d||d}~wwxYw) uReplace a local path with a ``nous-upload:`` reference; pass URLs through. Raises ``ValueError`` with a model-readable sentence when the file cannot be read or uploaded — the caller turns that into the tool's error payload. r)ImageResolutionErrorResolveContextresolve_image_source)r)rNzCould not read r3base_url upload_pathzGLocal file uploads are not available in this build; pass a URL instead.zCould not upload )rJrrtools.image_sourcerrrrr r%rdatamimerF) r rrrrrresolvedrP endpointsuploaders rrrws eS ! !)?)F)F ]]]]]]]]]]S--e^^G5T5T5T`ijjjjjjjjj SSSH=+?+?HH3HHIIsRS IH/ *0EyQ^G_``bcccUXhmX];;;;;;;;; UUUJ]5-A-AJJSJJKKQTTUs/AB#A;;BC D)#D  Dgr@g.@i2startedcttj|z z tz }t dt t |S)aeWhat is left of the call for a download, never more than the ceiling. Without this the download's own generous timeout outlives the agent's per-tool ceiling, and the "saving failed, poll again to retry" answer below is never reached: the bridge kills the call first and the model is told only "TimeoutError", with no indication the clip exists and is one poll away. Must not invent time past what remains: clamping upward used to schedule a download the outer ``asyncio.wait_for`` then cancelled, answering with a false ``_still_generating`` while the job was already Ready. )_CALL_BACKSTOP_SECONDStime monotonic_DOWNLOAD_GRACE_SECONDSmaxrr_DOWNLOAD_READ_TIMEOUT_SECONDS)rlefts r_download_read_timeoutrs< "T^%5%5%? @CZ ZD sC6== > >>rcK tj|}n#t$r|cYSwxYwt|ts|S|d}t|tr|ddkr|S|d}t|tr|dnd}t|t r|s|S|dd t|||d{V\}}nK#t$r>} dt| j d| d |d<tj |d cYd} ~ Sd} ~ wwxYwt ||d <||d <t|t |dpdz|d<tj |d S)ujDownload a finished clip and swap the signed URL for a local path. The URL is handled here rather than by the model on purpose. It is long and percent-encoded, and re-keying it into a shell command dropped characters often enough to be the main failure mode of this tool — a corrupted signature is rejected, but `curl` still writes the rejection body to the output file and exits 0, so it read as success. Passing the exact string from this response removes the transcription step entirely. It also keeps a bearer credential out of the transcript: the signed URL grants the clip to anyone holding it for the next 15-60 minutes, and returning it put it in the model's context and the saved conversation. The gateway already scrubs presigned URLs for *input* media for exactly this reason; this makes the output side match. r8rbr_r=sampleNz(The clip finished but saving it failed: r3zJ. Poll this job again to retry the download; the job itself is unaffected.Fr9 saved_path saved_bytes)r2rcrFrJrKrLrstriprM_download_videorGrHr?_delivery_lead_in) r`save_torrQr8r=r'targetsizerPs r_save_if_readyrs *S//   gt $ $ kk)$$G gt $ $ H(=(=(H(H [[ " "F",VT":": D&**X   C c3  syy{{  JJx7,SYY[['7KKKKKKKK  777 WtCyy7I W WS W W W z'666666666 7 KKGL!GM)&11C H8M8M8SQS4T4TTGH :gE 2 2 22s* (( ,D77 E?3E:4E?:E?c<tr d|d|dSd|dS)uOpens the result text, ahead of the gateway's own delivery guidance. On a messaging platform the tag is spelled out rather than described. The model has to reproduce this path exactly or the file is not sent, and the reply is published either way — the tag is stripped from the text whether or not it named a real file, so a wrong path reads to the user as a message that simply forgot the attachment. Handing over the finished line removes the step where that goes wrong; only this side knows the path. z Saved to z. To deliver it, copy the next line into your reply exactly as written, alone on its own line, with nothing added around it: MEDIA: z. )_delivers_as_an_attachment)rs rrrsM"##        "v ! ! !!rcKddl}ddlm}t|t |}||jdz}|tt|} ||d4d{V}| d|4d{V} | | d 5} | 23d{V} | | 6 dddn #1swxYwYdddd{Vn#1d{VswxYwYdddd{Vn#1d{VswxYwY|j} | t"krt%d | d ||n%#t($r|d wxYw|| fS) aStream the clip to disk, returning (path, bytes). SSRF-guarded, for the same reason the upload PUT is: this URL comes from the vendor by way of the gateway, and it is fetched from the user's own machine. Real result URLs are public CDN objects, which the guard allows. rN)create_ssrf_safe_async_clientz.partr-T)r0follow_redirectsGETwbzthe download returned only z bytes, which is not a video) missing_ok)r>tools.url_safetyr_resolve_destination_filename_from_url with_namenamerA!_DOWNLOAD_CONNECT_TIMEOUT_SECONDSrstreamraise_for_statusopen aiter_byteswritestatst_size_MIN_PLAUSIBLE_VIDEO_BYTESrreplace BaseExceptionunlink) r'rrr>rrpartialr0rNrOhandlechunkrs rrrsRLLL>>>>>> !'+=c+B+B C CFv{W455Gmm=DZ[bDcDcmddG00SWXXX , , , , , , ,\b}}UC00 , , , , , , ,H))+++\\$'',6'/';';'='=,,,,,,,e U++++(>'=,,,,,,,,,,,,,,, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,||~~% , , ,]4]]]^^ ^ $'''  4<s1F)E !*D( D  C=&D ? D( D D(D D(E ( D2 2E 5D2 6E 9F) EF)EAF))"G cddlm}ddlm}m}||||jj}tjdd| ddd}|pdS) Nr) PurePosixPath)unquoteurlsplitz[^A-Za-z0-9._-]_rxzflux3-video.mp4) pathlibr urllib.parserrrrresublstrip)r'rrrrs rrr$s%%%%%%........ =#!344 5 5 :D 6$c4 0 0 7 7 < .-@@ @ b b b LLQ\`L a a a a a b k)I!((** :99 :s(&AAfilenamecddlm}t|tr|r~||}|s'|dr||}}n|j |j }}nt|}}| ddt||z S)zDWhere to write, honouring an explicit request and never overwriting.rr)r\T)parentsexist_ok)rrrJrr expanduserrrstripendswithparentrrmkdir _free_path)rrr requested directoryrs rrrWs'39GMMOO9D))4466      ?!1!1!:!:;!G!G ?'tII'. tII,..4  OOD4O000 i$& ' ''rc|s|StdtdzD]@}||jd||j}|s|cSAt d|)uG`name.mp4` -> `name-2.mp4` -> `name-3.mp4` … so nothing is clobbered.-z'could not find a free filename next to )existsrange_MAX_FILENAME_ATTEMPTSrstemsuffixr) candidater siblings rrrhs     1A566%%&T&T&&T)BR&T&TUU~~ NNN  JyJJ K KKrr6c2tjd|idS)Nr,Fr9r2r?)r6s r_errorrws :w(u = = ==rmodecjdt|piD}||d<|S)zThe wire body: the model's arguments, minus Nones, plus our mode. Arguments pass through as the model gave them; the gateway owns validation and the translation onto the vendor's own fields. ci|] \}}||| Srr$rs rrz _submit_args..s G G GTQAqrrr)rr~bodys r _submit_argsr{s> H GT$*"--3355 G G GDDL KrcKt}|tdStd|ddt||d{VS)N4BFL video generation is not available in this build.POSTrz /generations)r%rrSr)rr~rs r_submitrsb ILMMMv)J*?'M'M'M|\`bfOgOghh h h h h h hhrcLKtdt|d{VS)N text_to_video)rrr~kwargss r_handle_text_to_videor s0.*>*>?? ? ? ? ? ? ??rcK t||dd{V}n3#t$r&}tt |cYd}~Sd}~wwxYwt d|d{VS)Nrimage_to_videorrLrrrrr~rrrPs r_handle_image_to_videor%s 'fjj.C.CDDDDDDDD    c#hh )844 4 4 4 4 4 44). AAAAchK|pid}t|tr|stdS t ||dd{V}n3#t $r&}tt |cYd}~Sd}~wwxYwtd|d{VS)NrWzKinput_images must be a non-empty list of 1-10 images (local paths or URLs).rkeyframes_to_video)rLrJrrrrrr)r~rimagesrrPs r_handle_keyframes_to_videor*sjb  n - -F fd # #e6ecddd 'fjj.C.CDDDDDDDD    c#hh -x88 8 8 8 8 8 88s)A++ B5BBBcK t||dd{V}n3#t$r&}tt |cYd}~Sd}~wwxYwt d|d{VS)Nrvideo_continuationr#r$s r_handle_video_continuationr-s 'fjj.C.CDDDDDDDD    c#hh -x88 8 8 8 8 8 88r&job_idcBtjd|d|ddddS)zHThe backstop's answer: an ordinary "call again", never a raised timeout.uStill generating. This call reached its own time limit, which the job is unaffected by — call bfl_flux3_get_result again with id=z to keep waiting. Generating)idrbr<Fr9r)r.s r_still_generatingr2sN :MS% ==       rcKd}d} tj}td|td{V}|tj|z z }t |r|dz }|t kr|St }nWd}t|}|&t|rt|||d{VS|t nt|t }|dks||ztkr|St|d{Vs|S||z })aLook until the job settles, the budget runs out, or the user stops. The waiting is absorbed here rather than asked of the model. A model has no clock: told to wait it emits "I'll check back in a minute" and its next action lands immediately, so guidance produced a burst of polls rather than a paced one. Waiting inside the call cannot be skipped, needs no shell, and works the same on every platform. rrTr)r)N) rrrS_POLL_READ_TIMEOUT_SECONDSrm!_MAX_CONSECUTIVE_TRANSPORT_ERRORS_POLL_GAP_SECONDSrkrerr_POLL_BUDGET_SECONDSrx) r'rrspent unanswered look_startedr`gap throttled_fors r_poll_until_doner>sS EJ~'' !%;UVVVVVVVVV !!L00 s # # h !OJ>>> #CCJ055M$):3)?)?$+C'BBBBBBBBB(5'<###mUfBgBgC !88us{&:::J(-------- J  =rcDK|pid}t|tr|st dSt }|t dSddlm}|}|dd||d }|pid }tj } tj t|||t d{VS#tj$rt|cYSwxYw) Nr1z9id is required: the job id returned by the generate tool.rr)quoterz /generations/r)saferr/)rLrJrrrr%rr@rrrtwait_forr>r TimeoutErrorr2)r~rr.rr@r'rrs r_handle_get_resultrDsZjb  d # #F fc " "S&,,..SQRRR ILMMM"""""" \\^^F z " I IvB1G1G1G I ICzry))GnG)% S'7 3 3=S            ))) ((((()s/C>>DDcKtSr)FLUX3_PROMPTING_GUIDErs r_handle_prompting_guiderGs  rctrdS ddlm}|dpi}n#t$rYdSwxYw|d}t |t o t|S)uTrue when a Nous bearer is on hand, without spending a refresh to learn it. Two lookups, because the transport itself has two. ``peek_nous_access_token`` covers the env override and the active store's cached token. A profile that was never logged into separately has neither, and reads the credential from the global-root ``auth.json`` — the same fallback ``resolve_nous_access_token`` takes when the transport refreshes. Probing only the first would hide the tools from a profile whose calls would have gone through perfectly well. Neither lookup validates or refreshes the token: an expired credential is the gateway's 401 to report, and that answer already asks for a sign-in. Tr)get_provider_auth_statenousF access_token) r hermes_cli.authrIrFrLrJrrr)rIstatetokens r_has_nous_credentialrO st;;;;;;''//52 uu IIn % %E eS ! ! 9d5;;==&9&99s & 44cb tdStS#t$rYdSwxYw)uVisible to anyone signed in to Nous; the gateway rules on the rest. No entitlement check. What an account may generate — plan, credits, per account limits — is the gateway's decision, and it refuses with a reason written for the model to act on; deciding it a second time here can only disagree with the server and hide the tools from someone entitled to them. A sign-in is still required, because the gateway takes a Nous bearer and nothing else: with no credential every call could only ever answer "sign in", so the six schemas would be pure cost on every API call. Stays a pair of file reads — no portal probe, no OAuth refresh. Behind the registry's 30s cache this still runs on every CLI start, gateway session and cron tick. NF)r%rOrFr$rrcheck_bfl_requirementsrQ$sD  << 5#%%% uus ..)autoz21:9z16:9z4:3z1:1z3:4z9:16z9:21720pz=Read bfl_flux3_prompting_guide before your first generation. zMedia fields accept a local file path (uploaded automatically to Nous-managed temporary storage and deleted when the generation finishes) or a URL. zAAll guidance is defaults: explicit user instructions override it.c dddddttddddd d d ddd gdd ddttddddddddddddddddddddS)Nstringr4uGeneration brief in plain prose (it is interpreted and expanded by a reasoning harness). Order it subject, distinguishing visual specifics, action, camera, lighting, environment, audio, style. Audio is generated by default — say "no music" if unwanted.rG minLength descriptionrRz2Output aspect ratio. "auto" lets the model choose.)rGenumdefaultrXintegerrGminimummaximum)rGconstz1Clip duration in whole seconds (5-20), or "auto".)oneOfrZrXrSzOutput resolution bin.booleanTzGenerate synchronized audio.)rGrZrXz.Allow a short research pass before generation.rlzOptional reproducibility seed.)rGr_r`rXz(Model version pin. Defaults to "latest".rGrX)prompt aspect_ratioduration resolutiongenerate_audio groundingseedversion)r_ASPECT_RATIOS _RESOLUTIONSr$rr_shared_submit_propertiesroKs*   ((O   #qR@@!F33N   &&3   9  K  !;   E  _3 3 3rbfl_flux3_text_to_videou^FLUX 3 text-to-video: generates a clip (with audio) from the prompt alone. Nothing but the prompt anchors the subject here, so research anything with a real, checkable appearance before writing it — whatever you leave unspecified is filled in for you. Generation takes several minutes: this returns a job id immediately; poll bfl_flux3_get_result. objectreF)rG propertiesrequiredadditionalProperties)rrX parametersbfl_flux3_image_to_videouFLUX 3 image-to-video: animates one image as the literal opening frame — those pixels are frame 0 and the clip moves from there. z-Returns a job id; poll bfl_flux3_get_result. rVrUr4zXExactly one opening-frame image: a local file path or a URL (PNG/JPEG/WebP, up to 10MB).rVbfl_flux3_keyframes_to_videozFLUX 3 keyframe video: a storyboard of 1-10 images pinned at chosen frame positions (24fps). Name the subject and describe the motion that carries it between the pins, and keep the subject consistent across every pinned image. array)rGrWzP1-10 keyframe images: local file paths or URLs (PNG/JPEG/WebP, up to 10MB each).)rGrminItemsmaxItemsrXr[ir^uOne unique non-negative frame index per image (24fps). Each must be at most duration×24, so set an explicit duration rather than "auto" whenever you pin indices — "auto" resolves to 5, 10, 15 or 20 seconds and an index past the length it picks is rejected.)rWkeyframe_indices)rerWr{bfl_flux3_video_continuationuFLUX 3 video continuation: the new generation picks up from the input clip's final frames. Open the prompt with "Continue this video from its final frames:", re-establish the subject and the moment it ended on, then describe what happens next. input_video must be an mp4 of at most 50MB and 15 seconds, and the generated segment tops out at 15s too — chain a second continuation for a longer sequence. duration is the new segment only. rXzXThe clip to continue: a local file path or a URL. mp4 only, at most 50MB and 15 seconds.bfl_flux3_get_resultaPoll a FLUX 3 video job by the job id a generate tool returned. Generation takes minutes and a long Generating phase is normal. This call waits for you while the job runs, so it may run for several minutes; if it returns still generating, just call it again. Do not sleep between calls. On Ready the clip is downloaded for you and the response gives its local path; your only remaining step is to deliver that file as the response describes.z1Job id from a previous bfl_flux3_* generate call.zWhere to save the finished clip: a directory or a full file path. Set this only when the user asked for a particular location; the default is ~/Downloads. An existing file is never overwritten.rd)r1rr1bfl_flux3_prompting_guideaRead this before your first FLUX 3 generation. The prompting and grounding guide: how to research a subject so it renders as itself, how to assemble a prompt, which generate tool fits, and how to save and deliver the finished clip. Takes no arguments and spends no generation budget.)rGrrrtuo# FLUX 3 video generation — how to get the best results Everything here is guidance, not policy: the user's explicit instructions always win. If they say skip the research, save somewhere specific, or deliver differently — do it their way without arguing. Only the server's own validation and limits are non-negotiable. Start from the user's own wording. The prompt is rewritten by a reasoning harness before anything is generated, so restyling it yourself just stacks a second rewrite on top and gives their intent another chance to drift. There are two reasons to add anything: grounding facts for a subject with a real, checkable appearance, and the behaviours below, which they had no way to know about. Absent those, send what they wrote. ## Grounding Grounding is your job, and it is the highest-leverage step in the workflow. What you specify is preserved; what you leave out is filled in for you. So when a subject has a real, checkable appearance, research it first and put what you found into the prompt — that is what makes the result yours rather than an approximation of it. Ground whenever someone who knows the subject could watch the clip and say "that's not what that is": a named person or place, a landmark, a particular vehicle or machine, anything technical, anything culturally specific, or a period setting. Skip it for generics ("a dog on a beach") — there is no fact to get wrong. To ground: search for VISUAL references, where three good photographs beat any amount of prose. If you can analyze images, analyze what you find. Then put only what a camera could see into the prompt: silhouette and proportion, materials and finish, specific colours, distinctive details, era-correct context. ## How this model behaves The prompt is read by a reasoning harness rather than a tag encoder, so keyword tricks and word order do nothing. Write plain prose at whatever length the brief deserves; a single line is a valid prompt. Audio is generated by default, whether or not you mention it, so leaving it out gets you invented sound rather than silence. Name the ambient sound, the music and any speech separately — each lands as its own layer — and say "no music" when you do not want it. A quoted line becomes speech only if a speaker is visible on camera. Without one it tends to render as burned-in text instead, so quote the line, describe the speaker, and add "no on-screen text, no subtitles". Multi-shot sequences work inside a single generation: "SHOT ONE ... HARD CUT. SHOT TWO ..." produces real cuts, and "one continuous unbroken shot" gets an uncut take. Consecutive shots have to contrast in scale, location or colour or the cut will not read as one — near-identical coverage blends back into a continuous take. ## Choosing a tool - No input media -> bfl_flux3_text_to_video. - Animate one image as the literal opening frame -> bfl_flux3_image_to_video (those pixels are frame 0, and the clip moves from there). Name the subject and its distinguishing specifics here as you would anywhere else: only frame 0 is pinned, every frame after it is generated, and what you leave out is the model's call rather than yours. - Several images pinned at chosen moments -> bfl_flux3_keyframes_to_video (name the subject and describe the motion that carries it between the pins; keep it consistent across every pin, since a mismatch becomes a visible morph mid-clip). Pin exact indices and you want an explicit duration too — every index must fall within duration×24. - Keep going from where a clip ends, or chain segments -> bfl_flux3_video_continuation. Open with "Continue this video from its final frames:", re-establish the subject and the moment the clip ended on, then describe what happens next; duration is the new segment only, so plan segments of 15 seconds or less to feed outputs back in. ## Media inputs Pass local file paths directly — never hand-encode file contents into an argument. URLs also work. Limits per file: images 10MB (PNG/JPEG/WebP), video one mp4 of at most 50MB and 15 seconds. Do not pre-shrink files to fit imagined caps; oversized pixel dimensions are auto-downscaled and output tops out at 720p. ## Workflow Submit returns a job id immediately — the video does not exist yet. Poll bfl_flux3_get_result with that id; generation takes several minutes and a long Generating phase is normal, not a stall. Nothing reaches disk before the job is Ready, so checking folders mid-run tells you nothing. The waiting is not yours to do. bfl_flux3_get_result takes the pause itself while a job is still running, so one call can occupy several minutes and comes back within seconds of the job finishing. If it returns still generating, just call it again — no sleeping, no interval to judge, nothing to time. A job survives client restarts: re-poll the same id rather than resubmitting, which would only spend your budgets on duplicate work. ## Save and deliver bfl_flux3_get_result saves the clip itself and returns saved_path. The download is not yours to do and no URL is handed to you to fetch. Pass save_to only when the user named a location; otherwise it lands in ~/Downloads, and an existing file is never overwritten. If saving fails the response says so — poll the same job again to retry, which is safe and spends no generation budget. Then deliver that file so the clip plays inline. Which markup plays inline is the host's decision, so check your system prompt or platform instructions and use exactly the form they give; the common ones are a MEDIA: tag alone on its own line and a markdown embed. Two things break it. Write the real absolute path, with ~ expanded. And keep the markup plain: wrapping it in bold, backticks or a code fence, or rewriting it as a [link](path), turns an inline player into literal text or a click-target. That is the most common way this step fails, and it reads as success because the filename is on screen. Where the instructions call for no delivery markup, or the host has no such mechanism, follow them and state the absolute path in plain text. Report what you did rather than what the job says it did: the echoed prompt field describes intent and often overstates what the render preserved. Tu🎬)rtoolsetschemahandlercheck_fn requires_envis_asyncemojiu📖)r rrr)rrrr)rr!)NN) r&rr'rr(r!r)r*rr)r`rrr)r`rrr*)rnrjrr)rry)r~rKrrrrK)r~rKrrK)rrrr)rrjrrj)r`rrrjrr)rr)r'rrrjrr)r'rrr)rr)rr)r6rrr)rrr~rKrrK)rrr~rKrr)r~rKrr)r.rrr)r'rrrjrr)rrK)]__doc__ __future__rrtr2loggingrrtypingrtools.registryrtools.managed_tool_gatewayrrrr r getLoggerrHr{_TOOLSETr#rCrBr@compilerrrrr r%rSrrrr8r7rsr5r6 frozensetrdrerkrmrxr}rrrrrrrr rrrrrrrrrrrrr r%r*r-r2r>rDrGrOrQrmrn_GUIDE_POINTER_MEDIA_SENTENCE_OVERRIDE_SENTENCEroTEXT_TO_VIDEO_SCHEMAIMAGE_TO_VIDEO_SCHEMAKEYFRAMES_TO_VIDEO_SCHEMAVIDEO_CONTINUATION_SCHEMAGET_RESULT_SCHEMAPROMPTING_GUIDE_SCHEMArFregisterr$rrrs8#"""""  ######  8 $ $   #(%)"J!bj!344 "*ABB!*UUUU----!%$( CCCCC\   "%&!$)RRR LLLL". P P P P    SSSS":QQQQUUUUF"'$(!'????"03030303f""""&""""J%%%%$;;;.(((("LLL>>>>iiii@@@@555599999999    ))))X))))6!!!!::::48ONNx PCY4444p & ! !   //11J % ( ' 6 6   :  :    ''))  y  }- %  4 + B B    :  :    ''))  "*;;q  "+cJJ3 ! !   ,CBB %3&&R +     : :   ''))  y  }- %  < # L!R !J   F %%B ( $2uUU  "vz "   ! #       #  " #       '  $ & #       '  $ & #           #       $  ! # #        r