豆包助手 API 是火山方舟平台提供的与豆包同源的企业级 API 服务，旨在帮助企业快速构建可落地、可规模化、可演进的 AI 应用。通过 Responses API，您可将豆包 App 同款 AI 能力（如日常沟通、深度沟通、联网搜索等）快速集成至自有应用，无需从零开发，即可获得安全、可靠且可控的优质 AI 体验。 ## 背景信息 ### 适用场景豆包助手 API 适用于从客户服务到业务决策的各类场景，主要有：日常知识问答、智能助手、智能硬件、学习教育、投研投顾等。 |**场景** |**一句话定位** |**核心价值点** |**典型场景** |**推荐方向** | |---|---|---|---|---| |日常沟通 |用于高频、情感丰富、即时反馈的人机交互场景。 |轻量、亲切、自然。 |* 生活助手：闲聊、陪伴、日常互动。

* 语音输出：讲解、导览、简单问答。

* 指令式对话：帮我查、帮我写、帮我改。

* 轻量内容生成：润色、改写、翻译。 |* 智能终端助手、儿童陪伴/陪读。

* 车载助手、手机助手。

* 文旅、展馆、商场、设备内置助手。 | |深度沟通 |用于需要结构化思考、多步推理场景。 |思考纠偏、回复质量高、思考过程可理解。 |* 决策辅助：方案对比/策略分析/取舍权衡。

* 复杂创作：结构化回复/行业方案/商业分析（基于已有知识与逻辑）。

* 学习与理解：原理解释/概念拆解/框架推演。 |* 企业内部分析型助手（产品/运营/战略/管理支持）。

* 专业 Copilot（不联网也能给出高质量判断）。

* 学习型助手（进阶学习、体系化理解）。

* 对“答案质量”要求高、但不要求实时性的场景。 | |联网搜索 |用于“答案依赖实时或外部信息”的问题。 |信息源丰富，实时获取，标注资料来源，兼顾信息时效性与可信度。 |* 核实信息与来源：用户快速确认事件或产品信息的真实性，并同时查看多方来源。

* 获取最新状态：用户实时获取政策、价格、行情等变化信息，确保决策基于当前数据。

* 整合多渠道知识：用户将不同来源的信息汇总、分析，形成可直接使用的结论或摘要。

* 验证对外输出内容：用户在讲解、报告或创作前，确保信息准确、来源可追溯。 |* 学术/研究型问题。

* 高风险决策。

* 复杂系统分析。

* 需要“不断修正假设”的问题探索。 | |边想边搜 |结合搜索与分析能力，对公开信息进行多轮检索与整合，用于研究型、学习型、分析型问题。 |推理过程外显，多轮自我校验、中间结论可见。 |* 车载助手，手机助手，语音助手。

* 售后客服，工单诊断，运营分析。

* 文旅场景、展览讲解，需要加入背景知识。

* 对信息准确性、可核验性要求高的场景。 |* 研究型产品/分析工具。

* 高风险、高不确定决策支持。

* 专业人员（研究、战略、投研）的探索式工作流。 | ### **功能列表** 豆包助手 API 的上述适用场景分别对应一种功能，您可通过下表列出的功能标识在参数中指定使用哪项功能。

说明

单次仅可开启一个功能，不支持同时开启多个功能。

