HBG Gemini Flow Suite

把 Gemini Web + Flow / Veo 的图片、视频能力装进同一个 Docker，
一次授权 · 一条 CLI · 统一下载 · 可选媒体后处理

Important

这是非官方、基于网页会话和浏览器自动化的本地工具，不是 Google 官方 API，也不是传统 HTTP 反向代理。它把 Gemini Web 与 Flow 的生成入口统一代理到一条本地 CLI 中。请确认账号、地区、订阅和用途符合 Google 的现行条款。

⚡ 一句话交给 Agent 部署

把下面整段话发给 Codex、Claude Code，或其他能操作本机终端的 Agent：

请从 https://github.com/Mr-funny/hbg-gemini-flow-suite 部署 HBG Gemini Flow Suite。

检查 Docker、Docker Compose、Google Chrome/Chromium，复制 .env.example 为 .env，
提醒我设置新的 NOVNC_PASSWORD。启动后不要读取、打印或上传任何 Cookie、Chrome
Profile 或 Google 账号数据；只引导我分别执行 ./suite auth gemini 和 ./suite auth flow。
最后运行 ./suite status、测试和 Docker Compose 配置检查，并说明输出目录。

Agent 可以完成环境检查和容器部署；Gemini 与 Flow 登录必须由你在本机浏览器中完成。

🚀 核心卖点：把 Gemini Pro 用到极致

能力	Gemini Web	Flow / Veo
文生图	✅	✅
图生图	由对话支持	✅
文生视频	✅	✅
首帧 / 尾帧视频	—	✅
参考图视频	—	✅
原始命令透传	—	✅
自动下载与统一输出	✅	✅
可选可见标记与元数据后处理	✅	✅

真正省事的地方：

• 一次性封装两套入口：Gemini Web 图片、视频和 Flow / Veo 图片、视频都由 ./suite 调用。
• 完整 Docker 运行时：Chromium、字体、FFmpeg、noVNC 和 Python 依赖全部封装。
• 授权留在本机：Cookie 只导入 Docker volume，不写入仓库或命令参数。
• 适合批处理与 Agent：可进入短视频、首尾帧连续生成和自动化工作流。
• 输出可审计：文件统一落盘，并附带 result.json。
• 包含 Flow 兼容补丁：已适配 2026 年 8 月 References / 素材模式、x1 输出标签与新版提交按钮。
• Apple Silicon 原生 Flow runner：自动使用 linux/arm64 执行 gflow，避免 x86 Chromium 在 ARM 模拟下崩溃。

📦 三步部署

1. 准备环境

• Docker Desktop，或 Docker Engine + Compose v2。
• Google Chrome / Chromium。
• 可访问 Gemini 与 Flow 的网络环境。
• 具备对应 Gemini / Flow / Veo 权限和额度的 Google 账号。

主媒体容器仍固定为 linux/amd64，以保留 Gemini 和现有媒体后处理工具。Apple Silicon 会额外构建一个公开可复现的 linux/arm64 Flow runner；FLOW_RUNNER_MODE=auto 会自动选择，不再让容器 Chromium 依赖 x86 模拟。

2. 克隆并启动

git clone https://github.com/Mr-funny/hbg-gemini-flow-suite.git
cd hbg-gemini-flow-suite
cp .env.example .env

# 编辑 .env，至少修改 NOVNC_PASSWORD。
./suite up

./suite status
./suite logs
./suite down
./suite build

noVNC 仅绑定本机：http://127.0.0.1:7900/vnc.html

3. 完成两次授权

./suite auth gemini
./suite auth flow
./suite status

Gemini 使用 Gemini-API 所需的 Web Cookie；Flow 使用 gflow-cli 的独立 Chromium Profile。两者来自同一个本机登录会话，但运行时格式不同，因此要分别导入。授权保存在 Docker named volume gemini-flow-suite-data，不会写入 Git。

🎨 生成图片与视频

Gemini Web

./suite gemini image \
  "A cinematic Hong Kong cha chaan teng at night" \
  --out-dir gemini/images/hong-kong

./suite gemini video \
  "A slow cinematic push-in through a rainy neon street" \
  --out-dir gemini/videos/neon-street

./suite gemini video \
  "Animate this exact image as one slow cinematic shot" \
  --image /workspace/reference.png \
  --out-dir gemini/videos/image-to-video

