内容
# flow-api-mcp
Web2API 包装器，用于 [Google Labs Flow](https://labs.google/fx/tools/flow) — 以 MCP（模型上下文协议）服务器的形式公开图像和视频生成。
使用 Playwright 驱动持久的 **Google Chrome** 配置文件，因此您只需使用自己的 Google 帐户进行一次身份验证，然后在每次后续调用时重用该会话。
```
AI 代理（Claude/Cursor/opencode）→ MCP（stdio 或 HTTP）→ Playwright + Chrome → Google Flow
```
## 功能
- `generate_image` — 通过 Nano Banana 2 / Nano Banana Pro / Imagen 4 进行文本转图像
- `generate_video` — 通过 Omni Flash / Veo 3 / Veo 3.1（多步骤代理，几分钟每剪辑）进行故事板驱动的视频生成
- `flow_status` — 验证会话，列出图像和视频模型，宽高比
- `flow_login` — 打开一个可见的浏览器进行一次性登录
- `flow_close` — 关闭浏览器
- **HTTP 传输** — 通过 `POST /mcp` 与 bearer-token 身份验证公开相同的工具，以及 `GET /health`、`POST /admin/import-cookies`、`GET /admin/cookie-status`
- **自动浏览器清理** — 每个脚本都在 `finally` 中关闭 Chrome，杀死孤立进程，删除配置文件锁；不再需要手动 `Stop-Process`
- 宽高比：`16:9`、`4:3`、`1:1`、`3:4`、`9:16`（图像）；`16:9`、`9:16`（视频）
- 可配置的输出目录
- 默认情况下无头（浏览器仅在登录时可见）
- Cookie 导入 — 重用从另一个 Chrome 实例导出的 Cookie
## 快速开始
```bash
cd "D:/code/flow api"
npm install
copy .env.example .env
# 选项 A — 交互式登录（打开一个可见的 Chrome 窗口）
npx flow-api login
# ... 然后登录到 Google，关闭标签页，Ctrl+C
# 选项 B — 导入从另一个浏览器导出的 Cookie
# （例如，通过 Chrome 扩展程序“Cookie-Editor”导出为 JSON）
npx flow-api import-cookies path/to/cookies.json
# 验证会话
npx flow-api status
# 快速 CLI 测试
npx flow-api test "一个充满霓虹灯的电影般的猫在城市中"
# 启动 MCP 服务器（stdio）
npx flow-api serve
# 或启动 HTTP 服务器（适用于远程客户端）
npx flow-api serve-http
```
Chrome 配置文件位于 `./data/chrome-profile/`，持续约 30 天。
## 为什么使用真正的 Chrome？
Google 的生成端点 (`aisandbox-pa.googleapis.com`) 在使用 Playwright 的捆绑 Chromium 调用时返回 **HTTP 403**，默认情况下具有反机器人标志。为了绕过这一点，我们启动您安装的 `Google Chrome`（通道：'chrome'）并注入一个小的隐身初始化脚本，隐藏 `navigator.webdriver`、自动化切换和其他几个指纹。
如果您真的想要捆绑的 Chromium，请在 `.env` 中设置 `USE_SYSTEM_CHROME=false` — 但预计大多数生成操作都会因 403 错误而失败。
## MCP 客户端配置
### opencode / Claude Desktop
将以下内容添加到您的 MCP 配置文件中（例如 `~/.config/opencode/opencode.jsonc` 或 `%APPDATA%\Claude\claude_desktop_config.json`）：
```json
{
"mcpServers": {
"flow-api": {
"command": "npx",
"args": ["flow-api", "serve"],
"cwd": "D:/code/flow api"
}
}
}
```
或直接使用 Node：
```json
{
"mcpServers": {
"flow-api": {
"command": "node",
"args": ["D:/code/flow api/bin/flow-api.js", "serve"]
}
}
}
```
## HTTP 传输
相同的 MCP 工具通过 HTTP 为远程客户端公开：
```bash
npx flow-api serve-http # 监听 $HTTP_PORT（默认为 8787）
curl -X POST http://localhost:8787/mcp \
-H "Authorization: Bearer $HTTP_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"flow_status","arguments":{}}}'
```
端点：
| 方法 | 路径 | 身份验证 | 目的 |
|---|---|---|---|
| `POST` | `/mcp` | bearer | JSON-RPC MCP 调用 |
| `GET` | `/health` | 可选 bearer | `{ ok, status, cookieCount, lastImport }` |
| `POST` | `/admin/import-cookies` | bearer | 上传 cookies.json 或 JSON 正文 `{ cookies: [...] }` |
| `GET` | `/admin/cookie-status` | bearer | 检查当前 Cookie + 过期时间 |
使用以下命令生成令牌：`node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`
## 工具
### `generate_image`
| 参数 | 类型 | 必需 | 默认值 | 描述 |
|---|---|---|---|---|
| `prompt` | 字符串 | 是 | — | 文本提示 |
| `model` | 枚举 | 否 | `nano-banana-2` | `nano-banana-2` / `nano-banana-pro` / `imagen-4` |
| `aspect_ratio` | 枚举 | 否 | — | `16:9` / `4:3` / `1:1` / `3:4` / `9:16` |
| `output_dir` | 字符串 | 否 | `./output` | 重写保存位置 |
返回： `{ ok, jobId, prompt, files: [...绝对路径] }`
### `generate_video`
| 参数 | 类型 | 必需 | 默认值 | 描述 |
|---|---|---|---|---|
| `prompt` | 字符串 | 是 | — | 场景描述（例如：“一只纸船在月光下的河流中漂浮”）|
| `aspect_ratio` | 枚举 | 否 | `16:9` | `16:9` / `9:16` |
| `count` | 整数 | 否 | `1` | 要生成的剪辑数量，`1`-`4` |
| `output_dir` | 字符串 | 否 | `./output` | 重写保存位置 |
返回： `{ ok, jobId, prompt, files: [...绝对路径到 .mp4] }`
> **注意** — 视频生成是 **多步骤且缓慢的**。Flow 的故事板代理首先起草一个 4-6 场景计划，然后依次生成每个剪辑。计划时间通常为 10-30 秒；剪辑时间每场景为 1-5 分钟。`count=4` 的总运行时间可能为 **15-30 分钟**。HTTP 请求在此期间被阻塞。
>
> 需要 **Pro / 付费** Flow 计划 — 免费层没有 Omni/Veo 访问权限。
### `flow_status`
返回登录状态、浏览器正常运行时间、图像和视频模型列表、宽高比和配置路径。
### `flow_login`
打开一个有头的 Chrome 窗口进行手动 Google 登录。用户登录后，会话 Cookie 将保存在本地配置文件中。可以多次调用 — 安全
### `flow_close`
释放浏览器。
## CLI
```
npx flow-api login # 打开浏览器，交互式登录
npx flow-api status # 检查会话，列出模型（图像 + 视频）
npx flow-api import-cookies [f] # 从 JSON 文件导入 Chrome Cookie
npx flow-api test "<prompt>" # 从 CLI 生成单个图像
npx flow-api serve # 启动 MCP 服务器（stdio）
npx flow-api serve-http # 启动 MCP 服务器（HTTP 传输）
npx flow-api cleanup # 杀死卡住的 Chrome，删除配置文件锁
```
## 配置（`.env`）
```ini
CHROME_PROFILE_DIR=./data/chrome-profile
OUTPUT_DIR=./output
LOCALE=zh
HEADLESS=true
USE_SYSTEM_CHROME=true
FLOW_URL=https://labs.google/fx/tools/flow
GENERATION_TIMEOUT_MS=180000
VIDEO_GENERATION_TIMEOUT_MS=480000
POLL_INTERVAL_MS=2000
ACTION_TIMEOUT_MS=30000
HTTP_PORT=8787
HTTP_AUTH_TOKEN= # 使用以下命令生成：node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```
## 工作原理
1. **首次运行** — `flow_login` 启动有头的 Chrome，用户登录到 Google，会话 Cookie 保存在 `./data/chrome-profile/`。（或 `import-cookies` 将 Cookie 从 JSON 文件注入。）
2. **`generate_image`** — Playwright 打开保存的配置文件，导航到 Flow，单击 *新建项目*，切换到 *图像* 模式（如果需要），选择宽高比，在 Slate.js 编辑器中输入提示，单击 *创建*（`arrow_forward` 图标按钮），轮询 DOM 以获取 `<img>` 标签，其 `src` 匹配 `media.getMediaUrlRedirect?name={uuid}`，然后通过身份验证会话下载每个 UUID。
3. **`generate_video`** — Playwright 导航到 Flow，创建新项目，切换画布到 **视频** 模式（宽高比 + 计数），单击故事板启动芯片（例如“开发故事板”），在聊天中输入提示，等待代理的计划响应（确认），发送“看起来不错。请现在生成视频。”以启动生成，然后轮询画布以获取 `<video>` 元素，并通过相同的 `media.getMediaUrlRedirect` 端点下载每个渲染的 `.mp4`。
4. **结果** — 图像字节保存到 `./output/flow_<jobId>_<uuid>.jpg`，视频字节保存到 `./output/flow_<jobId>_<uuid>.mp4`。
5. **自动清理** — 每个脚本（包括 `status`、`test`、`import-cookies`）都在 `finally` 块中包装其工作，在 `finally` 块中关闭 Playwright，杀死 Chrome 进程，并删除配置文件锁定文件。`cleanup` 子命令存在用于手动恢复，当其他东西杀死了进程并留下了锁定。
## 项目结构
```
flow api/
├── package.json
├── .env.example
├── README.md
├── NOTES.md # 开发日志（决策，错误，模型目录）
├── bin/
│ ├── flow-api.js # CLI 入口
│ ├── _runner.js # withBrowser/withPage 自动清理助手
│ ├── cleanup.js # 杀死 Chrome + 删除配置文件锁
│ └── import-cookies.js # 独立 Cookie 导入
├── src/
│ ├── server.js # MCP 服务器（stdio）
│ ├── http.js # MCP 服务器（HTTP 传输）
│ ├── handler.js # MCP 工具调度
│ ├── browser.js # Playwright + 隐身初始化脚本
│ ├── flow.js # Flow UI 自动化（图像 + 视频）
│ ├── tools/
│ │ └── index.js # MCP 工具定义
│ └── utils/
│ ├── logger.js
│ └── downloader.js # 图像 + 视频 UUID 提取
├── data/
│ ├── chrome-profile/ # 持久 Chrome 配置文件（gitignored）
│ └── cookies-import.json # 最后导入的 Cookie 转储
└── output/ # 生成的图像 + 视频（gitignored）
```
## 安全
- **您的帐户，您的数据** — 使用您自己的 Chrome 配置文件，您的凭证从未离开您的机器
- **无令牌导出** — 会话不被复制、导出或共享
- **验证码感知** — 如果 Google 对会话提出质疑，则干净地停止
- **无并行滥用** — 单个浏览器上下文，一次一个作业
- **视频需要 Pro 帐户** — 图像生成在免费层（每天 50 个积分）上有效，视频需要付费计划
## 故障排除
| 问题 | 修复 |
|---|---|
| `AUTH_REQUIRED` | 运行 `npx flow-api login` |
| `CAPTCHA` | 在 Chrome 中手动打开 Flow，解决挑战，重试 |
| `PROMPT_INPUT_NOT_FOUND` | Flow UI 更改 — 重新运行 headed=true 以检查 |
| `GENERATE_BUTTON_NOT_FOUND` | 与上述相同 |
| `GENERATION_TIMEOUT` | 每日积分可能已用完，或 Google 正在限制。请检查 `flow_status`。 |
| `AGENT_ERROR`（视频） | Flow 服务 / 速率限制。几分钟后重试。 |
| 生成 HTTP 403 | 确保 `.env` 中 `USE_SYSTEM_CHROME=true`。捆绑的 Chromium 触发反机器人。 |
| 浏览器无法启动 | 从 <https://google.com/chrome> 安装 Google Chrome |
| 会话过期 | 重新运行 `npx flow-api login` 或 `npx flow-api import-cookies <file>` |
| 配置文件锁定（SingletonLock） | 运行 `npx flow-api cleanup` |
## 许可证
MIT