|**功能名称** |**功能标识** |**功能介绍** | |---|---|---| |日常沟通 |chat |侧重自然对话，基于通用知识简要回答，无实时信息与深度分析。 | |深度沟通 |deep_chat |基于已有知识库深度解析，逻辑更严谨，但无实时数据支持。 | |联网搜索 |ai_search |通过实时联网获取最新资讯，信息时效性强，侧重结果呈现。 | |边想边搜 |reasoning_search |结合思考过程与实时搜索，先拆解问题再验证信息，逻辑链条完整。 | 为直观展示不同功能的差异，以下通过同一问题 “豆包 App 可以做什么？” 在不同功能模式下的响应效果对比：日常沟通（chat） ```Plain （输出）我能提供多维度实用帮助，核心能力覆盖以下几类： - 知识解答：精准回答各类事实性问题，从常识到专业领域关键信息，复杂概念会用简单类比辅助理解。 - 内容创作：撰写文案、小说片段、方案等，能提供多组差异化版本，适配不同场景与受众需求。 - 实用工具：处理翻译（兼顾准确与场景化）、分析文档、生成/编辑图片，还能完成数据分析、复杂计算等任务。 - 情感陪伴：像朋友一样聊天，共情你的情绪，提供简短安慰或建议，也能分享轻松话题。需要我帮你具体做件事吗？比如分析一份文档内容，或是写一段特定场景的文案。 ``` 深度沟通（deep_chat） ```Plain （思维链）用户问“豆包App可以做什么？”，需要全面且有条理地列出核心功能，同时符合手机阅读体验，避免冗长。首先，得分类梳理功能，比如知识类、创作类、实用工具类，这样用户一目了然。知识类方面，要涵盖常见需求，比如解答问题、翻译、医学健康建议，这些是基础且高频的，需要精准说明，比如医学建议要强调科学依据，避免误导。创作类要突出多样性，文案、小说、方案等，满足不同用户的创作需求，同时提到差异化备选项，体现专业性。实用工具类要贴近生活和工作，比如处理文档、生成图片视频、语音互动，这些功能能提升用户效率，需要明确列出具体操作，比如“读取PDF/Excel并总结”“陪练英语口语”。然后，结尾追问要符合要求，找出关键信息点加粗，提供具体可执行的服务，比如“帮你生成一份专属的旅行计划文案”，让用户只需判断是否需要，保持友好自然。还要注意格式，用列表和加粗突出重点，段落清晰，控制篇幅，确保手机上阅读方便，没有冗余信息，同时语言简洁专业，让用户快速了解豆包的核心能力。（输出）豆包能提供多维度服务，核心能力可分为三大类，满足你学习、创作、生活等多场景需求： 1. 知识问答与信息解读 - 解答各类客观问题：从常识、学科知识到专业领域（如法律、科技），精准输出核心答案，复杂概念会用类比辅助理解。 - 提供翻译服务：覆盖单词、短语、复杂句子，兼顾准确性与场景化，多含义表达会补充使用说明。 - 给出医学健康建议：基于科学依据解读食品功效、药品使用（标注风险），区分中医与现代医学表述，不夸大功效。 2. 内容创作与优化 - 定制多样化文案：包括营销文案、朋友圈文案、演讲稿等，提供≥3组差异化备选项，适配不同受众与场景。 - 创作文学内容：支持小说片段、故事、散文等创作，注重语言质感与记忆点，可根据你的风格调整调性。 - 优化文本：对现有内容进行润色、精简、扩写，提升表达流畅度与专业性。 3. 实用工具与互动服务 - 处理文档与数据：读取PDF、Excel、Word等文件并总结，支持数据统计、格式转换，还能生成可视化图表。 - 生成多媒体素材：根据文本描述绘制图片、生成视频脚本，也可对图片进行加字、换背景等编辑。 - 提供语音互动：支持语音通话，可陪你练英语口语、唱歌，也能引导你完成声音克隆操作。如果你有具体需求，比如想为周末出行做准备，我可以帮你生成一份专属的短途旅行计划文案，需要试试吗？ ``` 联网搜索（ai_search） ```Plain （搜索） "搜索 2 个关键词，参考 5 篇资料","queries":["豆包App的功能介绍","豆包App可以做的事情"] （输出）豆包是一款功能强大的AI助手，能为用户提供多种服务，具体如下： - 智能对话：作为24小时知识顾问，可回答历史、科学、技术、文化、地理等多领域问题，能理解上下文，通过追问帮助用户理清思路，解决复杂问题。 - 高效写作：拥有工作总结、营销文案、邮件、短视频脚本等多种模板，可分步骤生成内容，支持随时调整，还能通过金句模式提升文案感染力。 - AI搜索：输入问题后不仅返回链接，还直接给出整合答案，自动过滤低质量结果，提供权威信息，复杂问题时可自动搜索补充信息。 - 会议记录：会议中说“录音”可自动开启并转写，结束后自动生成纪要，标注重点、待办事项和责任人，支持多语言实时翻译，输出双语纪要。 - 文档处理：支持上传PDF、Word、图片等文件，可智能解析文档，总结核心观点，列出关键数据，进行中英对照翻译，还能将文档内容自动生成思维导图。 ... ``` 边想边搜（reasoning_search） ```Plain （思维链）可能需要先确认“豆包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如何重塑工作生活范式。 ``` 通过对比可见： * **日常沟通**适合闲聊交互，追求的是自然与效率。 * **深度沟通**适合复杂问题解析，追求的是正确性与思考质量。 * **联网搜索**适合获取实时资讯。 * **边想边搜**适合需要逻辑验证与深度洞察的场景。您可以根据实际业务需求选择对应功能模式，例如客服对话场景可选用**日常沟通**，行业研究场景可选用**边想边搜**。 ### **支持的模型** 参见 [豆包助手](https://ark.volcengine.com/region:cn-beijing/docs/ark/model-list#f44ceef7)。 ### 计费信息参见[豆包助手计费](https://ark.volcengine.com/region:cn-beijing/docs/ark/doubao-assistant-pricing)。 ## 准备工作 1. 获取豆包助手 API 的测试参与资格。

