doubao2api：将豆包装进你的 AI Agent

一个真实痛点的诞生

凌晨两点，你的 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 年底开源了这个项目。

Python FastAPI

核心功能：五项全能多模态

1. 多模态对话（识图 + 读文件）

接入 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）：深度推理，适合数学证明、代码分析等高难度任务

2. 图片生成（文生图 + 图生图）

使用豆包自研的 Seedance 图像模型，通过 generate_image() 方法即可生成图片，支持指定宽高比（1:1 / 16:9 / 9:16）。图片生成基于 TOS 存储 + 火山引擎 ImageX CDN 分发，生成后自动获取可下载 URL。

⚠️ 注意：所有生成的图片均带有豆包水印（水印在 CDN 层通过 ImageX 模板渲染，无法绕过）。

3. 视频生成（文生视频 + 图生视频）

使用 Seedance 2.0 全能视频模型，每日约 10 次免费额度。支持文生视频和图生视频（img2video）两种模式，最长等待约 3 分钟。视频生成是一个异步长连接流程：通过 SSE 轮询任务状态，任务完成后推送视频 URL。

4. 音乐生成（文生音乐）

支持自定义歌词模式，可指定音乐风格（流行/摇滚/民谣/电子/嘻哈/国风等 11 种）和情绪（快乐/放松/活力/忧郁等 9 种）。生成约 60-140 秒 AAC 音频，通常 30-60 秒内返回。

5. 文件中转站（免费跨机传输）

这是一个巧妙的"副产物"功能：通过 /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/             # 静态资源

部署体验：一键 Docker

部署极为简单，项目提供单阶段 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。

使用示例：用 OpenAI SDK 调用

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 开源社区中持续活跃。

doubao2api：将豆包装进你的 AI Agent

一个真实痛点的诞生

背景：为什么是豆包？

Python FastAPI

核心功能：五项全能多模态

1. 多模态对话（识图 + 读文件）

支持三种对话模式，通过 need_deep_think 参数切换：

快速模式（need_deep_think=0）：即时响应，适合简单问答
思考模式（need_deep_think=1）：输出思维链，适合复杂推理问题
专家模式（need_deep_think=3）：深度推理，适合数学证明、代码分析等高难度任务

2. 图片生成（文生图 + 图生图）

⚠️ 注意：所有生成的图片均带有豆包水印（水印在 CDN 层通过 ImageX 模板渲染，无法绕过）。

3. 视频生成（文生视频 + 图生视频）

4. 音乐生成（文生音乐）

5. 文件中转站（免费跨机传输）

技术架构：逆向工程的三层结构

doubao2api 的架构设计非常精妙，分为三层：

第三层：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 状态）

目录结构

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/             # 静态资源

部署体验：一键 Docker

部署极为简单，项目提供单阶段 Dockerfile（基于 python:3.12-slim）：

docker build -t doubao2api .
docker run -d -p 9090:9090 -v ./.doubao_session.json:/app/.doubao_session.json doubao2api

硬件需求方面：无需 GPU，Playwright 的 Chromium 浏览器在 CPU 上运行即可，内存建议 4GB+，磁盘 500MB。

使用示例：用 OpenAI SDK 调用

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 的协议解析，豆包服务条款明确禁止此类行为。技术上可行，法律层面存在风险，使用前请自行评估合规性。

doubao2api

社区活跃度

doubao2api：将豆包装进你的 AI Agent

一个真实痛点的诞生

背景：为什么是豆包？

核心功能：五项全能多模态

1. 多模态对话（识图 + 读文件）

2. 图片生成（文生图 + 图生图）

3. 视频生成（文生视频 + 图生视频）

4. 音乐生成（文生音乐）

5. 文件中转站（免费跨机传输）

技术架构：逆向工程的三层结构

目录结构

部署体验：一键 Docker

使用示例：用 OpenAI SDK 调用

局限与风险

行业意义：免费多模态的新路径

社区活跃度

doubao2api：将豆包装进你的 AI Agent

一个真实痛点的诞生

背景：为什么是豆包？

核心功能：五项全能多模态

1. 多模态对话（识图 + 读文件）

2. 图片生成（文生图 + 图生图）

3. 视频生成（文生视频 + 图生视频）

4. 音乐生成（文生音乐）

5. 文件中转站（免费跨机传输）

技术架构：逆向工程的三层结构

目录结构

部署体验：一键 Docker

使用示例：用 OpenAI SDK 调用

局限与风险

行业意义：免费多模态的新路径