gflow-cli

gflow-cli

用于 Google Flow 的 Python 命令行工具和 MCP 服务。从终端驱动 Veo（图像转视频、文本转视频）和 Imagen（文本转图像）：支持脚本化、批量处理，适合构建流水线。

⚠️ 安装前请阅读。 gflow-cli 目前处于 alpha 阶段，且为逆向工程项目——与 Google 无关。它会在你自己的 Google Flow 会话中驱动有头浏览器，因此请自行承担账号风险：自动化操作受 Google 服务条款约束，端点或界面也可能随时变更，恕不另行通知。任何拥有 Flow 使用权限的 Google 账号均可使用，所有生成都会从账号的 Flow 积分额度中扣除。请阅读完整的免责声明。

🛡️ “这样会导致我的账号被标记吗？” 关于工具如何尽量避免引人注意（使用有头的真实 Chrome、随机化交互时序、控制提交频率），明确不会做什么（不使用代理、不伪造指纹、不假装没有使用自动化），你可以调整哪些设置，以及我们无法作出哪些保证，诚实而具体的答复见 docs/ACCOUNT_SAFETY.md。

💳 失败会造成什么损失。 只有 Veo 视频生成会消耗积分——图像和合成操作均免费，因此大多数故障不会造成任何损失。如果运行期间 Flow 界面发生变化，命令行工具会立即报错并显示明确的退出代码（例如选择器变化时退出代码为 23），而不会重新提交；批处理项目也会在提交前记录到本地，因此运行中断时，过时状态不会悄无声息地消耗积分。当前风险列表请见 KNOWN_ISSUES。

🌐 目前使用有头浏览器。 gflow 通过持久化的 Playwright Chromium 配置文件驱动 Flow，因为 Google 的身份验证和 reCAPTCHA 验证需要使用浏览器。架构部分说明了你可以在哪些方面提供帮助。

为什么选择 gflow-cli？

你拥有可使用 Flow 的 Google 账号，有 Veo 点数，并且要处理实际的批量任务。gflow-cli 可为你提供：

• 批量生成。 直接在 shell 中循环处理提示词：for p in $(cat prompts.txt); do gflow image t2i "$p"; done。图像批量处理以及 gflow video t2v / i2v / r2v 现已全部可用，gflow video extend 还能让现有片段突破 Flow 的 8s 时长上限。
• 一致的主体。 gflow character create 会创建一个 Flow Character（面部和身体参考），让同一个人物在连续生成的内容中保持一致。
• 提示词工具。 --tool creative-director 会在生成前，按照 Google 的 5 部分公式，将简短的提示词改写得更生动——适用于任何命令。你也可以通过 My Tools 使用自己的工具。
• 工作流。 将 Veo 接入内容自动化、AI 视频技术栈或批量实验。
• 原生支持终端。 执行一次 gflow auth login 后，你就可以一直在 shell 中操作，无需点击对话框。会自动在后台续期过期的会话：gflow auth renew。

使用相同的 Veo 和 Imagen 模型，获得相同的质量，费用仍由你自己的 Google 账号承担，现在还可以通过程序调用。

60 秒快速入门

# 1 · Install (uv recommended; also: pip install gflow-cli)
uv tool install gflow-cli
uv tool run --from gflow-cli playwright install chromium     # one-time, ~150 MB
# later: `gflow update` upgrades in place (every command shows a banner when a newer release is out)

# 2 · Authenticate (one-time, opens a real Chrome window)
# Behind a proxy (e.g. Clash)? Set GFLOW_CLI_BROWSER_PROXY=http://127.0.0.1:7897 first (docs/CONFIGURATION.md)
gflow auth login --browser chrome

# Check the session (spends nothing)
gflow auth status
gflow credits user          # Veo credit balance (opens Flow in the browser; spends nothing)

# 3 · Generate
gflow image t2i "a hot air balloon over Tokyo at sunrise"
# or:
gflow video t2v "Slow cinematic push-in on a sunlit forest clearing" --aspect 16:9
# or mint a reusable Character (face + body reference):
gflow character create --project <id> --name "Aria" --face-prompt "..." --body-prompt "..."

输出会保存到 $GFLOW_CLI_OUTPUT_DIR，你也可以通过 GFLOW_CLI_STORAGE_URI 将输出保存到 S3、MinIO 或 Google Cloud Storage。首次调用需要 30 到 90 秒来预热 Chromium；之后的调用会复用已预热的会话。

