MCPcopy Index your code
hub / github.com/TheSmallHanCat/flow2api

github.com/TheSmallHanCat/flow2api @main

Chat with this repo
repository ↗ · DeepWiki ↗ · + Follow
1,359 symbols 4,628 edges 38 files 635 documented · 47%
What it actually does AI analysis from the code graph — generated when you open this
loading…
README

Flow2API

License Python FastAPI Docker

一个功能完整的 OpenAI 兼容 API 服务，为 Flow 提供统一的接口

✨ 核心特性

  • 🎨 文生图 / 图生图
  • 🎬 文生视频 / 图生视频
  • 🎞️ 首尾帧视频
  • 🔄 AT/ST自动刷新 - AT 过期自动刷新，ST 过期时自动通过浏览器更新（personal 模式）
  • 📊 余额显示 - 实时查询和显示 VideoFX Credits
  • 🚀 负载均衡 - 多 Token 轮询和并发控制
  • 🌐 代理支持 - 支持 HTTP/SOCKS5 代理
  • 📱 Web 管理界面 - 直观的 Token 和配置管理
  • 🎨 图片生成连续对话
  • 🧩 Gemini 官方请求体兼容 - 支持 generateContent / streamGenerateContent、systemInstruction、contents.parts.text/inlineData/fileData
  • ✅ Gemini 官方格式已实测出图 - 已使用真实 Token 验证 /models/{model}:generateContent 可正常返回官方 candidates[].content.parts[].inlineData

🚀 快速开始

前置要求

  • Docker 和 Docker Compose（推荐）

  • 或 Python 3.8+

  • 由于Flow增加了额外的验证码，你可以自行选择使用浏览器打码或第三发打码： 注册YesCaptcha并获取api key，将其填入系统配置页面YesCaptcha API密钥区域

  • YesCaptcha 支持在管理页切换 type：RecaptchaV3TaskProxyless、RecaptchaV3TaskProxylessM1、RecaptchaV3TaskProxylessM1S7、RecaptchaV3TaskProxylessM1S9；当前默认推荐 M1S9，S7/S9 会强制提交 minScore 0.7/0.9。

  • 默认 docker-compose.yml 建议搭配第三方打码（yescaptcha/capmonster/ezcaptcha/capsolver）。 如需 Docker 内有头打码（browser/personal），请使用下方 docker-compose.headed.yml。

  • 自动更新st浏览器拓展：Flow2API-Token-Updater

方式一：Docker 部署（推荐）

标准模式（不使用代理）

# 克隆项目
git clone https://github.com/TheSmallHanCat/flow2api.git
cd flow2api

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

说明：Compose 已默认挂载 ./tmp:/app/tmp。如果把缓存超时设为 0，语义是“不自动过期删除”；若希望容器重建后仍保留缓存文件，也需要保留这个 tmp 挂载。

WARP 模式（使用代理）

# 使用 WARP 代理启动
docker-compose -f docker-compose.warp.yml up -d

# 查看日志
docker-compose -f docker-compose.warp.yml logs -f

Docker 有头打码模式（browser / personal）

适用于你有虚拟化桌面需求、希望在容器里启用有头浏览器打码的场景。
该模式默认启动 Xvfb + Fluxbox 实现容器内部可视化，并设置 ALLOW_DOCKER_HEADED_CAPTCHA=true。
仅开放应用端口，不提供任何远程桌面连接端口。 personal 内置浏览器现在默认按有头模式启动；如需临时切回无头，可额外设置环境变量 PERSONAL_BROWSER_HEADLESS=true。

# 启动有头模式（首次建议带 --build）
docker compose -f docker-compose.headed.yml up -d --build

# 查看日志
docker compose -f docker-compose.headed.yml logs -f
  • API 端口：8000
  • 进入管理后台后，将验证码方式设为 browser 或 personal

方式二：本地部署

# 克隆项目
git clone https://github.com/TheSmallHanCat/flow2api.git
cd flow2api

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 启动服务
python main.py

首次访问

服务启动后,访问管理后台: http://localhost:8000,首次登录后请立即修改密码!

  • 用户名: admin
  • 密码: admin