说明

豆包助手 API 功能当前处于 beta 测试阶段，请联系销售人员或提交工单申请参与测试。

2. 开通豆包助手 API 服务。访问火山方舟管理控制台的 [开通管理](https://ark.volcengine.com/region:cn-beijing/openManagement?&advancedActiveKey=component&tab=DoubaoAssistant)[ ](https://ark.volcengine.com/region:cn-beijing/openManagement?&advancedActiveKey=component&tab=DoubaoAssistant)[＞应用组件库＞豆包助手 API](https://ark.volcengine.com/region:cn-beijing/openManagement?&advancedActiveKey=component&tab=DoubaoAssistant) 页面，并开通服务。

说明

如果您的控制台上没有该页面，可能是因为您尚未获得测试参与资格，或者您登录的账号不是已经获得资格的账号。

![图片](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/fa2f4dce1944448c9abe7d23fc5f41cd~tplv-goo7wpa0wc-image.image) 3. 获取 API Key。详见[快速入门](https://ark.volcengine.com/region:cn-beijing/docs/ark/quick-start)。 4. 将 API Key 配置到环境变量中。详见[环境变量配置指南](https://ark.volcengine.com/region:cn-beijing/docs/ark/environment-variable-configuration-guide)。 5. 如需使用 SDK，请先安装或升级 SDK。详见[安装及升级 SDK](https://ark.volcengine.com/region:cn-beijing/docs/ark/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 模型请求](https://ark.volcengine.com/region:cn-beijing/docs/ark/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 轮。详情请参见[使用上下文缓存能力](https://ark.volcengine.com/region:cn-beijing/docs/ark/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 工具总调用次数: 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 工具集不支持与[联网搜索工具](https://ark.volcengine.com/region:cn-beijing/docs/ark/web-search)、[Knowledge Search（私域知识库搜索工具）](https://ark.volcengine.com/region:cn-beijing/docs/ark/knowledge-search)、[云部署 MCP / Remote MCP](https://ark.volcengine.com/region:cn-beijing/docs/ark/mcp-remote-mcp)、[图像处理 Image Process](https://ark.volcengine.com/region:cn-beijing/docs/ark/image-process) 等工具混合使用，也不支持与自定义函数[Function Calling（函数调用）](https://ark.volcengine.com/region:cn-beijing/docs/ark/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 费用。具体价格请参考[豆包助手计费](https://ark.volcengine.com/region:cn-beijing/docs/ark/doubao-assistant-pricing)。 ### **8. 使用了豆包 API，是否意味着我的应用是和豆包“联合出品”的？** 不是。使用豆包 API 仅表示您的应用集成了豆包的 AI 能力，**不代表**您的产品是与豆包 App “联合出品”或“官方合作”的产品。您需要明确说明技术来源，避免引起用户混淆。 ### **9. 我应该如何宣传产品中集成的豆包 API 功能？** 在对外宣传时，您应使用清晰准确的表述，例如： * “本产品由豆包助手 API 提供技术支持”。 * “本功能基于豆包助手 API 实现”。请明确说明您是通过 API 接入，并避免使用“与豆包联合出品”、“官方合作”等可能引起误解的词语。