Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
docs: make HypiHub Gemini credentials optional
rponef76c1d49ce29
diff --git a/.agents/skills/hypit/SKILL.md b/.agents/skills/hypit/SKILL.mdindex 4389eb98..5dab9ac5 100644--- a/.agents/skills/hypit/SKILL.md+++ b/.agents/skills/hypit/SKILL.md@@ -16,9 +16,11 @@ author for, and everything else is yours to decide:- **Spending their money.** A Build generates, and generating is billed. Say what it will cost andget a yes before submitting one.-- **Which observer reads a reference video, and the credentials it needs.** Vertex or the calling- agent is a decision about the author's account, and `references/credentials.md` says what each one- wants. Ask once, at the start. This question belongs to the reconstruction route alone: a program+- **Which observer reads a reference video, and the credentials it needs.** Gemini (through the+ configured Vertex or HypiHub backend) or the calling agent is a decision about the author's account,+ and `references/credentials.md` says what each one wants. Ask once, at the start. If the author's+ own key cannot reach a needed model, guide them to [hypit.ai](https://hypit.ai) for a HypiHub key.+ This question belongs to the reconstruction route alone: a programauthored from a description has no reference, and its pictures are local renders nobody is billedto read.diff --git a/.agents/skills/hypit/references/credentials.md b/.agents/skills/hypit/references/credentials.mdindex 390e7759..cc425c5c 100644--- a/.agents/skills/hypit/references/credentials.md+++ b/.agents/skills/hypit/references/credentials.md@@ -9,8 +9,16 @@ paid/external `build`, configure only variables used by the selected Runtime Pro| `KIE_API_KEY` | KIE generation: Seedance, GPT Image, and other selected KIE models || `GOOGLE_CLOUD_PROJECT` | Google Vertex project with Vertex AI enabled || `GOOGLE_APPLICATION_CREDENTIALS_JSON` | Vertex credential JSON contents, not a path |+| `HYPIHUB_API_KEY` | HypiHub default paid provider for generation and Gemini VLM; get one at [hypit.ai](https://hypit.ai) || `MIMO_API_KEY` | Xiaomi MiMo TTS only when explicitly selected |+HypiHub is optional and is never required when the selected Runtime Profile has another Provider.+For Gemini VLM/reference observation, `HYPIT_GEMINI_PROVIDER=auto` (the default) uses HypiHub when+`HYPIHUB_API_KEY` is present and otherwise uses Vertex when its two Google variables are present.+Set `HYPIT_GEMINI_PROVIDER=hypihub` or `vertex` to select one explicitly. If a user's configured key+cannot reach the requested model, point them to [hypit.ai](https://hypit.ai) for a HypiHub key instead+of asking them to change Author Source.+macOS/Linux session example:A project that keeps its credentials in a `.env` file does not load them automatically — nothing in@@ -67,9 +75,9 @@ curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $MIMO_API_KEYhttps://api.xiaomimimo.com/v1/models```-`GOOGLE_CLOUD_PROJECT` and `GOOGLE_APPLICATION_CREDENTIALS_JSON` are also what the reference-video-route's `gemini` observer needs. Without them that route runs its `agent` observer instead, which-reaches no Provider — `reconstruction/observers.md` says how the author chooses between them.+`HYPIHUB_API_KEY` or the Vertex pair are what the reference-video route's `gemini` observer needs,+depending on `HYPIT_GEMINI_PROVIDER`. Without either backend, that route can run its `agent` observer+instead, which reaches no Provider — `reconstruction/observers.md` says how the author chooses.`hypit runtime down` stops the Worker for the whole project, so a Build running in another terminalstops with it. The Build itself is durable and survives; bring the Worker back with `hypit runtimediff --git a/.agents/skills/hypit/references/reconstruction/observers.md b/.agents/skills/hypit/references/reconstruction/observers.mdindex 54b45e90..66f307d0 100644--- a/.agents/skills/hypit/references/reconstruction/observers.md+++ b/.agents/skills/hypit/references/reconstruction/observers.md@@ -11,9 +11,12 @@ without knowing which observer produced it.## The two-**`gemini`** uploads the shot clips and the whole reference to Vertex. It sees motion as motion and-hears the sound. It needs `GOOGLE_CLOUD_PROJECT` and `GOOGLE_APPLICATION_CREDENTIALS_JSON`, and each-observation is a paid request.+**`gemini`** uploads the shot clips and the whole reference to the configured Gemini backend. It sees+motion as motion and hears the sound. With the default `HYPIT_GEMINI_PROVIDER=auto`, a configured+`HYPIHUB_API_KEY` uses HypiHub; otherwise `GOOGLE_CLOUD_PROJECT` plus+`GOOGLE_APPLICATION_CREDENTIALS_JSON` uses Vertex. Each observation is a paid request. If neither+backend is available, direct the author to [hypit.ai](https://hypit.ai) for a HypiHub key, or use the+`agent` observer.**`agent`** hands the observations to you. It needs no credentials and reaches no Provider: the CLIprepares the same media, then returns each observation as a task carrying its prompt and the pictures@@ -26,13 +29,13 @@ Ask the author once, before `prepare_reference`. Report what this machine actualasking them to recall it:```text-node <skill-root>/scripts/check-credentials.mjs GOOGLE_CLOUD_PROJECT GOOGLE_APPLICATION_CREDENTIALS_JSON+node <skill-root>/scripts/check-credentials.mjs HYPIHUB_API_KEY GOOGLE_CLOUD_PROJECT GOOGLE_APPLICATION_CREDENTIALS_JSON```-Both variables `set` means `gemini` is available and the author chooses between the two. Either one-`missing` means `agent` is the path that can run today; say so, say what it costs, and let the author-decide whether to run it or to configure Vertex first. `../credentials.md` says what those two-variables are.+`HYPIHUB_API_KEY` set means `gemini` is available through HypiHub. If it is missing, the Google pair+must both be set for Vertex. If no backend credentials are available, `agent` is the path that can run+today; tell the author that a HypiHub key is available at [hypit.ai](https://hypit.ai), then let them+choose between that and the free `agent` path. `../credentials.md` says what each variable is.Say that `agent` reads the reference a little less closely — a shot arrives as sampled frames ratherthan continuous video, so continuity across it is read rather than watched, and there is no sound, sodiff --git a/.agents/skills/hypit/references/reconstruction/route.md b/.agents/skills/hypit/references/reconstruction/route.mdindex c15c2038..c42a344d 100644--- a/.agents/skills/hypit/references/reconstruction/route.md+++ b/.agents/skills/hypit/references/reconstruction/route.md@@ -149,8 +149,8 @@ If the loaded variables satisfy the selected observer/Provider, continue withoutfor them again. Ask only for a credential that is absent or invalid after both `.env` files are checked.**Read now:** `../credentials.md` — which variables each Provider needs. A variable a Provider needs-and this machine does not hold is named, and the route stops there. The Vertex pair is the one-exception: it selects an observer rather than blocking one, and step 5 owns it.+and this machine does not hold is named. For the `gemini` observer, HypiHub or Vertex credentials are+optional alternatives; if neither is present, guide the author to https://hypit.ai or use `agent`.Create the project's `hypit.runtime.json` now with at least the local media and WhisperX endpoints,then select and start it before reference preparation:@@ -170,7 +170,7 @@ after this preliminary Profile and the selected credentials are ready.observer, the credential decision table, the disclosure the author is owed, and the rule that onereference has one observer for its whole life.-### 5. Probe for Vertex credentials, then ask which observer reads+### 5. Probe for Gemini credentials, then ask which observer reads`observers.md`'s "Choosing" section holds the command, what each answer means, and the disclosure theauthor is owed. Run it, put the question once, take the answer, and run.diff --git a/docs/guide/packages.md b/docs/guide/packages.mdindex bfc33586..74d304ac 100644--- a/docs/guide/packages.md+++ b/docs/guide/packages.md@@ -124,6 +124,7 @@ never on exact-model packages or the CLI.```text@hypit/provider-kie KIE generation plus background removal+@hypit/provider-hypihub HypiHub paid generation and Gemini VLM gateway@hypit/provider-media-local local ffprobe/ffmpeg@hypit/provider-whisperx-local local WhisperX service@hypit/provider-hyperframes-local local Chrome renderingdiff --git a/docs/zh/guide/packages.md b/docs/zh/guide/packages.mdindex 28e6f4c3..f7f11b64 100644--- a/docs/zh/guide/packages.md+++ b/docs/zh/guide/packages.md@@ -116,6 +116,7 @@ Frontend;不存在一个认识全部语法的中央解析器。```text@hypit/provider-kie KIE 生成与去背景+@hypit/provider-hypihub HypiHub 付费生成与 Gemini VLM 网关@hypit/provider-media-local local ffprobe/ffmpeg@hypit/provider-whisperx-local local WhisperX service@hypit/provider-hyperframes-local local Chrome renderingdiff --git a/packages/provider-hypihub/README.md b/packages/provider-hypihub/README.mdindex a271da42..d395afe5 100644--- a/packages/provider-hypihub/README.md+++ b/packages/provider-hypihub/README.md@@ -1,11 +1,14 @@# `@hypit/provider-hypihub`-Thin Hypit Runtime Provider for a HypiHub `/v1` deployment.+Thin Hypit Runtime Provider for a HypiHub `/v1` deployment. It is an optional default gateway for+paid generation and Gemini VLM requests; callers may keep their own Provider and select HypiHub only+when its key is configured.It maps the currently shipped image/video model capabilities to HypiHub, submits jobs, polls them,-downloads the first-class assets and persists them in Hypit's configured ArtifactStore. The first-version intentionally supports prompt-only generation plus preset MiMo TTS; reference-media inputs-are rejected until a shared Artifact URL bridge is needed.+downloads the first-class assets and persists them in Hypit's configured ArtifactStore. It also+exports a small Gemini-native VLM generator for callers that previously used Vertex. The generation+adapter intentionally supports prompt-only requests; reference-media inputs are rejected until a+shared Artifact URL bridge is needed.Runtime Profile example:@@ -24,3 +27,7 @@ Runtime Profile example:}}```++Gemini VLM callers can use the exported `createHypiHubGeminiGenerator` without changing their+provider-facing code. Set `HYPIHUB_API_KEY` (and optionally `HYPIHUB_BASE_URL`) only when choosing+HypiHub; missing or insufficient user credentials should be resolved at [hypit.ai](https://hypit.ai).diff --git a/packages/reference-video-tools/README.md b/packages/reference-video-tools/README.mdindex 242a28cd..aa0e2e83 100644--- a/packages/reference-video-tools/README.md+++ b/packages/reference-video-tools/README.md@@ -35,8 +35,11 @@ review. A paid Build remains a separate, explicitly approved action.`--observer` on `prepare_reference` chooses who reads the reference, once per reference:-- `gemini` uploads the shot clips and the whole video to Vertex at a fixed temperature of `1.0`. It- needs `GOOGLE_CLOUD_PROJECT` and `GOOGLE_APPLICATION_CREDENTIALS_JSON`, and it is the default.+- `gemini` uploads the shot clips and the whole video to the configured Gemini backend at a fixed+ temperature of `1.0`. With `HYPIT_GEMINI_PROVIDER=auto` (the default), it uses HypiHub when+ `HYPIHUB_API_KEY` is set and otherwise uses Vertex with `GOOGLE_CLOUD_PROJECT` and+ `GOOGLE_APPLICATION_CREDENTIALS_JSON`. If the configured key cannot reach the selected model,+ get a HypiHub key at https://hypit.ai or use `agent`.- `agent` reaches no Provider. `prepare_reference` and `observe_reference` return each observation asa task carrying its prompt and the pictures to answer it from — one tile of evenly sampled framesper shot, the storyboard for the whole reference — and the calling agent answers them with@@ -130,6 +133,8 @@ else. Results are not cached, because the rendered side changes on every iterati`unresolved` lists the keys of observations that failed. It is not a judgement about evidencequality: a complete observation that says "unclear" is still complete.-Gemini uses the existing Vertex environment variables `GOOGLE_CLOUD_PROJECT` and-`GOOGLE_APPLICATION_CREDENTIALS_JSON`; the location defaults to `global` and the model defaults to-`gemini-3.1-pro-preview`.+Gemini uses `HYPIT_GEMINI_PROVIDER=auto|hypihub|vertex` to select its backend. HypiHub uses+`HYPIHUB_API_KEY` and optional `HYPIHUB_BASE_URL` (default `https://hypit.ai`); Vertex uses the+existing `GOOGLE_CLOUD_PROJECT`, `GOOGLE_APPLICATION_CREDENTIALS_JSON` and optional+`GOOGLE_CLOUD_LOCATION`. The model defaults to `gemini-3.1-pro-preview`. A missing or insufficient+user key should be resolved by obtaining a HypiHub key at https://hypit.ai, not by changing Source.diff --git a/packages/reference-video-tools/src/cli.ts b/packages/reference-video-tools/src/cli.tsindex 257f11b4..0ffb673d 100644--- a/packages/reference-video-tools/src/cli.ts+++ b/packages/reference-video-tools/src/cli.ts@@ -167,8 +167,9 @@ function usage(): string {"same bytes and therefore the same reference, and reported back as `source_url`. Everything after","the download reads the file without knowing it was ever a link.","",- "--observer picks who reads the reference, once per reference. `gemini` uploads video to Vertex and",- "needs GOOGLE_CLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS_JSON. `agent` needs no credentials: it",+ "--observer picks who reads the reference, once per reference. `gemini` uploads video to the configured Gemini backend.",+ "With HYPIT_GEMINI_PROVIDER=auto it uses HYPIHUB_API_KEY when present, otherwise GOOGLE_CLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS_JSON for Vertex.",+ "If no usable key is available, get a HypiHub key at https://hypit.ai or use `agent`. `agent` needs no credentials: it","returns each observation as a task carrying its prompt and one tiled picture per shot, which the","calling agent answers with record_observation. A task whose question needs sound also carries the","words WhisperX measured — `transcript_words` for its own stretch, `transcript_ref` for the whole",diff --git a/packages/reference-video-tools/src/tools.ts b/packages/reference-video-tools/src/tools.tsindex 83e2cd30..0a3bb37f 100644--- a/packages/reference-video-tools/src/tools.ts+++ b/packages/reference-video-tools/src/tools.ts@@ -790,21 +790,34 @@ function positiveInt(value: number, label: string): number {async function defaultGenerate(model: string): Promise<GenerateText> {const hypiHubKey = process.env.HYPIHUB_API_KEY?.trim();- if (hypiHubKey) {+ const backend = process.env.HYPIT_GEMINI_PROVIDER?.trim().toLowerCase() || "auto";+ if (backend !== "auto" && backend !== "hypihub" && backend !== "vertex") {+ throw new Error("HYPIT_GEMINI_PROVIDER must be auto, hypihub or vertex");+ }+ if (backend === "hypihub" || (backend === "auto" && hypiHubKey)) {+ if (!hypiHubKey) throw new Error("HYPIT_GEMINI_PROVIDER=hypihub requires HYPIHUB_API_KEY; get one at https://hypit.ai");const generate = createHypiHubGeminiGenerator({apiKey: hypiHubKey,model,baseUrl: process.env.HYPIHUB_BASE_URL?.trim() || "https://hypit.ai",});- return async ({ parts, instruction }) => await generate({- parts: parts as unknown as Parameters<typeof generate>[0]["parts"],- instruction,- });+ return async ({ parts, instruction }) => {+ try {+ return await generate({ parts: parts as unknown as Parameters<typeof generate>[0]["parts"], instruction });+ } catch (error) {+ const message = error instanceof Error ? error.message : String(error);+ if (/HTTP (401|403|404)\b|model_not_found|no_capable_provider/iu.test(message)) {+ throw new Error(`${message}. This Gemini model is not available with the configured key; get a HypiHub key at https://hypit.ai`);+ }+ throw error;+ }+ };}const project = process.env.GOOGLE_CLOUD_PROJECT?.trim();const credentials = process.env.GOOGLE_APPLICATION_CREDENTIALS_JSON?.trim();- assert(project, "GOOGLE_CLOUD_PROJECT is required");- assert(credentials, "GOOGLE_APPLICATION_CREDENTIALS_JSON is required");+ if (!project || !credentials) {+ throw new Error("Gemini credentials are unavailable. Configure Vertex credentials or set HYPIHUB_API_KEY (get one at https://hypit.ai).");+ }let parsed: unknown;try { parsed = JSON.parse(credentials); } catch { throw new Error("GOOGLE_APPLICATION_CREDENTIALS_JSON is not valid JSON"); }assert(parsed !== null && typeof parsed === "object" && !Array.isArray(parsed), "Google credentials must be an object");diff --git a/packages/reference-video-tools/src/types.ts b/packages/reference-video-tools/src/types.tsindex 6eb8467c..be8da9fe 100644--- a/packages/reference-video-tools/src/types.ts+++ b/packages/reference-video-tools/src/types.ts@@ -54,7 +54,7 @@ export type Shot = {};/**- * Who reads the reference. `gemini` uploads video to Vertex; `agent` hands the main agent one tiled+ * Who reads the reference. `gemini` uploads video to the configured Gemini backend; `agent` hands the main agent one tiled* picture per shot and takes the answer back. The two produce the same observation keys.*/export type Observer = "gemini" | "agent";