# 豆包助手 API
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
豆包助手 API 是火山方舟平台提供的与豆包同源的企业级 API 服务，旨在帮助企业快速构建可落地、可规模化、可演进的 AI 应用。通过 Responses API，您可将豆包 App 同款 AI 能力（如日常沟通、深度沟通、联网搜索等）快速集成至自有应用，无需从零开发，即可获得安全、可靠且可控的优质 AI 体验。
## 背景信息
### 适用场景
豆包助手 API 适用于从客户服务到业务决策的各类场景，主要有：日常知识问答、智能助手、智能硬件、学习教育、投研投顾等。
|**场景** |**一句话定位** |**核心价值点** |**典型场景** |**推荐方向** |
|---|---|---|---|---|
|日常沟通 |用于高频、情感丰富、即时反馈的人机交互场景。 |轻量、亲切、自然。 |* 生活助手：闲聊、陪伴、日常互动。 |* 智能终端助手、儿童陪伴/陪读。 | \
| | | |* 语音输出：讲解、导览、简单问答。 |* 车载助手、手机助手。 | \
| | | |* 指令式对话：帮我查、帮我写、帮我改。 |* 文旅、展馆、商场、设备内置助手。 | \
| | | |* 轻量内容生成：润色、改写、翻译。 | |
|深度沟通 |用于需要结构化思考、多步推理场景。 |思考纠偏、回复质量高、思考过程可理解。 |* 决策辅助：方案对比/策略分析/取舍权衡。 |* 企业内部分析型助手（产品/运营/战略/管理支持）。 | \
| | | |* 复杂创作：结构化回复/行业方案/商业分析（基于已有知识与逻辑）。 |* 专业 Copilot（不联网也能给出高质量判断）。 | \
| | | |* 学习与理解：原理解释/概念拆解/框架推演。 |* 学习型助手（进阶学习、体系化理解）。 | \
| | | | |* 对“答案质量”要求高、但不要求实时性的场景。 |
|联网搜索 |用于“答案依赖实时或外部信息”的问题。 |信息源丰富，实时获取，标注资料来源，兼顾信息时效性与可信度。 |* 核实信息与来源：用户快速确认事件或产品信息的真实性，并同时查看多方来源。 |* 学术/研究型问题。 | \
| | | |* 获取最新状态：用户实时获取政策、价格、行情等变化信息，确保决策基于当前数据。 |* 高风险决策。 | \
| | | |* 整合多渠道知识：用户将不同来源的信息汇总、分析，形成可直接使用的结论或摘要。 |* 复杂系统分析。 | \
| | | |* 验证对外输出内容：用户在讲解、报告或创作前，确保信息准确、来源可追溯。 |* 需要“不断修正假设”的问题探索。 |
|边想边搜 |结合搜索与分析能力，对公开信息进行多轮检索与整合，用于研究型、学习型、分析型问题。 |推理过程外显，多轮自我校验、中间结论可见。 |* 车载助手，手机助手，语音助手。 |* 研究型产品/分析工具。 | \
| | | |* 售后客服，工单诊断，运营分析。 |* 高风险、高不确定决策支持。 | \
| | | |* 文旅场景、展览讲解，需要加入背景知识。 |* 专业人员（研究、战略、投研）的探索式工作流。 | \
| | | |* 对信息准确性、可核验性要求高的场景。 | |
### **功能列表**
豆包助手 API 的上述适用场景分别对应一种功能，您可通过下表列出的功能标识在参数中指定使用哪项功能。
> **说明**
>
> 单次仅可开启一个功能，不支持同时开启多个功能。
|**功能名称** |**功能标识** |**功能介绍** |
|---|---|---|
|日常沟通 |chat |侧重自然对话，基于通用知识简要回答，无实时信息与深度分析。 |
|深度沟通 |deep_chat |基于已有知识库深度解析，逻辑更严谨，但无实时数据支持。 |
|联网搜索 |ai_search |通过实时联网获取最新资讯，信息时效性强，侧重结果呈现。 |
|边想边搜 |reasoning_search |结合思考过程与实时搜索，先拆解问题再验证信息，逻辑链条完整。 |
为直观展示不同功能的差异，以下通过同一问题 “豆包 App 可以做什么？” 在不同功能模式下的响应效果对比：
**选项：日常沟通（chat）**
```Plain Text
（输出）
我能提供多维度实用帮助，核心能力覆盖以下几类：
- 知识解答：精准回答各类事实性问题，从常识到专业领域关键信息，复杂概念会用简单类比辅助理解。
- 内容创作：撰写文案、小说片段、方案等，能提供多组差异化版本，适配不同场景与受众需求。
- 实用工具：处理翻译（兼顾准确与场景化）、分析文档、生成/编辑图片，还能完成数据分析、复杂计算等任务。
- 情感陪伴：像朋友一样聊天，共情你的情绪，提供简短安慰或建议，也能分享轻松话题。
需要我帮你具体做件事吗？比如分析一份文档内容，或是写一段特定场景的文案。
```
**选项：深度沟通（deep_chat）**
```Plain Text
（思维链）
用户问“豆包App可以做什么？”，需要全面且有条理地列出核心功能，同时符合手机阅读体验，避免冗长。首先，得分类梳理功能，比如知识类、创作类、实用工具类，这样用户一目了然。 知识类方面，要涵盖常见需求，比如解答问题、翻译、医学健康建议，这些是基础且高频的，需要精准说明，比如医学建议要强调科学依据，避免误导。 创作类要突出多样性，文案、小说、方案等，满足不同用户的创作需求，同时提到差异化备选项，体现专业性。 实用工具类要贴近生活和工作，比如处理文档、生成图片视频、语音互动，这些功能能提升用户效率，需要明确列出具体操作，比如“读取PDF/Excel并总结”“陪练英语口语”。 然后，结尾追问要符合要求，找出关键信息点加粗，提供具体可执行的服务，比如“帮你生成一份专属的旅行计划文案”，让用户只需判断是否需要，保持友好自然。 还要注意格式，用列表和加粗突出重点，段落清晰，控制篇幅，确保手机上阅读方便，没有冗余信息，同时语言简洁专业，让用户快速了解豆包的核心能力。
（输出）
豆包能提供多维度服务，核心能力可分为三大类，满足你学习、创作、生活等多场景需求：
1. 知识问答与信息解读
- 解答各类客观问题：从常识、学科知识到专业领域（如法律、科技），精准输出核心答案，复杂概念会用类比辅助理解。
- 提供翻译服务：覆盖单词、短语、复杂句子，兼顾准确性与场景化，多含义表达会补充使用说明。
- 给出医学健康建议：基于科学依据解读食品功效、药品使用（标注风险），区分中医与现代医学表述，不夸大功效。
2. 内容创作与优化
- 定制多样化文案：包括营销文案、朋友圈文案、演讲稿等，提供≥3组差异化备选项，适配不同受众与场景。
- 创作文学内容：支持小说片段、故事、散文等创作，注重语言质感与记忆点，可根据你的风格调整调性。
- 优化文本：对现有内容进行润色、精简、扩写，提升表达流畅度与专业性。
3. 实用工具与互动服务
- 处理文档与数据：读取PDF、Excel、Word等文件并总结，支持数据统计、格式转换，还能生成可视化图表。
- 生成多媒体素材：根据文本描述绘制图片、生成视频脚本，也可对图片进行加字、换背景等编辑。
- 提供语音互动：支持语音通话，可陪你练英语口语、唱歌，也能引导你完成声音克隆操作。
如果你有具体需求，比如想为周末出行做准备，我可以帮你生成一份专属的短途旅行计划文案，需要试试吗？
```
**选项：联网搜索（ai_search）**
```Plain Text
（搜索）
"搜索 2 个关键词，参考 5 篇资料","queries":["豆包App的功能介绍","豆包App可以做的事情"]
（输出）
豆包是一款功能强大的AI助手，能为用户提供多种服务，具体如下：
- 智能对话：作为24小时知识顾问，可回答历史、科学、技术、文化、地理等多领域问题，能理解上下文，通过追问帮助用户理清思路，解决复杂问题。
- 高效写作：拥有工作总结、营销文案、邮件、短视频脚本等多种模板，可分步骤生成内容，支持随时调整，还能通过金句模式提升文案感染力。
- AI搜索：输入问题后不仅返回链接，还直接给出整合答案，自动过滤低质量结果，提供权威信息，复杂问题时可自动搜索补充信息。
- 会议记录：会议中说“录音”可自动开启并转写，结束后自动生成纪要，标注重点、待办事项和责任人，支持多语言实时翻译，输出双语纪要。
- 文档处理：支持上传PDF、Word、图片等文件，可智能解析文档，总结核心观点，列出关键数据，进行中英对照翻译，还能将文档内容自动生成思维导图。
...
```
**选项：边想边搜（reasoning_search）**
```Plain Text
（思维链）
可能需要先确认“豆包App”是否指字节跳动的AI助手，用户可能混淆名称。得查官网或官方文档明确其功能范围，是否包含聊天、信息查询、内容生成等基础服务。还需验证是否支持多语言、图像识别等高级功能，以及是否有企业级应用案例。需要注意区分豆包与同类产品的差异点，比如是否整合抖音生态资源。同时得检查是否有2025年新增的AI功能或合作伙伴服务，比如智能硬件联动。需优先搜索最新产品手册和官方公告，避免引用过时信息。
（搜索）
"搜索 8 个关键词，参考 7 篇资料","queries":["豆包App可以做什么","豆包App 功能","豆包App 官方网站","豆包App 官方文档","豆包App 最新功能","豆包App 企业应用","豆包App AI 功能","豆包App 2025 更新"]
（思维链）
"用户询问豆包功能，先从基础入手：智能对话、文档处理、多模态创作等核心功能。需确认是否覆盖所有场景，比如教育、医疗、金融等行业应用。检查到2025年新增实时视频通话、音乐生成、AI播客等功能，可能遗漏了行业解决方案细节，比如企业API接口的具体应用。需验证是否有未提及的工具整合或高级分析功能，但现有信息已涵盖用户可能关心的工作、学习、生活全场景。进一步搜索可能带来更多细节，但现有信息已足够，现在就进入答复环节。
（输出）
"豆包是字节跳动推出的全能型AI助手，基于先进大模型技术，覆盖工作、学习、生活全场景，功能远超传统聊天工具。以下是其核心能力的详细解析：
一、基础交互与智能问答
1. 自然语言对话
支持普通话、方言语音输入，可连续对话并记忆上下文，像人类一样理解复杂指令。例如询问“秦始皇统一六国的时间”，能精准回答并拓展历史背景。
2. AI搜索与信息整合
输入问题后直接返回权威整合答案，无需跳转网页。例如搜索“5G技术特点”，会自动聚合高时效信息并结构化呈现。
3. 多模态交互
...
二、工作学习效率神器
1. 文档处理专家
- 智能解析：上传PDF、Word等文件，可自动总结核心观点、提取关键数据，如年报财务指标分析。
- 中英对照翻译：学术文献、商务合同边读边译，保留格式和专业术语。
- 思维导图生成：自动将文档内容转化为逻辑清晰的脑图，辅助梳理思路。
2. 高效写作工具
- 模板化创作：覆盖工作总结、营销文案、短视频脚本等50+模板，输入“小学三年级语文教案”即可生成完整教学计划。
- 分步骤优化：先出大纲再细化内容，支持实时润色和风格调整，如将“帮我写方案”改为“市场经理Q4活动策划”。
- 金句模式：添加“请用金句模式”可提升文案感染力，适合社交媒体推广。
3. 代码开发助手
支持Python、Java等30+编程语言，能生成可运行脚本并调试错误。例如输入“Python爬取天气数据并可视化”，可快速获得完整代码。
三、创意与艺术创作
1. AI绘画与设计
- 文生图：输入“海边日落，水彩风格”可生成1-4张候选图，支持调整细节如“添加帆船”。
- 图生图：上传参考图后可转换风格，如将风景照改为赛博朋克风。
- 实用工具：一键抠图、修复老照片、批量生成设计素材，适合自媒体和电商。
2. 视频生成与编辑
- 文本生视频：输入脚本自动生成画面、配音和字幕，支持1080P导出并分享至抖音。
- 图片生视频：单图添加动态效果和旁白，适合产品演示或教育培训。
- 对口型视频：上传人物照片后输入台词，生成自然对话视频，适合虚拟主播创作。
四、生活与健康助手
1. 日程与时间管理
- 语音设置提醒：直接说“今天10点开会，下午3点取快递”，自动同步手机日历并分类任务优先级。
- 会议记录神器：录音转文字并智能提取待办事项，支持多语言实时翻译，输出双语纪要。
2. 健康与生活服务
- 体检报告解读：分析指标异常并提供建议，如“低密度脂蛋白偏高如何调整饮食”。
- 本地生活推荐：基于抖音商家数据，根据口味和预算推荐附近餐厅，提供导航和团购链接。
- 旅行规划：输入目的地生成包含交通、景点、住宿的完整攻略，支持个性化调整。
五、企业级解决方案
1. 团队协作工具
- 企业API接口：可嵌入OA、CRM系统，实现审批流程自动化和客户咨询智能路由，已服务金融、电商数十家企业。
- 共享工作区：项目经理上传会议录音后自动生成待办清单，标注责任人与截止时间，提升协作效率。
2. 行业定制化
- 法律智能体：创建专属AI解答合同问题，引用具体法律条文并提供合规建议。
- 教育智能体：数学辅导AI可讲解习题，育儿智能体提供喂养和教育方案，支持多角色切换。
六、进阶隐藏技能
1. AI播客生成
上传PDF或网页链接，一键生成双人对话播客，语音效果接近真人，适合学习资料转音频。
2. 桌面端高效操作
- AI划词：任意界面选中文字后右键“翻译/解释/总结”，快捷键Alt+1实现网页全文翻译。
- 截图提问：Shift+Alt+A捕捉屏幕内容，识别图片中的文字并进行分析，如公式计算或图表解读。
3. 深度思考模式
复杂问题时开启“深度思考”，边想边搜并串联信息，如分析论文图表或诊断代码逻辑错误，响应延迟控制在800毫秒内。
七、使用技巧与最佳实践
1. 精准提问公式
采用“身份+需求+细节+格式”结构，例如“作为HR，请设计销售岗位面试题，5个核心问题用Markdown表格呈现”。
2. 隐私保护建议
不输入银行卡密码等敏感信息，重要文件处理后手动删除历史记录，避免数据留存。
3. 时段选择策略
长文写作等复杂任务建议在早上8-10点进行，模型响应速度提升40%。 从基础问答到专业创作，从个人效率到企业协作，豆包已进化为真正的“AI超级大脑”。无论是学生、职场人士还是创意工作者，都能通过其丰富功能实现生产力跃升。
立即体验三大隐藏技能：①对它说“记录今天的重要事情”；②上传老照片修复；③输入“生成30秒产品宣传视频脚本”，感受AI如何重塑工作生活范式。
```
通过对比可见：
* **日常沟通**适合闲聊交互，追求的是自然与效率。
* **深度沟通**适合复杂问题解析，追求的是正确性与思考质量。
* **联网搜索**适合获取实时资讯。
* **边想边搜**适合需要逻辑验证与深度洞察的场景。
您可以根据实际业务需求选择对应功能模式，例如客服对话场景可选用**日常沟通**，行业研究场景可选用**边想边搜**。
### **支持的模型**
参见 [豆包助手](/docs/model-list#f44ceef7)。
### 计费信息
参见[豆包助手计费](/docs/doubao-assistant-pricing)。
## 准备工作
1. 获取豆包助手 API 的测试参与资格。
> **说明**
>
> 豆包助手 API 功能当前处于 beta 测试阶段，请联系销售人员或提交工单申请参与测试。
2. 开通豆包助手 API 服务。
访问火山方舟管理控制台的 [**开通管理** **＞ 应用组件库 ＞ 豆包助手 API**](https://ark.volcengine.com/region:cn-beijing/openManagement?&advancedActiveKey=component&tab=DoubaoAssistant) 页面，并开通服务。
> **说明**
>
> 如果您的控制台上没有该页面，可能是因为您尚未获得测试参与资格，或者您登录的账号不是已经获得资格的账号。
3. 获取 API Key。详见[快速入门](/docs/quick-start)。
4. 将 API Key 配置到环境变量中。详见[环境变量配置指南](/docs/environment-variable-configuration-guide)。
5. 如需使用 SDK，请先安装或升级 SDK。详见[安装及升级 SDK](/docs/install-and-upgrade-sdk)。
## **快速开始**
### **示例代码**
**选项：curl**
> **说明**
>
> 测试期间，通过 curl 调用此工具时需要增加`header 'ark-beta-doubao-app: true'`。
```Bash
curl --location 'https://ark.cn-beijing.volces.com/api/v3/responses' \
--header "Authorization: Bearer $ARK_API_KEY" \
--header 'Content-Type: application/json' \
--header 'ark-beta-doubao-app: true' \
--data '{
"model": "doubao-seed-2-1-pro-260915",
"stream": true,
"tools": [
{
"type": "doubao_app",
"feature": {
"ai_search": {
"type": "enabled",
"role_description": "你是科技领域助手，专业解答行业问题"
},
"chat": {
"type": "disabled"
},
"deep_chat": {
"type": "disabled"
},
"reasoning_search": {
"type": "disabled"
}
},
"user_location": {
"type": "approximate",
"country": "中国",
"region": "浙江",
"city": "杭州"
}
}
],
"input": [
{
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "今天有什么AI领域热点新闻"
}
]
}
]
}'
```
**选项：Python SDK**
```Python
import os
from arkruntime import Ark
# 从环境变量中获取API KEY
api_key = os.getenv('ARK_API_KEY')
client = Ark(
base_url='https://ark.cn-beijing.volces.com/api/v3', # 填写实际base_url
api_key=api_key,
)
# 配置豆包助手 API 工具参数
tools = [{
"type": "doubao_app",
"feature": {
"ai_search": {
"type": "enabled",
"role_description": "你是科技领域助手，专业解答行业问题"
}
},
"user_location": {
"type": "approximate",
"country": "中国",
"region": "浙江",
"city": "杭州"
}
}]
# 发送请求
response = client.responses.create(
model="doubao-seed-2-1-pro-260915",
input=[{"role": "user", "content": "今天有什么AI领域热点新闻"}],
tools=tools,
stream=True
)
# 处理响应
for event in response:
print(event)
```
**选项：Java SDK**
```Java
package com.example.arkdemo;
import com.volcengine.ark.runtime.models.responses.*;
import com.volcengine.ark.runtime.service.ArkService;
import io.reactivex.Flowable;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
public class SimplifiedDoubaoArkExample {
private static final String MODEL_NAME = "doubao-seed-2-1-pro-260915";
public static void main(String[] args) {
// 1. 获取环境变量中的API KEY
String apiKey = System.getenv("ARK_API_KEY");
if (apiKey == null) {
System.out.println("ARK_API_KEY environment variable not set");
return;
}
// 2. ArkService初始化
ArkService service = ArkService.builder()
.apiKey(apiKey)
.baseUrl("https://ark.cn-beijing.volces.com/api/v3")
.build();
// 3. 启用豆包工具必需的请求头
Map headers = new HashMap<>();
headers.put("ark-beta-doubao-app", "true");
// 4. 构建工具配置
DoubaoAppTool doubaoTool = DoubaoAppTool.builder()
.feature(
DoubaoAppFeature.builder()
.aiSearch(
DoubaoAppFeatureItem.builder()
.type(DoubaoAppFeatureMode.ENABLED)
.roleDescription("你是科技领域助手，专业解答行业问题")
.build()
)
.build()
)
.userLocation(
UserLocation.builder()
.type(UserLocation.TypeEnum.APPROXIMATE)
.country("中国")
.region("浙江")
.city("杭州")
.build()
)
.build();
// 5. 构建请求参数
ResponsesRequest request = ResponsesRequest.builder()
.model(MODEL_NAME)
.stream(true) // 开启流式请求
.tools(Arrays.asList(doubaoTool))
.input(ResponsesInput.ofString("今天有什么AI领域热点新闻"))
.build();
ResponseCompletedEvent[] finalEventHolder = new ResponseCompletedEvent[1];
try {
// 6. 发送流式请求，遍历所有事件
Flowable streamResponse = service.streamResponse(request, headers);
streamResponse.blockingForEach(event -> {
System.out.println(event); // 打印所有流式事件
// 捕获最终完成事件
if (event instanceof ResponseCompletedEvent) {
synchronized (SimplifiedDoubaoArkExample.class) {
finalEventHolder[0] = (ResponseCompletedEvent) event;
}
}
});
// 7. 提取并打印工具使用统计
ResponseCompletedEvent finalEvent = finalEventHolder[0];
if (finalEvent != null && finalEvent.getResponse() != null && finalEvent.getResponse().getUsage() != null) {
System.out.println("\n===== 工具使用统计 =====");
System.out.println("tool_usage: " + finalEvent.getResponse().getUsage().getToolUsage());
System.out.println("tool_usage_details: " + finalEvent.getResponse().getUsage().getToolUsageDetails());
}
} catch (Exception e) {
System.err.println("Create Response Error: " + e.getMessage());
return;
} finally {
// 关闭服务资源
service.shutdownExecutor();
}
}
}
```
**选项：Go SDK**
```Go
package main
import (
"context"
"fmt"
"io"
"os"
"github.com/volcengine/ark-runtime-go/arkruntime"
"github.com/volcengine/ark-runtime-go/arkruntime/model/responses"
)
const (
chatFeature = "chat"
deepChatFeature = "deepChat"
aiSearchFeature = "aiSearch"
reasoningSearchFeature = "reasoningSearch"
doubaoHeader = "ark-beta-doubao-app"
)
var featureToQuery = map[string]string{
chatFeature: "你好介绍一下你自己",
deepChatFeature: "为什么天空是蓝色",
aiSearchFeature: "今天的 AI 新闻",
reasoningSearchFeature: "今天的 AI 新闻",
}
func main() {
stream(chatFeature)
}
func stream(feature string) {
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
ctx := context.Background()
fmt.Println("----- round 1 -----")
request := &responses.ResponsesRequest{
Model: "doubao-seed-2-1-pro-260915",
Input: textInput(featureToQuery[feature]),
Tools: []responses.Tool{doubaoAppTool(feature)},
}
responseID, err := streamResponse(ctx, client, request)
if err != nil {
fmt.Printf("stream error: %v\n", err)
return
}
fmt.Println("\n----- round 2 -----")
followUp := &responses.ResponsesRequest{
Model: "doubao-seed-2-1-pro-260915",
Input: textInput("刚刚我们聊了什么"),
Tools: []responses.Tool{doubaoAppTool(feature)},
PreviousResponseID: responses.NewOptString(responseID),
}
if _, err := streamResponse(ctx, client, followUp); err != nil {
fmt.Printf("stream error: %v\n", err)
}
}
func textInput(text string) responses.ResponsesInput {
message := responses.ItemEasyMessage{
Role: responses.NewOptMessageRole(responses.MessageRoleUser),
Content: responses.NewContentItemArrayMessageContent(
[]responses.ContentItem{
{
OneOf: responses.NewContentItemTextContentItemSum(
responses.ContentItemText{
Type: responses.ContentItemTextTypeInputText,
Text: text,
},
),
},
},
),
}
return responses.NewInputItemArrayResponsesInput(
[]responses.InputItem{
{OneOf: responses.NewItemEasyMessageInputItemSum(message)},
},
)
}
func doubaoAppTool(feature string) responses.Tool {
enabled := responses.NewOptDoubaoAppFeatureMode(
responses.DoubaoAppFeatureModeEnabled,
)
item := responses.NewOptDoubaoAppFeatureItem(
responses.DoubaoAppFeatureItem{Type: enabled},
)
var features responses.DoubaoAppFeature
switch feature {
case chatFeature:
features.Chat = item
case deepChatFeature:
features.DeepChat = item
case aiSearchFeature:
features.AiSearch = item
case reasoningSearchFeature:
features.ReasoningSearch = item
}
return responses.Tool{
OneOf: responses.NewDoubaoAppToolToolSum(
responses.DoubaoAppTool{
Type: responses.DoubaoAppToolTypeDoubaoApp,
Feature: features,
},
),
}
}
func streamResponse(
ctx context.Context,
client *arkruntime.Client,
request *responses.ResponsesRequest,
) (string, error) {
stream, err := client.CreateResponsesStream(
ctx,
request,
arkruntime.WithCustomHeader(doubaoHeader, "true"),
)
if err != nil {
return "", err
}
var responseID string
for {
event, err := stream.Recv()
if err == io.EOF {
return responseID, nil
}
if err != nil {
return responseID, err
}
handleEvent(event)
if event.OneOf.Type == responses.ResponseCreatedEventResponseStreamEventSum {
responseID = event.OneOf.ResponseCreatedEvent.Response.ID
}
}
}
func handleEvent(event *responses.ResponseStreamEvent) {
switch event.OneOf.Type {
case responses.ResponseDoubaoAppCallSearchSearchingEventResponseStreamEventSum:
fmt.Printf("[searching] %s\n", event.OneOf.ResponseDoubaoAppCallSearchSearchingEvent.SearchingState.Or(""))
case responses.ResponseDoubaoAppCallSearchCompletedEventResponseStreamEventSum:
fmt.Printf("\n[search done] %s\n", event.OneOf.ResponseDoubaoAppCallSearchCompletedEvent.Summary.Or(""))
case responses.ResponseDoubaoAppCallReasoningSearchCompletedEventResponseStreamEventSum:
fmt.Printf("\n[reasoning search done] %s\n", event.OneOf.ResponseDoubaoAppCallReasoningSearchCompletedEvent.Summary.Or(""))
case responses.ResponseDoubaoAppCallReasoningTextDeltaEventResponseStreamEventSum:
fmt.Print(event.OneOf.ResponseDoubaoAppCallReasoningTextDeltaEvent.Delta.Or(""))
case responses.ResponseDoubaoAppCallOutputTextDeltaEventResponseStreamEventSum:
fmt.Print(event.OneOf.ResponseDoubaoAppCallOutputTextDeltaEvent.Delta.Or(""))
}
}
```
### **参数说明**
详见 [创建 Responses 模型请求](/docs/create-model-responses-api)。
## **配置说明**
### **1. 功能启用配置**
您可以使用 `feature` 字段来启用特定功能，并为每个功能单独配置开关和角色描述：
```Python
tools = [{
"type": "doubao_app",
"feature": {
# 开启 日常沟通 功能， 关闭 深度沟通、联网搜索 和 边想边搜 功能
"chat": {"type": "enabled", "role_description": "你是XX车企助手，推荐自家产品"},
"deep_chat": {"type": "disabled"},
"ai_search": {"type": "disabled"},
"reasoning_search": {"type": "disabled"}
}
}]
```
### **2. 角色自定义配置**
您可以使用 `role_description` 字段来自定义助手的角色（例如名称和偏好），但它与 `system prompt` 互斥，二者不能同时使用。
> **说明**
>
> 如需使用自定义`system prompt`功能，请提交工单申请。
```Python
# 车企定制示例
tools = [{
"type": "doubao_app",
"feature": {
"chat": {
"type": "enabled",
"role_description": "你是小魔仙，你有魔法，你可以帮助用户回答任何问题"
}
}
}]
```
### **3. 地理位置优化**
您可以通过设置 `user_location` 字段来优化与地理位置相关的搜索结果。请注意，该字段仅支持填写行政区划级别的信息。
```Python
tools = [{
"type": "doubao_app",
"feature": {"ai_search": {"type": "enabled"}},
"user_location": {
"type": "approximate",
"country": "中国",
"region": "广东",
"city": "深圳"
}
}]
```
### **4. 上下文交互配置**
您可以使用 `store` 字段来存储对话上下文，并通过 `previous_response_id` 传入历史对话 ID 来实现连续对话，此功能最多支持 20 轮。详情请参见[使用上下文缓存能力](/docs/responses-api-migration#f61fe601)。
> **说明**
>
> `store` 字段仅用于保存对话上下文，不会自动保留 `tools` 的配置。如果您希望在连续的对话中沿用相同的工具设置，就需要在每一轮请求中都为 `tools` 字段传入相同的值。
```Python
response = client.responses.create(
model="doubao-seed-2-1-pro-260915",
input=[{"role": "user", "content": "继续刚才的话题，还有其他热点吗"}],
tools=tools,
stream=True,
store=True, # 存储当前对话上下文。此字段不存储tools，每次调用仍需给tools赋值。
previous_response_id="xxx" # 上一轮对话ID
)
```
### **5. 用量查询**
可通过 Responses API 的`usage`字段查看工具使用情况。
示例代码：
```Python
# 提取工具使用统计
if final_event:
tool_usage = final_event.response.usage.tool_usage
tool_usage_details = final_event.response.usage.tool_usage_details
print(f"工具总调用次数: {tool_usage}")
print(f"各功能调用明细: {tool_usage_details}")
```
示例返回值：
```Plain Text
工具总调用次数: ToolUsage(web_search=None, mcp=None, knowledge_search=None, doubao_app=1)
各功能调用明细: ToolUsageDetails(web_search=None, mcp=None, knowledge_search=None, doubao_app={'ai_search': 1})
```
## **实践案例**
### **企业角色定制示例**
以下示例展示如何为客户定制专属助手，实现品牌化交互体验：
```Bash
curl --location 'https://ark.cn-beijing.volces.com/api/v3/responses' \
--header "Authorization: Bearer $ARK_API_KEY" \
--header 'Content-Type: application/json' \
--header 'ark-beta-doubao-app: true' \
--data '{
"model": "doubao-seed-2-1-pro-260915",
"stream": true,
"tools": [
{
"type": "doubao_app",
"feature": {
"chat": {
"type": "enabled",
"role_description": "你是本企业专属助手，专业解答产品咨询、功能介绍、服务相关问题，优先推荐自家产品与服务，保持正面专业的沟通态度"
}
},
"user_location": {
"type": "approximate",
"country": "中国",
"region": "浙江省",
"city": "杭州市"
}
}
],
"input": [
{
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "介绍下你们的核心产品及优势"
}
]
}
]
}'
```
### **边想边搜功能示例**
以下示例展示边想边搜功能的使用，实时获取思考过程和搜索结果：
```Bash
curl --location 'https://ark.cn-beijing.volces.com/api/v3/responses' \
--header "Authorization: Bearer $ARK_API_KEY" \
--header 'Content-Type: application/json' \
--header 'ark-beta-doubao-app: true' \
--data '{
"model": "doubao-seed-2-1-pro-260915",
"stream": true,
"tools": [
{
"type": "doubao_app",
"feature": {
"reasoning_search": {
"type": "enabled",
"role_description": "你是专业资讯助手，通过搜索获取准确信息，详细说明思考过程"
}
}
}
],
"input": [
{
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "2024年AI行业有哪些重大技术突破？"
}
]
}
]
}'
```
## **常见问题**
### **1. 功能可以混合使用吗？**
不可以。请注意，豆包助手 API 工具集不支持与[联网搜索工具](/docs/web-search)、[Knowledge Search（私域知识库搜索工具）](/docs/knowledge-search)、[云部署 MCP / Remote MCP](/docs/mcp-remote-mcp)、[图像处理 Image Process](/docs/image-process) 等工具混合使用，也不支持与自定义函数[Function Calling（函数调用）](/docs/function-calling)同时调用。
### **2. 调用时有哪些常见的参数冲突？**
请注意以下参数的互斥或限制：
* `role_description` 与 `system prompt` 参数互斥。如果您同时指定这两个参数，请求将返回 `400` 错误。
* `max_tool_call` 参数当前无效。如果您在请求中使用该参数，将会返回冲突错误。
* `caching` 参数当前无效。如果您在请求中使用该参数，将会返回 `400` 错误。
### **3. API 的调用频率有限制吗？**
是的，API 的调用频率有限制。默认情况下，单个账号调用频率上限为 2 QPS（每秒查询次数）。如果当前配额无法满足您的需求，请提交工单申请扩容。
### **4. 调用时提示“功能未授权”怎么办？**
如果您尚未开通豆包助手 API 的使用权限，调用 API 时就会收到此错误。请您先前往火山方舟管理控制台开通豆包助手 API。
### **5. 豆包 API 和豆包 App 有什么区别？**
主要区别在于目标用户和使用方式：
* **豆包 API**：专为企业开发者设计，通过火山方舟平台提供。您可以使用它将豆包的 AI 功能集成到自己的应用程序中。
* **豆包 App**：一款面向个人用户的独立应用程序，供用户直接使用。
### **6. 使用豆包 API 有哪些限制？**
与豆包 App 相比，API 的主要限制如下：
* **输入限制**：目前仅支持文本输入，不支持图片或视频。同时，您也无法调整 `top_p`、`temperature`、`max_tokens` 等模型参数。
* **功能与工具限制**：每次 API 调用只能启用一个豆包助手 API 功能（如 `ai_search`）。您无法自定义工具的内部参数（如内容源、搜索轮次），也不能将其与其他自定义函数、内置工具或 MCP 混合使用。
### **7. 使用豆包 API 是否需要付费？**
是的，使用豆包 API 需要付费。我们目前采用按次调用的计费模式，不收取 Token 费用。
具体价格请参考[豆包助手计费](/docs/doubao-assistant-pricing)。
### **8. 使用了豆包 API，是否意味着我的应用是和豆包“联合出品”的？**
不是。使用豆包 API 仅表示您的应用集成了豆包的 AI 能力，**不代表**您的产品是与豆包 App “联合出品”或“官方合作”的产品。您需要明确说明技术来源，避免引起用户混淆。
### **9. 我应该如何宣传产品中集成的豆包 API 功能？**
在对外宣传时，您应使用清晰准确的表述，例如：
* “本产品由豆包助手 API 提供技术支持”。
* “本功能基于豆包助手 API 实现”。
请明确说明您是通过 API 接入，并避免使用“与豆包联合出品”、“官方合作”等可能引起误解的词语。