📈 监控接口

  • GET /health：公开健康检查，返回服务是否存活、活跃 Token 数、即将过期 Token 数、已过期 Token 数、429 禁用数等摘要
  • GET /metrics：Prometheus 指标接口
  • GET /api/tokens：管理接口，返回 at_expires、at_expired、at_expiring_within_1h、ban_reason、consecutive_error_count 等 Token 状态

Prometheus 可直接抓 /metrics。如果部署到 Kubernetes，建议只在集群内抓取，并在 Ingress/Gateway 层单独限制 /metrics 的外部访问。

模型测试页面

访问 http://localhost:8000/test 可打开内置的模型测试页面，支持：

  • 按分类浏览所有可用模型（图片生成、文/图生视频、多图视频、视频放大等）
  • 输入提示词一键测试，流式显示生成进度
  • 图生图 / 图生视频场景支持上传图片
  • 生成完成后直接预览图片或视频

📋 支持的模型

图片生成

模型名称 说明 尺寸
gemini-3.0-pro-image-landscape 图/文生图 横屏
gemini-3.0-pro-image-portrait 图/文生图 竖屏
gemini-3.0-pro-image-square 图/文生图 方图
gemini-3.0-pro-image-four-three 图/文生图 横屏 4:3
gemini-3.0-pro-image-three-four 图/文生图 竖屏 3:4
gemini-3.0-pro-image-landscape-2k 图/文生图(2K) 横屏
gemini-3.0-pro-image-portrait-2k 图/文生图(2K) 竖屏
gemini-3.0-pro-image-square-2k 图/文生图(2K) 方图
gemini-3.0-pro-image-four-three-2k 图/文生图(2K) 横屏 4:3
gemini-3.0-pro-image-three-four-2k 图/文生图(2K) 竖屏 3:4
gemini-3.0-pro-image-landscape-4k 图/文生图(4K) 横屏
gemini-3.0-pro-image-portrait-4k 图/文生图(4K) 竖屏
gemini-3.0-pro-image-square-4k 图/文生图(4K) 方图
gemini-3.0-pro-image-four-three-4k 图/文生图(4K) 横屏 4:3
gemini-3.0-pro-image-three-four-4k 图/文生图(4K) 竖屏 3:4
imagen-4.0-generate-preview-landscape 图/文生图 横屏
imagen-4.0-generate-preview-portrait 图/文生图 竖屏
gemini-3.1-flash-image-landscape 图/文生图 横屏
gemini-3.1-flash-image-portrait 图/文生图 竖屏
gemini-3.1-flash-image-square 图/文生图 方图
gemini-3.1-flash-image-four-three 图/文生图 横屏 4:3
gemini-3.1-flash-image-three-four 图/文生图 竖屏 3:4
gemini-3.1-flash-image-landscape-2k 图/文生图(2K) 横屏
gemini-3.1-flash-image-portrait-2k 图/文生图(2K) 竖屏
gemini-3.1-flash-image-square-2k 图/文生图(2K) 方图
gemini-3.1-flash-image-four-three-2k 图/文生图(2K) 横屏 4:3
gemini-3.1-flash-image-three-four-2k 图/文生图(2K) 竖屏 3:4
gemini-3.1-flash-image-landscape-4k 图/文生图(4K) 横屏
gemini-3.1-flash-image-portrait-4k 图/文生图(4K) 竖屏
gemini-3.1-flash-image-square-4k 图/文生图(4K) 方图
gemini-3.1-flash-image-four-three-4k 图/文生图(4K) 横屏 4:3
gemini-3.1-flash-image-three-four-4k 图/文生图(4K) 竖屏 3:4

视频生成

文生视频 (T2V - Text to Video)

⚠️ 不支持上传图片