可附加 --model MODEL、一个或多个 --image /workspace/...、--keep-originals 或 --no-clean。

Flow 图片

./suite flow image t2i \
  "Editorial food photography of beef offal noodles" \
  --model nano-banana-2 --aspect 9:16 \
  --out flow/images/noodles

./suite flow image i2i \
  "Turn this photo into a premium menu advertisement" \
  --ref /workspace/reference.png \
  --model nano-banana-2 --out flow/images/menu

Flow / Veo 视频

./suite flow video t2v \
  "A chef serves steaming beef offal noodles" \
  --model veo-quality --duration 4 --aspect 9:16 \
  --out-dir flow/videos/noodles

./suite flow video i2v \
  --initial-frame /workspace/start.png \
  --end-frame /workspace/end.png \
  "A smooth continuous camera move" \
  --model veo-quality --duration 4 \
  --out-dir flow/videos/transition

./suite flow video r2v \
  "Animate this exact reference image as one continuous cinematic shot" \
  --ref /workspace/reference.png \
  --model omni-flash --duration 8 --aspect 16:9 --count 1 \
  --out-dir flow/videos/reference-shot --json

video i2v 对应首帧 / 尾帧控制；video r2v 对应 Flow 新版 References / 素材 模式。用户要求“把完整母图作为素材图生视频”时，应使用 r2v --ref，不要误用 i2v --initial-frame。

只有日志依次确认素材上传、素材绑定、send_prompt 完成和生成接口返回 200，才算真正提交。仅进入编辑器或上传图片不代表已经开始生成。

Flow 原生命令透传

./suite flow raw models
./suite flow raw project list
./suite flow raw --help

Note

Flow 参数、模型名和 UI 控件会随上游变化。若参数被当前账号或 UI 忽略，结果以 Flow 页面实际暴露的能力为准。

📁 输出与挂载

默认输出：

outputs/
├── gemini/{images,videos}/
├── flow/{images,videos}/
└── .processing/

处理后文件名通常以 _clean 结尾，并写入 result.json。设置 KEEP_ORIGINALS=true 后，原文件保留在结果目录的 .originals/。

HOST_OUTPUT_DIR=/absolute/path/to/outputs
HOST_WORKSPACE_DIR=/absolute/path/to/your/project

主机路径	容器路径	权限
HOST_OUTPUT_DIR	/data/outputs	读写
HOST_WORKSPACE_DIR	/workspace	只读

🧠 工作原理

flowchart LR
    A["用户 / Agent"] --> B["./suite 主机 CLI"]
    B --> C["本机 Chrome 授权"]
    B --> D["Docker: gemini-flow-suite"]
    C --> E["Gemini Cookie"]
    C --> F["Flow Chromium Profile"]
    E --> D
    F --> D
    D --> G["Gemini Web wrapper"]
    D --> H["gflow-cli + Flow UI automation"]
    G --> I["图片 / 视频下载"]
    H --> I
    I --> J["可选媒体后处理"]
    J --> K["outputs/ + result.json"]

Loading

⚙️ 配置

cp .env.example .env

变量	默认值	说明
NOVNC_PASSWORD	必填	noVNC 密码；不要使用示例值
NOVNC_PORT	7900	本机 noVNC 端口
FLOW_CDP_PORT	9223	Flow Chrome 调试端口
GEMINI_CDP_PORT	9224	Gemini Chrome 调试端口
FLOW_CDP_BRIDGE_PORT	19223	macOS Docker Desktop 临时 CDP 桥接端口
GEMINI_CDP_BRIDGE_PORT	19224	Gemini 授权使用的临时 CDP 桥接端口
FLOW_RUNNER_MODE	auto	auto / arm64 / amd64 Flow runner 选择
HOST_PROXY / CONTAINER_PROXY	空	主机 / 容器代理
REMOVE_VISIBLE_WATERMARKS	true	启用可见标记与元数据后处理
KEEP_ORIGINALS	false	保留未处理原文件
IMAGE_CLEAN_BACKEND	migan	图片修复后端
GFLOW_CLI_PREFER_CLASSIC	true	优先经典 Flow 编辑模式
HOST_OUTPUT_DIR	./outputs	主机输出目录
HOST_WORKSPACE_DIR	.	只读参考素材目录

代理示例：

HOST_PROXY=http://127.0.0.1:10808
CONTAINER_PROXY=http://host.docker.internal:10808

🧹 可选媒体后处理

./suite clean image /workspace/input.png /data/outputs/manual/input_clean.png
./suite clean video /workspace/input.mp4 /data/outputs/manual/input_clean.mp4

后处理开关不是为了鼓励误导性发布。请保留必要的 AI 生成披露，并遵守平台条款、适用法律和发布渠道规则。

当前链路针对已知 Gemini 图片 sparkle / diamond、Gemini / Veo 视频中的小型可见文字或 diamond，以及常见 C2PA、EXIF、IPTC 和容器元数据。项目不宣称可以稳定移除像素级 SynthID，也不保证在动态背景、UI 更新或新标记样式下始终成功；正式发布前必须人工检查。

✅ 已验证环境

2026-08-09 本地验证：

• 容器健康运行，Gemini 与 Flow 两套持久化授权可用。
• Gemini 图片与视频生成、下载和可选后处理完成。
• Flow Nano Banana 2 图片生成、下载和可选后处理完成。
• Flow Veo 3.1 Lite 视频生成、下载和可选后处理完成。
• Flow 首帧 / 尾帧视频入口已适配 2026 年 7 月 UI。
• Flow Omni Flash video r2v 已在 References / 素材模式实际提交，单参考图、16:9、8 秒、x1，生成接口返回 200。
• Apple Silicon 原生 arm64 runner 已完成项目创建、Omni 模型选择、素材上传、提示词提交和生成轮询。
• 授权同步同时保留 *.google.com 与 *.google Cookie，避免遗漏 labs.google 的 Flow 会话。

Google 页面、模型名、额度策略和上游 CLI 都可能变化；“曾验证”不等于永久兼容。

🗂️ 项目结构

gemini-flow-suite/
├── SKILL.md
├── agents/openai.yaml
├── docs/showcase/hero.png
├── vendor/Gemini-API/
├── tests/
├── Dockerfile
├── Dockerfile.arm64-flow
├── compose.yaml
├── suite
├── suite_cli.py
├── run_gemini.py
├── sync_auth.py
├── sitecustomize.py
├── scripts/cdp_bridge.py
└── media_cleanup.py

仓库根目录同时是一个 Codex Skill。安装后可用 $hbg-gemini-flow-suite 触发部署、授权、Omni 素材图生视频和 Flow UI 兼容诊断流程。

🔐 安全与隐私

• .env、outputs/、Cookie、Chrome Profile、缓存和临时文件不会进入 Git。
• 登录发生在本机独立 Chrome Profile；Cookie 只导入 Docker named volume。
• noVNC 默认只监听 127.0.0.1，不要改成公网监听。
• 不要分享 gemini-flow-suite-data、~/.gemini-flow-suite 或浏览器 Profile。
• CI 会检查常见密钥格式和禁止追踪的授权文件名。

漏洞报告方式见 SECURITY.md。

⚠️ 限制与免责声明

• 非官方网页自动化项目，Google UI 变化可能随时导致功能失效。
• 账号订阅、地区、模型权限、生成额度和并发限制仍由 Google 决定。
• 项目不会绕过付费、额度、地区或账号权限。
• 不建议在多人共享服务器或公网无隔离环境中运行。
• Google、Gemini、Flow、Veo 为其各自权利人的商标；本项目与 Google 无隶属、赞助或认可关系。
• 你需要自行确认生成、自动化、后处理和发布方式符合相关条款与法律。

🧩 第三方项目

• HanaokaYuzu/Gemini-API — AGPL-3.0，源码快照位于 vendor/。
• ffroliva/gflow-cli — MIT。
• wiltodelta/remove-ai-watermarks — Apache-2.0。
• allenk/VeoWatermarkRemover — 构建时下载指定 release binary；上游当前未声明 SPDX 许可证，再分发镜像前请复核。

完整说明见 THIRD_PARTY_NOTICES.md。

🤝 贡献

欢迎提交兼容性修复、选择器更新、文档和测试。请阅读 CONTRIBUTING.md，不要在 Issue、日志或测试夹具中提交真实 Cookie、账号信息和生成历史。

📄 License

本仓库整体使用 GNU Affero General Public License v3.0，因为仓库直接包含并集成了 AGPL-3.0 的 Gemini-API 源码。第三方组件仍保留各自许可证。