doubao2api

一个基于本地浏览器运行时的字节跳动豆包（Doubao）网页端 OpenAI 兼容 API 桥接服务。

---

💡 项目由来与致谢

本项目最初灵感来源于开源项目 wangchuxiaoji-oss/doubao2api。原作者探索出了一套非常出色的豆包接口封装思路，让很多人能够在第三方客户端中使用豆包，在此对原作者的开源奉献表示由衷的感谢！

随着豆包网页端架构和前端风控算法的持续更新，旧有的纯 HTTP 请求接口、前端签名和会话校验经常失效，维护纯逆向协议的成本极高。为了提供一个长期稳定的调用方案，本项目转变了实现思路：借助本地浏览器（Playwright 控制 Chromium/Chrome/Edge）作为运行环境与会话载体，在其之上对外提供标准的 OpenAI 兼容 API。

虽然这种方式相比纯 HTTP 略微增加了本地内存开销，但彻底摆脱了频繁逆向前端算法的困扰，稳定性和功能完整度都有了实质保障。

---

🛠️ 当前已实现的功能

• OpenAI 兼容接口：
  • /v1/chat/completions：支持流式（Streaming）与非流式对话，支持多轮上下文。
  • /v1/models：提供可用模型列表。
  • /v1/images/generations & /v1/images/edits：文生图与图生图（支持参考图片 URL、Base64 或 Form 表单上传）。
  • /v1/video/generations：文生视频与图生视频（支持参考图片动效生成）。
  • /v1/files 与 /v1/images/upload：文件及图片上传接口。
• 三种对话模式：
  • 常规模式（doubao）：响应速度快，适合日常翻译和简短问答。
  • 思考模式（doubao-think）：附带完整的思维链（Reasoning Content）输出。
  • 专家模式（doubao-expert）：深度推理模式，内置额度耗尽自动降级至思考模式的机制。
• 多模态与文档理解：
  • 支持传入图片进行图文对话。
  • 支持上传 PDF、TXT、Markdown、代码文件等多种文档并进行问答总结。
• 即用即焚（无痕会话）：
  • 默认开启（DOUBAO_AUTO_DELETE_CONV=true）。API 响应完成后会自动清理网页端历史记录，避免大量接口调用污染你的豆包网页侧边栏。
• 并发平滑调度：
  • 针对“沉浸式翻译”等插件高频并发请求的特点，内置请求平滑调度锁（默认间隔 200ms），降低触发频率限制的概率。
• 模型智能别名与零报错回退：
  • 内置常见第三方模型别名映射（gpt-4o、gpt-3.5-turbo、deepseek-chat、deepseek-reasoner、dall-e-3 等），第三方客户端导入后无需修改模型名即可直接请求。
  • 遇到未知模型名称时，自动平滑回退至默认模型（doubao-2.1-turbo），彻底消除 400 阻断。
• SSE 思考长连接保活心跳：
  • 深度思考（doubao-think）深度推理期间，每 5 秒自动发送规范允许的 : keep-alive\n\n 心跳注释帧，彻底避免 Cloudflare/Nginx 反向代理或客户端读取超时导致的连接意外断开。
• 多账号池与额度自动轮换（应对每日额度上限）：
  • 支持在控制台导入多个豆包账号 Cookie，集中管理。
  • 零内存热切换：单浏览器实例直接热更新 Cookie，秒级切换，无额外内存开销。
  • 智能故障转移（Failover）：当检测到当前账号视频或对话“今日生成次数已达上限/额度已用尽”时，后台自动标记该账号并无缝切换至下一个可用账号自动重试，对上层调用完全透明。
  • 一键全量巡检与重命名：控制台提供一键健康体检，秒级排查失效 Cookie；支持在线编辑账号备注名称。
• 高频并发与人机验证三级容灾体系（应对大流量风控）：
  • 第一道防线（本地自动求解）：当触发字节 SecSDK 滑块验证码时，内置的自动化求解器通过边缘差分算法计算缺口坐标，并使用拟人化非线性贝塞尔轨迹（加速冲刺、减速逼近、微小过冲与物理抖动）驱动鼠标模拟拖拽，实现 100% 本地无人值守过验证。
  • 第二道防线（多账号熔断逃逸）：若自动求解未通过，系统不会向客户端报错，而是立即将当前账号标记为 待验证 (Captcha)，并秒级热切换至账号池中的下一个健康账号自动重试，API 调用方完全无感知。
  • 第三道防线（桌面置顶与秒级自愈）：仅在所有账号均被风控时触发，自动将浏览器切换为桌面可见窗口并强制置顶；后台看门狗每 2 秒检测一次 DOM，人工滑过验证码后无需重启服务，立刻自动恢复。
• 可视化管理面板与多媒体画廊（Admin Dashboard）：
  • 本地提供 Web 控制台（http://127.0.0.1:9090/admin），支持查看实时服务状态、请求日志、多账号池管理、扫码登录、常见客户端一键配置卡片以及最近生成的图片/视频画廊。
• Windows 本地友好：
  • 提供完整的一键启动、环境安装、日常更新、故障排查与无黑窗静默启动批处理/脚本，普通用户无需手动配置复杂环境。

---

🚀 快速上手（Windows 推荐）

如果你使用的是 Windows 10/11，推荐直接使用内置的一键脚本：

1. 下载项目：
   • 点击 GitHub 页面绿色的 Code -> Download ZIP 下载源码并解压到本地（或者使用 git clone）。
2. 一键启动：
   • 双击运行根目录下的 launcher.bat（推荐，统一便捷管理中心）。
   • 你也可以直接双击 start_server.bat（前台带日志）或 run_silent.vbs（后台静默运行）。
   • 首次运行时，脚本会自动调用 install.bat 为你创建虚拟环境 .venv、安装 Python 依赖并下载 Playwright 浏览器内核。
   • 启动完成后，会在你的默认浏览器中自动打开管理控制台：http://127.0.0.1:9090/admin。
3. 扫码登录：
   • 启动时会弹出一个豆包浏览器窗口，使用手机【豆包 App】扫码登录即可。
   • 也可以在控制台点击“导入 Cookie”，将你在常规浏览器中已登录的豆包 Cookie 粘贴进去。
   • 控制台状态显示为绿色的 已登录 后，服务即可正常接受 API 调用。

---

🧰 Windows 运维与启动说明

根目录下提供了多个开箱即用的批处理脚本，推荐优先使用 launcher.bat：

脚本文件	说明	适用场景
launcher.bat	统一管理中心 (推荐)	聚合控制台。实时查看服务运行状态、开机自启状态，一键前台/后台启动、停止服务、生成桌面图标、设置开机自启、故障修复与更新。
start_server.bat	前台启动	日常双击启动服务，自动激活虚拟环境、检测端口并自动打开管理页面（保留黑框显示实时日志）。
run_silent.vbs	静默后台启动	双击后直接在后台静默运行，桌面上不保留任何黑框窗口，服务就绪后自动弹出管理网页。
install.bat	环境初装	建立 Python 虚拟环境、配置清华镜像源加速并安装依赖与浏览器驱动。
repair.bat	故障自愈	当遇到浏览器窗口打不开、端口被占用等异常时运行，可一键清理残留死锁与僵尸进程。
update.bat	一键升级	自动通过 Git 拉取最新代码并同步更新依赖。

---

🔌 常用客户端配置指南

服务启动后，本地服务地址为 http://127.0.0.1:9090/v1。你可以把它接入各类支持自定义 OpenAI 接口的软件：

1. 沉浸式翻译（Immersive Translate）

• 翻译服务：选择 OpenAI
• 接口地址 (Base URL)：http://127.0.0.1:9090/v1（注意末尾带有 /v1）
• API Key：随意填写（未配置环境变量密码时，填任意非空字符串如 sk-doubao 即可）
• 自定义模型：doubao

2. Cherry Studio / NextChat / Chatbox

• 模型提供商：OpenAI
• API 地址 / Host：http://127.0.0.1:9090/v1
• API Key：随意填写（若配置了 DOUBAO_API_KEY 则填写对应的 Key）
• 模型名称：
  • doubao：快速对话（默认）
  • doubao-think：思考模式（输出思维链）
  • doubao-expert：专家模式（深度推理）
  • doubao-image：文生图

3. 图生图与图生视频调用示例

• 图生图（OpenAI 标准 /v1/images/edits 端点）：

  # 支持 Form 表单上传本地图片文件
  curl http://127.0.0.1:9090/v1/images/edits \
    -F "image=@photo.png" \
    -F "prompt=将图片修改为赛博朋克风格"

  或者通过 JSON 直接传入图片远程 URL / Base64：

  POST /v1/images/edits
  {
    "prompt": "将图片修改为水彩画风格",
    "image": "https://example.com/cat.png"
  }

• 图生视频（/v1/video/generations 端点）：

  POST /v1/video/generations
  {
    "prompt": "让画面动起来，微风吹拂树叶，镜头缓慢拉近",
    "image": "https://example.com/forest.png",
    "ratio": "16:9"
  }

4. 多账号池管理与额度自动切换

豆包对单个账号的每日视频生成次数和高阶功能有配额上限。本项目内置多账号池（Account Pool）：

• 进入控制台：打开 http://127.0.0.1:9090/admin，切换到顶部的 「账号池管理」 标签页。
• 添加账号：
  • 可以直接点击 「将当前登录存为账号」 将本地已登录的会话保存进账号池。
  • 也可以点击 「添加账号」，粘贴其他豆包账号的 Cookie（JSON 数组格式或 key=val; 字符串格式均支持）。
• 调度策略：
  • 故障转移模式（默认 failover）：优先使用当前账号，当检测到“今日生成次数已达上限”或“额度已用尽”提示时，后台自动将当前账号标记为额度耗尽，并无缝切换至下一个可用账号自动重试，API 调用方完全无感知。
  • 轮询模式（round_robin）：轮流使用可用账号，均匀分摊额度消耗。
• 额度恢复：次日 00:00 自动重置所有账号的额度耗尽标记，也可以在控制台随时手动点击“重置额度标记”。

---

⚙️ 环境变量配置

如果需要自定义服务行为，可以在根目录创建 .env 文件或在系统环境变量中设置：

环境变量	默认值	说明
DOUBAO_PORT	9090	本地服务监听端口
DOUBAO_HOST	0.0.0.0	监听地址。注意：未设置 API Key 时，为防公网裸奔会自动降级为 127.0.0.1
DOUBAO_API_KEY	(空)	访问密钥。仅支持 HTTP Header（Authorization: Bearer <key>）传递，不支持 URL 传参
DOUBAO_HEADLESS	auto	浏览器模式：auto（Windows 桌面默认有头方便首次登录，无界面环境自动无头）、true（强制无头）、false（强制有头）
DOUBAO_AUTO_DELETE_CONV	true	是否在请求完成后自动清理豆包云端临时对话（即用即焚）
DOUBAO_BROWSER_DATA	~/.doubao_browser	浏览器持久化配置目录（保存登录凭证与浏览器缓存）
DOUBAO_RPM_LIMIT	20	每分钟请求频率限制，避免并发过高触发风控
ALLOW_UNPROTECTED_BIND	false	是否允许在未设置 API Key 的情况下将服务暴露到公网 0.0.0.0

---

📌 客观局限与注意事项

为了避免不切实际的预期，这里实事求是地说明当前实现的客观局限：

1. 资源占用：
   • 由于后台运行着一个真实的 Chromium/Chrome 实例，内存占用通常在 300MB ~ 800MB 之间，无法做到纯 HTTP 脚本那样几兆的轻量。
2. Tool Calling / Function Calling：
   • 豆包网页端模型并不原生支持 OpenAI 格式的工具调用。本项目通过在 System Prompt 中注入规则并解析回复中的 XML/JSON 结构来实现模拟工具调用，适合轻度场景，不建议用于重度依赖精准工具调用的复杂 Agent。
3. 多媒体生成限制：
   • 生成的图片带有豆包官方的水印（由字节服务端 CDN 模板渲染，无法绕过）。
   • 视频生成受豆包账号每日免费额度限制。
4. 风控验证码：
   • 若遇到调用异常，可能是触发了豆包的滑块验证码。请在有头浏览器窗口中完成手动验证，或在 Admin 控制台点击“解除拦截标记”。
5. 关于 Docker：
   • Docker 部署已移至 experimental/docker/ 目录，归档为实验性支持。因为在无图形界面的服务器环境下扫码与验证码处理较为繁琐，更推荐在本地桌面环境直接运行。

---

📄 开源许可与免责声明

• 本项目采用 Apache-2.0 License 开源协议。
• 本项目仅供 Python 编程学习、浏览器自动化测试与个人学术研究使用。
• 请勿将本项目用于任何商业营利、高并发滥用或恶意爬取行为。
• 使用本项目过程中产生的一切后果由使用者自行承担，与本项目开发者无关。