模型名称 说明 尺寸
veo_3_1_t2v_fast_portrait 文生视频 竖屏
veo_3_1_t2v_fast_landscape 文生视频 横屏
veo_3_1_t2v_fast_portrait_ultra 文生视频 竖屏
veo_3_1_t2v_fast_ultra 文生视频 横屏
veo_3_1_t2v_fast_portrait_ultra_relaxed 文生视频 竖屏
veo_3_1_t2v_fast_ultra_relaxed 文生视频 横屏
veo_3_1_t2v_portrait 文生视频 竖屏
veo_3_1_t2v_landscape 文生视频 横屏
veo_3_1_t2v_landscape_4s 文生视频 4秒 横屏
veo_3_1_t2v_portrait_4s 文生视频 4秒 竖屏
veo_3_1_t2v_landscape_6s 文生视频 6秒 横屏
veo_3_1_t2v_portrait_6s 文生视频 6秒 竖屏
veo_3_1_t2v_fast_landscape_4s 文生视频 Fast 4秒 横屏
veo_3_1_t2v_fast_portrait_4s 文生视频 Fast 4秒 竖屏
veo_3_1_t2v_fast_landscape_6s 文生视频 Fast 6秒 横屏
veo_3_1_t2v_fast_portrait_6s 文生视频 Fast 6秒 竖屏
veo_3_1_t2v_lite_portrait 文生视频 Lite 竖屏
veo_3_1_t2v_lite_landscape 文生视频 Lite 横屏
veo_3_1_t2v_lite_4s_portrait 文生视频 Lite 4秒 竖屏
veo_3_1_t2v_lite_4s_landscape 文生视频 Lite 4秒 横屏
veo_3_1_t2v_lite_6s_portrait 文生视频 Lite 6秒 竖屏
veo_3_1_t2v_lite_6s_landscape 文生视频 Lite 6秒 横屏

首尾帧模型 (I2V - Image to Video)

📸 支持1-2张图片：1张作为首帧，2张作为首尾帧

💡 自动适配：系统会根据图片数量自动选择对应的 model_key - 单帧模式（1张图）：使用首帧生成视频 - 双帧模式（2张图）：使用首帧+尾帧生成过渡视频 - veo_3_1_i2v_lite_* 仅支持 1 张 首帧图片 - veo_3_1_interpolation_lite_* 仅支持 2 张 首尾帧图片

模型名称 说明 尺寸
veo_3_1_i2v_s_fast_portrait_fl 图生视频 竖屏
veo_3_1_i2v_s_fast_fl 图生视频 横屏
veo_3_1_i2v_s_fast_portrait_ultra_fl 图生视频 竖屏
veo_3_1_i2v_s_fast_ultra_fl 图生视频 横屏
veo_3_1_i2v_s_fast_portrait_ultra_relaxed 图生视频 竖屏
veo_3_1_i2v_s_fast_ultra_relaxed 图生视频 横屏
veo_3_1_i2v_s_portrait 图生视频 竖屏
veo_3_1_i2v_s_landscape 图生视频 横屏
veo_3_1_i2v_s_landscape_4s 图生视频 4秒 横屏
veo_3_1_i2v_s_portrait_4s 图生视频 4秒 竖屏
veo_3_1_i2v_s_landscape_6s 图生视频 6秒 横屏
veo_3_1_i2v_s_portrait_6s 图生视频 6秒 竖屏
veo_3_1_i2v_s_fast_landscape_4s_fl 图生视频 Fast 4秒 横屏
veo_3_1_i2v_s_fast_portrait_4s_fl 图生视频 Fast 4秒 竖屏
veo_3_1_i2v_s_fast_landscape_6s_fl 图生视频 Fast 6秒 横屏
veo_3_1_i2v_s_fast_portrait_6s_fl 图生视频 Fast 6秒 竖屏
veo_3_1_i2v_lite_portrait 图生视频 Lite（仅首帧） 竖屏
veo_3_1_i2v_lite_landscape 图生视频 Lite（仅首帧） 横屏
veo_3_1_i2v_lite_4s_portrait 图生视频 Lite 4秒（仅首帧） 竖屏
veo_3_1_i2v_lite_4s_landscape 图生视频 Lite 4秒（仅首帧） 横屏
veo_3_1_i2v_lite_6s_portrait 图生视频 Lite 6秒（仅首帧） 竖屏
veo_3_1_i2v_lite_6s_landscape 图生视频 Lite 6秒（仅首帧） 横屏
veo_3_1_interpolation_lite_portrait 图生视频 Lite（首尾帧过渡） 竖屏
veo_3_1_interpolation_lite_landscape 图生视频 Lite（首尾帧过渡） 横屏
veo_3_1_interpolation_lite_4s_portrait 图生视频 Lite 4秒（首尾帧过渡） 竖屏
veo_3_1_interpolation_lite_4s_landscape 图生视频 Lite 4秒（首尾帧过渡） 横屏
veo_3_1_interpolation_lite_6s_portrait 图生视频 Lite 6秒（首尾帧过渡） 竖屏
veo_3_1_interpolation_lite_6s_landscape 图生视频 Lite 6秒（首尾帧过渡） 横屏

