doubao2api
免费调用豆包全部多模态能力：识图、读文件、文生图、视频、音乐。OpenAI兼容接口，为纯文本LLM补全视觉理解。
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
免费调用豆包全部多模态能力：识图、读文件、文生图、视频、音乐。OpenAI兼容接口，为纯文本LLM补全视觉理解。
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
凌晨两点，你的 AI Agent 正在处理一份用户上传的产品需求文档。文档里有截图、有流程图、有表格——而你的 Agent 是纯文本模型，看不见，读不懂，只能回复一句"抱歉，我无法处理图片"。这种无力感，相信每一个搭建过 AI Agent 的开发者都体验过。
doubao2api 正是为了解决这个问题而生。它将字节跳动旗下豆包（Doubao）桌面客户端的多模态能力——包括图片理解、文件解析、文生图、文生视频、文生音乐——通过逆向工程的方式，封装成一套 OpenAI 兼容的 REST API。只需一行代码，纯文本模型也能"长出眼睛和双手"。
豆包是字节跳动推出的 AI 助手产品，提供免费的多模态服务：图片理解、60+ 种文件格式解析、文生图（Seedance）、文生视频（Seedance 2.0）、文生音乐。然而，豆包官方仅提供网页端和桌面客户端，没有开放 API。这给需要程序化调用的开发者造成了壁垒。
本项目作者 wangchuxiaoji-oss 在搭建自己的 Hermes Agent 时，遇到了同样的困境——DeepSeek V4 Flash 是纯文本模型，无法理解用户上传的截图和 PDF。他开始研究豆包桌面客户端的通信协议，最终逆向出了完整的 API 端点，并于 2024 年底开源了这个项目。
接入 doubao2api 后，Agent 可以在对话中上传图片（PNG/JPEG/WebP）或文件（PDF/Word/Excel/PPT/代码等 60+ 格式），豆包模型会返回详细理解结果。这是整个项目的核心价值点——为纯文本 LLM 补全视觉理解能力。
支持三种对话模式，通过 need_deep_think 参数切换：
need_deep_think=0）：即时响应，适合简单问答need_deep_think=1）：输出思维链，适合复杂推理问题need_deep_think=3）：深度推理，适合数学证明、代码分析等高难度任务使用豆包自研的 Seedance 图像模型，通过 generate_image() 方法即可生成图片，支持指定宽高比（1:1 / 16:9 / 9:16）。图片生成基于 TOS 存储 + 火山引擎 ImageX CDN 分发，生成后自动获取可下载 URL。
⚠️ 注意：所有生成的图片均带有豆包水印（水印在 CDN 层通过 ImageX 模板渲染，无法绕过）。
使用 Seedance 2.0 全能视频模型，每日约 10 次免费额度。支持文生视频和图生视频（img2video）两种模式，最长等待约 3 分钟。视频生成是一个异步长连接流程：通过 SSE 轮询任务状态，任务完成后推送视频 URL。
支持自定义歌词模式，可指定音乐风格（流行/摇滚/民谣/电子/嘻哈/国风等 11 种）和情绪（快乐/放松/活力/忧郁等 9 种）。生成约 60-140 秒 AAC 音频，通常 30-60 秒内返回。
这是一个巧妙的"副产物"功能：通过 /v1/files 上传任意文件（最大约 50MB）获得一个永久 TOS URI，之后随时通过 /v1/files/download 换取 7 天有效的 CDN 下载链接。这个 URI 可以跨机器传递——Agent A 在服务器 A 上传文件拿到 URI，把 URI 传给 Agent B，Agent B 凭 URI 下载。相当于免费的跨机器文件传输通道，无需自建 OSS，单文件最大 50MB，存储不过期。
doubao2api 的架构设计非常精妙，分为三层：
第一层：认证层（QR 扫码 + Session）
通过 Playwright 启动无头浏览器，模拟用户在豆包网页端扫码登录，获取 sessionid、ttwid、passport_csrf_token 等认证 Cookie。登录成功后，Session 信息保存到 .doubao_session.json 文件，后续请求直接复用，无需重复扫码。
第二层：签名层（X-Bogus 签名注入）
豆包 API 请求需要携带 X-Bogus 签名（由 window.bdms.frontierSign() 在浏览器上下文中生成）。项目使用 Playwright 的 expose_function 机制，将浏览器内的签名函数暴露给 Python 调用，解决了纯 HTTP 请求无法生成合法签名的问题。
第三层：API 层（OpenAI 兼容 + FastAPI）
unified_server.py 基于 FastAPI 构建完整的 OpenAI 兼容接口：
POST /v1/chat/completions：流式/非流式对话GET /v1/models：模型列表POST /v1/images/generations：图片生成POST /v1/video/generations：视频生成POST /v1/audio/generations：音乐生成POST /v1/files：文件上传GET /v1/files/download：文件下载GET /health：健康检查GET /admin：Admin 管理后台（HTML 页面，每 5 秒自动刷新 session 状态）此外，项目还包含了 qianwen_client.py，用于逆向阿里通义千问（Qianwen）的 API——通过阿里安全 SDK（百夏/baxia）实现四步签名（qwenSign → etSign → getFYToken → getUidToken），这是一个独立的额外模块。
doubao2api/
├── __init__.py # 包导出
├── __main__.py # 入口：python -m doubao2api
├── browser_client.py # Playwright 浏览器客户端（登录+签名）
├── client.py # 核心会话客户端（对话/生成/上传）
├── unified_server.py # FastAPI OpenAI 兼容服务器
├── qr_login.py # QR 码扫码登录
├── captcha_handler.py # 验证码处理
├── captcha_server.py # 验证码服务
├── session.py # Session 加载/保存
├── sse.py # SSE 事件解析
├── token_counter.py # Token 计数
├── tool_calling.py # 工具调用（千问客户端用）
├── qianwen_client.py # 阿里千问逆向客户端
└── static/ # 静态资源
部署极为简单，项目提供单阶段 Dockerfile（基于 python:3.12-slim）：
docker build -t doubao2api .
docker run -d -p 9090:9090 -v ./.doubao_session.json:/app/.doubao_session.json doubao2api
服务启动后默认监听 0.0.0.0:9090，可通过 /v1/chat/completions 接口用任何 OpenAI 兼容客户端调用。部署难度属于中等——技术门槛在于需要预先扫码获取 session 文件，但 QRLogin 支持跨平台，无需安装豆包桌面客户端。
硬件需求方面：无需 GPU，Playwright 的 Chromium 浏览器在 CPU 上运行即可，内存建议 4GB+，磁盘 500MB。
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:9090/v1",
api_key="your-api-key" # 留空则不鉴权
)
# 多模态对话
response = client.chat.completions.create(
model="doubao-think",
messages=[
{"role": "user", "content": [
{"type": "text", "text": "这张图里有什么？"},
{"type": "image_url", "image_url": {"url": "https://example.com/photo.png"}}
]}
],
stream=True
)
for chunk in response:
print(chunk.choices[0].delta.content, end="", flush=True)
项目坦诚列出了几个重要限制：
不适合编程智能体：豆包模型不支持 Function Calling/Tool Use，无法调用外部工具（如文件读写、终端命令、代码搜索）。如果你需要的是能操作代码仓库的 coding agent，请选择原生支持工具调用的模型（如 Claude Code、Codex）。
Session 有效期：豆包 Session 可能过期，需要定期重新扫码。当前代码有 session 保活机制（默认 2 小时刷新一次），但风控检测触发时需要人工介入。
msToken 风控：部分请求需要 msToken，假值会触发风控，建议留空由系统自动处理。
图片水印：生成的图片/视频 URL 带有水印，无法绕过 CDN 模板渲染。
法律灰色地带：逆向工程涉及对专有 API 的协议解析，豆包服务条款明确禁止此类行为。技术上可行，法律层面存在风险，使用前请自行评估合规性。
在 OpenAI GPT-4V 收费、Claude Vision 收费的背景下，doubao2api 提供了一条完全免费的多模态调用路径。对于个人开发者、开源项目和预算有限的小团队来说，这个项目的价值不可忽视。
从技术角度看，这个项目也展示了逆向工程在 AI 时代的另一种可能——不是用来破解闭源模型，而是为免费服务打通标准化接口，让更多系统能够接入进来。它的出现填补了"免费多模态 API"这一生态位的空白，预计将在 AI Agent 开源社区中持续活跃。