"我们不生产模型，我们只是思想的搬运工...的 API 搬运工。" —— 一位不愿意透露姓名的开发者
欢迎来到 flowith-2api 的世界！这是一个将 flowith.net 网页聊天功能转换为兼容 OpenAI 格式 API 的开源项目。
这不仅仅是一个工具，它是一座桥梁，连接了便捷的网页体验与强大的编程能力。无论你是编程专家，还是刚刚踏入代码世界的新手，这里都有你需要的解决方案。
仓库链接: https://github.com/lzA6/flowith-2api
- ✨ 项目缘起与核心思想
- 🎯 主要功能与现阶段成果
- 👍 优点 vs 👎 缺点
- 🧑💻 适用场景与目标用户
- 🛠️ "懒人"一键安装与使用教程
- 🏛️ 架构师蓝图：技术原理深度剖析
- 🗺️ 项目完整文件结构
- 🧭 未来规划：发展规划与技术路径
- ❤️ 开源协议
- 🙏 致谢
"道生一，一生二，二生三，三生万物。网页生交互，交互生数据，我们生 API。"
flowith.net 是一个优秀的 AI 聊天网站，但它只提供了 Web UI，而我们想要一个可以在自己的代码、脚本和自动化流程中随时调用的 API。
核心原理：
flowith-2api 的核心思想是 "会话模拟" (Session Simulation)。
想象一下你访问 flowith.net 的过程：
- 打开网站，通过 Cloudflare 验证
- 与后端服务建立连接，获取身份凭证
- 发送消息时携带凭证进行通信
flowith-2api 在服务器上完美复刻了上述行为：
cloudscraper库: 我们的"隐身斗篷"，能够智能处理 Cloudflare 的 JavaScript 挑战，避免被403 Forbidden拒绝- 会话预授权 (
_pre_authorize_session): 我们的"社交礼仪"，在正式聊天前先与后端进行"握手"，获取有效会话状态 - FastAPI 框架: 我们的"翻译中枢"，将 OpenAI 格式的请求转换为
flowith.net能理解的格式，并实时返回流式响应
架构流程图：
┌─────────────────┐ OpenAI Format ┌──────────────────┐ Flowith Format ┌──────────────────┐
│ │ ┌───────────────► │ │ ┌───────────────► │ │
│ Your Client │ │ flowith-2api │ │ flowith.net │
│ │ ◄───────────────┐ │ │ ◄───────────────┐ │ │
└─────────────────┘ Stream Response └──────────────────┘ Stream Response └──────────────────┘
一句话总结： 我们用代码构建了一个"看不见的浏览器"，模拟用户的所有网页行为，并将这个过程封装成标准的 OpenAI API 接口。
我们已经完成了从 0 到 1 的关键一步！
- ✅ 核心 API 转换: 将
flowith.net聊天转换为 OpenAIv1/chat/completions兼容接口 - ✅ 流式响应 (Streaming): 完美支持打字机效果，实时返回 AI 响应
- ✅ Cloudflare 绕过: 内置
cloudscraper，自动处理 Cloudflare 防护 - ✅ 会话保持与预授权: 智能会话管理，避免
429/401错误 - ✅ 模型列表: 提供
/v1/models接口，动态获取支持的模型 - ✅ Docker 一键部署: 提供完整 Docker 支持，部署简单快捷
- ✅ 安全认证: 支持
API_MASTER_KEY，保护 API 安全
- 便捷性 ✨: 无需复杂逆向工程，轻松集成 Flowith 模型到你的应用
- 零成本 💰: 利用
flowith.net免费额度实现 AI API 自由 - 标准化 📏: 输出与 OpenAI 完全一致，兼容所有 OpenAI 生态工具
- 高性能 ⚡: 基于 FastAPI 和 Uvicorn，具备高并发处理能力
- 易于部署 📦: Docker 容器化，一条命令完成部署
- 依赖性 🔗: 强依赖
flowith.net的实现，对方变更可能导致失效 - 稳定性风险 😟: 非官方支持，稳定性无法与付费 API 相比
- 功能局限 🚧: 目前仅支持核心聊天功能，缺少高级特性
- 单会话模式 👤: 所有请求共享同一会话，高并发下可能存在风险
"给需要的人一把锤子，他能敲开整个世界。"
- AI 应用开发者 & 爱好者: 开发聊天机器人、内容生成工具等 AI 应用，希望降低 API 成本
- 学习与研究者: 学习 Python API 开发、网站交互、Docker 部署的实战案例
- 自动化与极客玩家: 将 AI 能力集成到自动化脚本、智能家居、个人助手中
- 所有希望高效利用免费资源的用户 😉
"Talk is cheap. Show me the code... and the command."
我们准备了基于 Docker 的"懒人包"，只需几步即可拥有专属 AI API！
- 安装
Docker和Docker Compose的机器 - 安装
Git
git clone https://github.com/lzA6/flowith-2api.git
cd flowith-2api复制环境变量模板并编辑：
cp .env.example .env
nano .env # 或使用你喜欢的编辑器修改关键配置：
# ====================================================================
# flowith-2api 配置文件
# ====================================================================
# --- 核心安全配置 (必须修改) ---
# 将此默认密钥修改为复杂的自定义密码
API_MASTER_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
# --- 部署配置 (可选) ---
# API 服务对外暴露的端口
NGINX_PORT=8088
# --- Supabase 配置 (通常无需修改) ---
SUPABASE_URL=https://aibdxsebwhalbnugsqel-all.supabase.co
SUPABASE_ANON_KEY=sb_publishable_qPCinc8LE8ChpdT7Pf79tQ_eryz5udrdocker-compose up -d这条命令会：
- 根据
Dockerfile构建应用镜像 - 启动所有服务（
app和nginx） - 在后台运行服务
服务运行在 http://你的服务器IP:端口，使用 curl 测试：
curl -X POST http://127.0.0.1:8088/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-d '{
"model": "flowith-gpt-4.1",
"messages": [
{"role": "user", "content": "你好，你是谁？"}
],
"stream": true
}'如果一切正常，你将看到 AI 的流式回复！
Python 代码示例:
import openai
# 配置 OpenAI 客户端
client = openai.OpenAI(
api_key="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx", # 你的 API_MASTER_KEY
base_url="http://127.0.0.1:8088/v1" # 你的服务地址
)
# 发起流式聊天请求
stream = client.chat.completions.create(
model="flowith-gpt-4.1",
messages=[{"role": "user", "content": "用 Python 写一个 Hello World"}],
stream=True,
)
# 打印返回内容
for chunk in stream:
content = chunk.choices[0].delta.content or ""
print(content, end="", flush=True)
print()"庖丁解牛，所见非牛，乃神理也。"
| 技术/库 | 作用 | 难度 | 重要性 | 替代方案 |
|---|---|---|---|---|
| FastAPI | 构建高性能异步 API 框架 | ⭐⭐ | ⭐⭐⭐⭐⭐ | Flask, Django |
| Docker | 应用容器化部署 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | Podman |
| Nginx | 反向代理和负载均衡 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | Caddy, Traefik |
| cloudscraper | 绕过 Cloudflare 防护 | ⭐⭐ | ⭐⭐⭐⭐⭐ | Playwright, Selenium |
| pydantic | 数据校验与配置管理 | ⭐⭐ | ⭐⭐⭐⭐ | dataclasses |
| uvicorn | ASGI 服务器 | ⭐ | ⭐⭐⭐⭐⭐ | Hypercorn |
┌─────────────────────────────────────────────────────────────┐
│ Client Applications │
│ (OpenAI SDK, curl, Postman, custom apps) │
└───────────────────────┬─────────────────────────────────────┘
│ HTTP Requests (OpenAI Format)
▼
┌─────────────────────────────────────────────────────────────┐
│ Nginx Reverse Proxy │
│ - Port forwarding (${NGINX_PORT} → 80) │
│ - Load balancing (ip_hash for session consistency) │
│ - Proxy buffering off (for streaming) │
└───────────────────────┬─────────────────────────────────────┘
│ Internal Requests
▼
┌─────────────────────────────────────────────────────────────┐
│ FastAPI Application │
│ - /v1/chat/completions (main endpoint) │
│ - /v1/models (model list) │
│ - API key authentication │
└───────────────────────┬─────────────────────────────────────┘
│ Provider Abstraction
▼
┌─────────────────────────────────────────────────────────────┐
│ FlowithProvider │
│ - cloudscraper session management │
│ - _pre_authorize_session() for auth │
│ - chat_completion() for core logic │
└───────────────────────┬─────────────────────────────────────┘
│ HTTP Requests (Flowith Format)
▼
┌─────────────────────────────────────────────────────────────┐
│ flowith.net │
│ - Cloudflare protection │
│ - Supabase backend │
│ - AI chat endpoints │
└─────────────────────────────────────────────────────────────┘
定义了两个服务：
nginx: 端口映射和反向代理app: 应用构建和运行环境
ip_hash: 确保同一客户端 IP 的请求路由到同一应用实例proxy_buffering off: 关闭代理缓冲，实现真正的流式传输
- 生命周期管理 (
lifespan) - API 密钥验证 (
verify_api_key) - 路由定义 (
/v1/chat/completions)
会话预授权流程：
def _pre_authorize_session(self) -> str:
# 1. 构造 Supabase URL
url = f"{self.supabase_url}/rest/v1/rpc/get_user_balance"
# 2. 使用 cloudscraper 发送请求
response = self.scraper.get(url)
# 3. 获取并保存会话 Cookies
return "Session authorized"聊天完成流程：
async def chat_completion(self, request: ChatCompletionRequest):
# 1. 预授权会话
await self._pre_authorize_session()
# 2. 准备请求数据
data = self._prepare_chat_data(request)
# 3. 发送流式请求
response = self.scraper.post(chat_url, json=data, stream=True)
# 4. 转换和返回流式响应
async for line in response.iter_lines():
yield self._format_to_openai_sse(line)flowith-2api/
├── 📄 .dockerignore # Docker 忽略文件
├── 📄 .env # 环境配置文件（由用户创建）
├── 📄 .env.example # 环境配置模板
├── 📄 Dockerfile # Docker 镜像构建文件
├── 📄 docker-compose.yml # Docker 服务编排
├── 📄 main.py # FastAPI 应用入口
├── 📄 nginx.conf # Nginx 配置
├── 📄 requirements.txt # Python 依赖列表
└── 📁 app/ # 应用核心代码
├── 📁 core/ # 核心配置模块
│ ├── 📄 __init__.py
│ └── 📄 config.py # Pydantic 配置模型
├── 📁 providers/ # API 提供者模块
│ ├── 📄 __init__.py
│ ├── 📄 base_provider.py # 提供者抽象基类
│ └── 📄 flowith_provider.py # Flowith 具体实现
└── 📁 utils/ # 工具函数模块
└── 📄 sse_utils.py # SSE 格式化工具
"我们的征途是星辰大海。"
1. 更强的并发支持
- 问题: 当前所有请求共享单一
cloudscraper实例 - 解决方案: 实现会话池机制
class SessionPool:
def __init__(self, max_size=10):
self.sessions = {}
self.max_size = max_size
def get_session(self, key):
if key not in self.sessions:
if len(self.sessions) >= self.max_size:
self._evict_oldest()
self.sessions[key] = cloudscraper.create_scraper()
return self.sessions[key]- 难度: ⭐⭐⭐
2. 自动重试与会话刷新
- 问题: 会话过期导致请求失败
- 解决方案: 实现智能重试机制
max_retries = 2
for attempt in range(max_retries):
try:
return await self._make_request(data)
except (HTTPError, ConnectionError) as e:
if attempt < max_retries - 1:
await self._refresh_session()
continue
raise- 难度: ⭐⭐
1. 多账号/多 Key 支持
- 引入简单数据库存储多个 API Key
- 为每个 Key 维护独立会话
- 难度: ⭐⭐⭐⭐
2. 插件化提供者系统
- 基于
base_provider.py的抽象接口 - 动态加载不同网站的 Provider
- 难度: ⭐⭐⭐⭐
3. 简易 Web UI
- 集成聊天界面供非开发者使用
- API Key 管理功能
- 难度: ⭐⭐⭐⭐
- 精细化错误处理: 区分客户端、服务端和网络错误
- 增强日志系统: 加入请求 ID 追踪
- 配置热重载: 支持运行时配置更新
本项目采用 Apache 2.0 开源许可证。
这意味着：
- 你可以自由使用、修改、分发代码，包括商业用途
- 需要保留原始版权和许可声明
- 修改代码需要明确标识
简单来说：放心使用，但请注明出处。我们相信开放与共享是技术进步的基石。
"独行快，众行远。"
感谢 flowith.net 提供优秀的免费服务。
感谢 FastAPI、Docker、cloudscraper 等开源项目的作者。
特别感谢每一位使用、测试和贡献这个项目的开发者。
这个项目证明了只要有好奇心和动手能力，我们就能用代码为自己创造便利，解决问题。
不要害怕犯错，不要畏惧未知。如果你有任何想法、建议或发现了 Bug，请提交 Issue 或 Pull Request。
愿代码的乐趣与你同在，愿开源的精神永不熄灭！
Happy Hacking! 💻✨