多图生成 (R2V - Reference Images to Video)

🖼️ 支持多张图片

2026-03-06 更新

  • 已同步上游新版 R2V 视频请求体
  • textInput 已切换为 structuredPrompt.parts
  • 顶层新增 mediaGenerationContext.batchId
  • 顶层新增 useV2ModelConfig: true
  • 横屏 / 竖屏 R2V 模型共用同一套新版请求体
  • 横屏 R2V 的上游 videoModelKey 已切换为 *_landscape 形式
  • 根据当前上游协议，referenceImages 当前最多传 3 张
模型名称 说明 尺寸
veo_3_1_r2v_fast_portrait 图生视频 竖屏
veo_3_1_r2v_fast_landscape 图生视频 横屏
veo_3_1_r2v_fast_portrait_ultra 图生视频 竖屏
veo_3_1_r2v_fast_landscape_ultra 图生视频 横屏
veo_3_1_r2v_fast_portrait_ultra_relaxed 图生视频 竖屏
veo_3_1_r2v_fast_landscape_ultra_relaxed 图生视频 横屏

视频放大模型 (Upsample)

这些模型不是直接调用上游 upsampler key，而是先用对应的 Veo 3.1 普通模型生成视频，再提交 1080P/4K 放大请求。

模型名称 说明 输出
veo_3_1_t2v_landscape_4k 文生视频放大 4K
veo_3_1_t2v_portrait_4k 文生视频放大 4K
veo_3_1_t2v_landscape_1080p 文生视频放大 1080P
veo_3_1_t2v_portrait_1080p 文生视频放大 1080P
veo_3_1_t2v_landscape_4s_4k 文生视频 4秒放大 4K
veo_3_1_t2v_portrait_4s_4k 文生视频 4秒放大 4K
veo_3_1_t2v_landscape_4s_1080p 文生视频 4秒放大 1080P
veo_3_1_t2v_portrait_4s_1080p 文生视频 4秒放大 1080P
veo_3_1_t2v_landscape_6s_4k 文生视频 6秒放大 4K
veo_3_1_t2v_portrait_6s_4k 文生视频 6秒放大 4K
veo_3_1_t2v_landscape_6s_1080p 文生视频 6秒放大 1080P
veo_3_1_t2v_portrait_6s_1080p 文生视频 6秒放大 1080P
veo_3_1_t2v_fast_portrait_4k 文生视频放大 4K
veo_3_1_t2v_fast_4k 文生视频放大 4K
veo_3_1_t2v_fast_portrait_ultra_4k 文生视频放大 4K
veo_3_1_t2v_fast_ultra_4k 文生视频放大 4K
veo_3_1_t2v_fast_portrait_1080p 文生视频放大 1080P
veo_3_1_t2v_fast_1080p 文生视频放大 1080P
veo_3_1_t2v_fast_portrait_ultra_1080p 文生视频放大 1080P
veo_3_1_t2v_fast_ultra_1080p 文生视频放大 1080P
veo_3_1_i2v_s_fast_portrait_ultra_fl_4k 图生视频放大 4K
veo_3_1_i2v_s_fast_ultra_fl_4k 图生视频放大 4K
veo_3_1_i2v_s_fast_portrait_ultra_fl_1080p 图生视频放大 1080P
veo_3_1_i2v_s_fast_ultra_fl_1080p 图生视频放大 1080P
veo_3_1_i2v_s_landscape_4k 图生视频放大 4K
veo_3_1_i2v_s_portrait_4k 图生视频放大 4K
veo_3_1_i2v_s_landscape_1080p 图生视频放大 1080P
veo_3_1_i2v_s_portrait_1080p 图生视频放大 1080P
veo_3_1_i2v_s_landscape_4s_4k 图生视频 4秒放大 4K
veo_3_1_i2v_s_portrait_4s_4k 图生视频 4秒放大 4K
veo_3_1_i2v_s_landscape_4s_1080p 图生视频 4秒放大 1080P
veo_3_1_i2v_s_portrait_4s_1080p 图生视频 4秒放大 1080P
veo_3_1_i2v_s_landscape_6s_4k 图生视频 6秒放大 4K
veo_3_1_i2v_s_portrait_6s_4k 图生视频 6秒放大 4K
veo_3_1_i2v_s_landscape_6s_1080p 图生视频 6秒放大 1080P
veo_3_1_i2v_s_portrait_6s_1080p 图生视频 6秒放大 1080P
veo_3_1_r2v_fast_portrait_ultra_4k 多图视频放大 4K
veo_3_1_r2v_fast_landscape_ultra_4k 多图视频放大 4K
veo_3_1_r2v_fast_portrait_ultra_1080p 多图视频放大 1080P
veo_3_1_r2v_fast_landscape_ultra_1080p 多图视频放大 1080P