为什么使用 --browser chrome？ 这是唯一会将配置文件标记为真实 Chrome 配置文件的策略，后续生成任务会使用此配置文件运行。只要检测到已安装 Chrome，默认的 auto 就会选择该策略——请参阅 docs/AUTHENTICATION.md。

从本地检出目录安装？ uv tool install <path> 会忽略 uv.lock，并根据 pyproject.toml 中的版本范围解析依赖，因此安装的 Playwright 版本可能未经本项目测试。Playwright 自带浏览器驱动，未经测试的小版本可能会导致生成任务无声地卡住。请明确指定锁定的版本：

uv tool install --force --with playwright==1.59.0 .

从 PyPI 安装（uv tool install gflow-cli）不受影响——已发布的版本范围设置了上限。使用 uv tool run --from gflow-cli python -c "import importlib.metadata as m; print(m.version('playwright'))" 检查实际安装的版本。

如需查看包含故障排查和多账号设置的完整 10 分钟指南，请参阅 USER_GUIDE: Journey 1。

示例

输入一条命令，即可获得真实的 Flow 输出。左侧：gflow image t2i 在你的图库中生成逼真的场景。右侧：帧间变换。

演示

在已登录的 Flow 配置文件上调用一次 gflow image t2i "..." --aspect 9:16 --model nano2。终端会实时输出本次运行的 structlog JSON，然后列出写入的 PNG 文件。Chromium 会在后台静默操控 Flow 编辑器。

使用 scripts/record_demo.ps1（Windows、OBS、ffmpeg、gifski）复现此录制内容。更多格式，包括并排分屏版：docs/DEMOS.md。

文档

docs/INDEX.md 是主路由层。快速链接：

主题	阅读
🎯 快速入门	用户指南 · 用法 · 配置
存储与目录	外部存储 · 数据层
🎭 角色	角色，可重复使用的主体（gflow character）
🤖 Agent 与自动化	指令（gflow instructions，持久化简报卡片） · 影片（gflow movie，多场景清单） · 工具（--tool，提示词重写） · MCP 服务（gflow mcp run / gflow serve）
🔐 身份验证与会话	身份验证 · 已知问题
📣 安装来源	市场（每个渠道及其实际提供的内容） · 容器（为何镜像可以检查内容，却无法生成）
🏗️ 内部实现	架构 · 安全 · 调试
📦 发布	更新日志 · 路线图 · 发布协议 · 项目状态
🤝 参与贡献	贡献指南 · 开发 · GitHub 工作流

面向 AI Agent 与大模型

gflow-cli 提供四个 Agent 入口。选择你的工具最先读取的入口。

文件	适用对象	工具
AGENTS.md	通用编码 Agent 规范	Cursor · Codex · Aider · Antigravity · Jules · Devin · Windsurf · Zed · Warp · opencode · Copilot
CLAUDE.md	Claude Code 自动加载的记忆	Claude Code
llms.txt	大模型可读摘要（llmstxt.org 格式）	粘贴到 ChatGPT、Claude 或 Gemini 中，为模型提供入门信息
skills/gflow-cli/SKILL.md	Claude Code Skill	创建符号链接到 ~/.claude/skills/

安装插件（Claude Code）

只需一步，即可获得 gflow-cli 和 video-production 技能以及 MCP 服务：

/plugin marketplace add ffroliva/gflow-cli
/plugin install gflow@gflow-cli

插件默认禁用。启用插件后，Claude Code 会自动启动其 MCP 服务，且不会另行提示——而此服务会使用你自己的 Google 账号，Veo 视频生成会消耗你的额度。因此，安装插件不会启动任何内容，而启用插件则需要你主动操作。图片和构图免费；只有视频会消耗额度。如需绝对保证，请自行使用 gflow mcp run --no-spend 注册服务；此命令完全不会注册消耗额度的工具。详情请参阅 docs/MCP.md，包括 /plugin marketplace add 会提供哪个修订版本。

Codex 用户：运行 codex plugin marketplace add .，然后运行 codex plugin add gflow@gflow-cli。

用一行命令为任意 Agent 提供入门信息。将以下内容粘贴到你选择的 Agent 中：

“阅读 AGENTS.md 和 docs/INDEX.md，然后帮我处理 Flow 批次。”

架构与当前限制

gflow CLI  →  Provider (interchangeable)  →  Flow (ui_automation) / Mock (tests) / [planned: Official Veo]
                                              ↓
                                      Playwright Chromium (headed — login AND generation, by default)
                                              ↓
                              aisandbox-pa.googleapis.com  (Google's private Flow API)

当前传输方式：ui_automation 通过持久化的 Playwright Chromium 配置文件驱动 Flow。该方式已达到生产稳定性，并在每次发布时通过端到端验证（参见每个版本对应的 LIVE_VERIFICATION_* 证据文件）。

两个 Flow 前端：Google 正在将账号从 labs.google 迁移到 flow.google.com（#639）——这是同一款产品，但采用不同的小部件工具包和线协议（使用 batchexecute 而非 aisandbox-pa）。已迁移的驱动支持文本生成视频、从本地起始帧生成视频、从本地文件生成参考视频、文本生成图像、从本地文件生成图像，以及单片段 video extend。图像生成支持 Nano Banana 2.1（nano2，#958）/ 2 Lite / Pro、在该主机上测得的五种宽高比（16:9、4:3、1:1、3:4、9:16），以及 1–4 张图；传输边界处必须已有项目。图像可通过 @Name 标记角色（#723）。使用仅限 Agent 撰写器的账号（#799）仅支持文本生成图像和文本生成视频。如果目录记录的图像 --ref <uuid> 与 --project 属于同一项目，则会在原位置引用该图像（#995）。其他 UUID 媒体引用、没有名称的实体 ID、指令、Imagen 4，以及矩阵中的其余功能，在移植完成前仍由 labs 驱动支持（GFLOW_CLI_FLOW_HOST，参见 CONFIGURATION）。

**受阻事项：**纯 HTTP 视频生成传输方式。视频上传端点在非 Chrome 浏览器下会返回 HTTP 401，并使用我们无法在无头环境中复现的 reCAPTCHA mint。此前的三种 HTTP 方案（evaluate_fetch、bearer、sapisidhash）位于 src/gflow_cli/api/transports/experimental/，仅用于研究，不属于生产路径。

**如何提供帮助：**如果你曾在真实 Chrome 会话之外调用 aisandbox-pa.googleapis.com，或了解 Google 在此处使用的反机器人机制，请提交 issue。可用的 REST 传输方式将支持无服务器部署、真正的水平并发，并让项目的覆盖范围扩大约 10 倍。详情见：docs/ARCHITECTURE.md § Headed-browser dependency。

项目状态

**Alpha。**图像（t2i、i2i、上传、放大、批处理）和视频（t2v、i2v、r2v、链式生成、扩展、放大）均可通过 ui_automation 端到端运行，配有 5 模型 Veo 选择器以及 --duration 和 --count。除单次生成外：gflow movie 可渲染多场景清单，gflow instructions 可管理持久化的 Agent-Mode 简报卡片（不消耗积分），gflow character 可处理可重复使用的主体，gflow scene 可在服务器端进行免积分拼接，--tool 可应用提示词改写工具；MCP 服务（gflow mcp run stdio / gflow serve Streamable HTTP）可向 AI Agent 暴露核心功能，并通过 CI 强制执行 CLI↔MCP 奇偶一致性契约。

完整的里程碑历史记录见 CHANGELOG.md。项目的发展方向见 ROADMAP.md。

支持 gflow-cli

gflow-cli 由一人构建和维护。每个版本都会使用真实的 Google Flow 进行验证，这会消耗实际的 AI 积分；由于有人在自己的流水线中使用它，出现的问题也能迅速修复。赞助可以支持这两项工作。

在工作中依赖 gflow-cli？公司的月度赞助档位可将贵公司的 Logo 列在这里，Silver 及以上档位还可获得问题优先处理。所有档位及其权益：docs/SPONSORS.md。

在自己的分支中修复了 gflow-cli？请提交问题或拉取请求——修复合并到上游后，所有人都能受益。

名人堂

目前还没有赞助者。成为第一位——所有公开赞助者都会列在这里。

许可证与法律声明

MIT 许可证 © 2026 Flavio Oliva（ffroliva）。MIT 许可证仅适用于 gflow-cli 的代码，不授予任何与 Flow、Veo 模型输出或任何 Google 服务相关的权利。您的生成内容受 Google 自有条款（Labs 附加条款及任何特定套餐的订阅条款）约束。请参阅免责声明。

致谢

• edge-tts，为基于私有云 API 构建社区 SDK 提供了设计灵感。
• googleapis/python-genai，官方 Veo SDK，未来的提供方版本可能会将其作为别名。
• Keysight，《Google Labs – Flow AI with Veo3：网络流量分析》，这份独立捕获记录有助于验证路由模式。

---

统计数据

Star 历史

如果 gflow-cli 帮你节省了时间，请给仓库点个 ⭐。这是支持该项目最省钱的方式。