# doubao2api **Repository Path**: ipcun/doubao2api ## Basic Information - **Project Name**: doubao2api - **Description**: No description available - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-10-09 - **Last Updated**: 2026-10-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # doubao2api > 一个基于本地浏览器运行时的字节跳动豆包（Doubao）网页端 OpenAI 兼容 API 桥接服务。 --- ## 💡 项目由来与致谢 本项目最初灵感来源于开源项目 [wangchuxiaoji-oss/doubao2api](https://github.com/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` 端点）**： ```bash # 支持 Form 表单上传本地图片文件 curl http://127.0.0.1:9090/v1/images/edits \ -F "image=@photo.png" \ -F "prompt=将图片修改为赛博朋克风格" ``` 或者通过 JSON 直接传入图片远程 URL / Base64： ```json POST /v1/images/edits { "prompt": "将图片修改为水彩画风格", "image": "https://example.com/cat.png" } ``` - **图生视频（`/v1/video/generations` 端点）**： ```json 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 `）传递，不支持 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](LICENSE) 开源协议。 - 本项目仅供 Python 编程学习、浏览器自动化测试与个人学术研究使用。 - 请勿将本项目用于任何商业营利、高并发滥用或恶意爬取行为。 - 使用本项目过程中产生的一切后果由使用者自行承担，与本项目开发者无关。