📡 API 使用示例（需要使用流式）

除了下方 OpenAI-compatible 示例，服务也支持 Gemini 官方格式： - POST /v1beta/models/{model}:generateContent - POST /models/{model}:generateContent - POST /v1beta/models/{model}:streamGenerateContent - POST /models/{model}:streamGenerateContent

Gemini 官方格式支持以下认证方式： - Authorization: Bearer <api_key> - x-goog-api-key: <api_key> - ?key=<api_key>

Gemini 官方图片请求体已兼容： - systemInstruction - contents[].parts[].text - contents[].parts[].inlineData - contents[].parts[].fileData.fileUri - generationConfig.responseModalities - generationConfig.imageConfig.aspectRatio - generationConfig.imageConfig.imageSize

Gemini 官方 generateContent（文生图）

已使用真实 Token 实测通过。 如需流式返回，可将路径替换为 :streamGenerateContent?alt=sse。

curl -X POST "http://localhost:8000/models/gemini-3.1-flash-image:generateContent" \
  -H "x-goog-api-key: han1234" \
  -H "Content-Type: application/json" \
  -d '{
    "systemInstruction": {
      "parts": [
        {
          "text": "Return an image only."
        }
      ]
    },
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "一颗放在木桌上的红苹果，棚拍光线，极简背景"
          }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }'

文生图

curl -X POST "http://localhost:8000/v1/chat/completions" \
  -H "Authorization: Bearer han1234" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-landscape",
    "messages": [
      {
        "role": "user",
        "content": "一只可爱的猫咪在花园里玩耍"
      }
    ],
    "stream": true
  }'

图生图

curl -X POST "http://localhost:8000/v1/chat/completions" \
  -H "Authorization: Bearer han1234" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-landscape",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "将这张图片变成水彩画风格"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/jpeg;base64,<base64_encoded_image>"
            }
          }
        ]
      }
    ],
    "stream": true
  }'

文生视频

```bash curl -X POST "http://localhost:8000/v1/chat/completions" \ -H "Authorization: Bearer han1234" \ -H "Content-Type: application/json" \ -d '{ "model": "veo_3_1_t2v_fast_landscape", "messages": [

Core symbols most depended-on inside this repo

log_warning
called by 280
src/core/logger.py
log_info
called by 278
src/core/logger.py
log_error
called by 103
src/core/logger.py
_create_stream_chunk
called by 60
src/services/generation_handler.py
clear
called by 56
src/core/monitoring.py
_connect
called by 51
src/core/database.py
set
called by 47
src/core/monitoring.py
add_alias
called by 46
src/services/generation_handler.py

Shape

Method 925
Function 289
Class 80
Route 65

Languages

Python99%
TypeScript1%

Modules by API surface

src/services/browser_captcha_personal.py389 symbols
src/api/admin.py147 symbols
src/services/flow_client.py114 symbols
src/core/config.py98 symbols
src/services/browser_captcha.py90 symbols
src/core/database.py61 symbols
src/api/routes.py56 symbols
src/services/token_manager.py51 symbols
tests/test_browser_captcha_personal.py40 symbols
src/services/generation_handler.py32 symbols
tests/test_veo_lite_support.py30 symbols
src/core/models.py23 symbols

For agents

$ claude mcp add flow2api \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact