请求方式	GET
请求地址	`https://api.coze.cn/v1/bots/:bot_id`
权限	`getMetadata` 确保调用该接口使用的访问令牌开通了 `getMedata` 权限，详细信息参考鉴权方式。
接口说明	查看指定智能体的配置信息。

请求地址

https://api.coze.cn/v1/bots/:bot_id

权限

getMetadata

确保调用该接口使用的访问令牌开通了 getMedata 权限，详细信息参考鉴权方式。

接口说明 查看指定智能体的配置信息。

请求参数

参数	取值	说明
Authorization	Bearer $AccessToken	用于验证客户端身份的访问令牌。你可以在扣子编程中生成访问令牌，详细信息，参考准备工作。
Content-Type	application/json	解释请求正文的方式。

Path

参数类型 是否必选 示例说明

参数	类型	是否必选	示例	说明
bot_id	String	必选	73428668*****	要查看的智能体 ID。进入智能体的开发页面，开发页面 URL 中 `bot` 参数后的数字就是智能体 ID。例如`https://www.coze.cn/space/341**/bot/73428668*`，bot ID 为`73428668***`。说明确保该智能体的所属空间已经生成了访问令牌。

bot_id

String

必选

73428668*****

要查看的智能体 ID。

进入智能体的开发页面，开发页面 URL 中 bot 参数后的数字就是智能体 ID。例如https://www.coze.cn/space/341****/bot/73428668*****，bot ID 为73428668*****。

说明

确保该智能体的所属空间已经生成了访问令牌。

Query

参数类型 是否必选 示例说明

参数	类型	是否必选	示例	说明
is_published	Boolean	可选	true	根据智能体的发布状态筛选对应版本。默认值为 `true`。 `true` ：查看已发布版本的配置。 `false` ：查看当前草稿版本的配置。

is_published

Boolean

可选

true

根据智能体的发布状态筛选对应版本。默认值为 true。

true ：查看已发布版本的配置。
false ：查看当前草稿版本的配置。

返回参数

参数	类型	示例	说明
data	Object of BotInfo	\	返回的智能体配置信息。
code	Long	0	调用状态码。0 表示调用成功，其他值表示调用失败，你可以通过 msg 字段判断详细的错误原因。
msg	String	“”	状态信息。API 调用失败时可通过此字段查看详细错误信息。状态码为 0 时，msg 默认为空。
detail	Object of ResponseDetail	{“logid”:“1234567890****”}	包含请求的详细日志信息，用于问题排查和调试。

BotInfo

参数	类型	示例	说明
bot_id	String	73428668*****	智能体的唯一标识。
name	String	新闻	智能体的名称。
description	String	每天给我推送 AI 相关的新闻。	智能体的描述信息。
icon_url	String	https://example.com/icon.png	智能体的头像地址，用于展示智能体的图标。
create_time	Long	1715689059	创建时间，格式为 10 位的 Unixtime 时间戳，单位为秒（s）。
update_time	Long	1716388526	更新时间，格式为 10 位的 Unixtime 时间戳，单位为秒（s）。
version	String	171638852****	智能体最新版本的版本号。
prompt_info	Object of PromptInfo	{“prompt”: “调用getToutiaoNews工具推送最新的科技新闻。”}	智能体的提示词配置。
onboarding_info	Object of OnboardingInfoV2	{ “prologue”: “你好，我可以为你提供最新、最有趣的科技新闻。让我们一起探索科技的世界吧！”, “suggested_questions”: [ “你能给我推荐一些最新的科技新闻吗？”, “你知道最近有哪些科技趋势吗？”, “你能告诉我如何获得更多关于科技的信息吗？” ] }	智能体的开场白配置。
bot_mode	Integer	0	智能体模式，取值： 0：单 Agent 模式 1：多 Agent 模式
plugin_info_list	Array of PluginInfo	[{“plugin_id”:“730197029480849**”,“name”:“头条新闻”,“icon_url”:“https://example.com/plugin_icon.png”,“description”:“持续更新，了解最新的头条新闻和新闻文章。”,“api_info_list”:[{“api_id”:“730197029480851**”,“name”:“getToutiaoNews”,“description”:“搜索新闻讯息”}]}]	智能体配置的插件列表，包含插件的名称、图标、描述及工具信息。
model_info	Object of ModelInfo	{“top_k”:50,“top_p”:1,“model_id”:“1706077826”,“max_tokens”:4096,“model_name”:“豆包·Function call模型”,“parameters”:{“thinking_type”:“enabled”},“temperature”:1,“context_round”:30,“response_format”:“text”,“presence_penalty”:0,“frequency_penalty”:0}	智能体绑定的模型配置信息，包括模型 ID、名称、生成参数等。
folder_id	String	752316125533***	智能体所属的文件夹 ID。
knowledge	Object of CommonKnowledge	{ “knowledge_infos”: [ { “id”: “738694398580390****”, “name”: “text” } ] }	智能体绑定的知识库。
variables	Array of Variable	-	智能体配置的变量列表。
media_config	Object of MediaConfig	{“is_voice_call_closed”:false}	智能体的语音通话配置，是否关闭语音通话功能。
owner_user_id	String	368567*****	智能体创建者的扣子用户 ID。
voice_info_list	Array of Voice	[ { “voice_id”: “7468512265134800000”, “language_code”: “zh” } ]	智能体配置的音色。
shortcut_commands	Array of ShortcutCommandInfo	[{“id”:“745701083352557**”,“name”:“示例快捷指令”,“command”:“/sc_demo”,“description”:“快捷指令示例”,“query_template”:“搜索今天的新闻讯息”,“icon_url”:“https://**”,“components”:[{“name”:“query”,“description”:“新闻搜索关键词”,“type”:“text”,“tool_parameter”:“query”,“default_value”:“”,“is_hide”:false}],“tool”:{“name”:“头条新闻”,“type”:“plugin”}}]	智能体配置的快捷指令。
workflow_info_list	Array of WorkflowInfo	[{“id”:“746049108611037****”,“name”:“示例工作流”,“description”:“工作流示例”,“icon_url”:“https://example.com/workflow_icon.png”}]	智能体配置的工作流列表，包含工作流的 ID、名称、图标及描述信息。
background_image_info	Object of BackgroundImageInfo	\	智能体背景的图片配置信息，包含 Web 端和移动端的背景图 URL、主题颜色、裁剪位置及渐变效果等。
default_user_input_type	String	text	默认的用户输入方式。枚举值如下： text：打字输入。 voice：语音输入。 call：语音通话。

PromptInfo

参数类型示例说明

参数	类型	示例	说明
prompt	String	你是一位经验丰富的中餐大厨，能够熟练传授各类中餐的烹饪技巧，每日为大学生厨师小白教学一道经典中餐的制作方法。	智能体的人设与回复逻辑。长度为 0~ 20,000 个字符。默认为空。开启前缀缓存后，不支持通过 `prompt` 参数设置提示词，需要通过 `prefix_prompt_info` 参数设置提示词。
prompt_mode	String	standard	提示词模式，用于指定智能体的人设与回复逻辑的配置方式。枚举值： `standard`（默认值）：标准模式。未开启前缀缓存时使用该模式。 `prefix`：前缀缓存模式，提示词会分为缓存提示词和非缓存提示词两部分。开启前缀缓存后需要设置为该模式。
prefix_prompt_info	Object of PrefixPromptInfo	\	通过 `cache_type` 或 `parameters.caching.type`开启前缀缓存后，你需要通过该参数设置缓存提示词（`prefix_prompt`）和非缓存提示词（`dynamic_prompt`）。不支持通过 `prompt` 参数设置提示词。

prompt

String

你是一位经验丰富的中餐大厨，能够熟练传授各类中餐的烹饪技巧，每日为大学生厨师小白教学一道经典中餐的制作方法。

智能体的人设与回复逻辑。长度为 0~ 20,000 个字符。默认为空。

开启前缀缓存后，不支持通过 prompt 参数设置提示词，需要通过 prefix_prompt_info 参数设置提示词。

prompt_mode

String

standard

提示词模式，用于指定智能体的人设与回复逻辑的配置方式。枚举值：

standard（默认值）：标准模式。未开启前缀缓存时使用该模式。
prefix：前缀缓存模式，提示词会分为缓存提示词和非缓存提示词两部分。开启前缀缓存后需要设置为该模式。

prefix_prompt_info Object of PrefixPromptInfo \ 通过 cache_type 或 parameters.caching.type开启前缀缓存后，你需要通过该参数设置缓存提示词（prefix_prompt）和 非缓存提示词（dynamic_prompt）。不支持通过 prompt 参数设置提示词。

PrefixPromptInfo

参数	类型	示例	说明
prefix_prompt	String	\	缓存提示词，大量重复出现的固定规则、模板框架或背景信息，用于指引大模型输出格式与风格。扣子编程会将其缓存并复用，大模型无需重新解析这部分固定信息。
dynamic_prompt	String	\	非缓存提示词，动态变化的个性化信息，仅针对当前请求生效。

OnboardingInfoV2

参数类型示例说明

参数	类型	示例	说明
prologue	String	你好，我可以为你提供最新、最有趣的科技新闻。让我们一起探索科技的世界吧！	智能体配置的开场白内容。开场白中如果设置了用户名称变量`{{user_name}}`，API 场景中需要业务方自行处理，例如展示开场白时将此变量替换为业务侧的用户名称。
suggested_questions	Array of String	[“你能给我推荐一些最新的科技新闻吗？”,“你知道最近有哪些科技趋势吗？”,“你能告诉我如何获得更多关于科技的信息吗？”]	智能体配置的推荐问题列表。未开启用户问题建议时，不返回此字段。

prologue

String

你好，我可以为你提供最新、最有趣的科技新闻。让我们一起探索科技的世界吧！

智能体配置的开场白内容。

开场白中如果设置了用户名称变量{{user_name}}，API 场景中需要业务方自行处理，例如展示开场白时将此变量替换为业务侧的用户名称。

suggested_questions Array of String [“你能给我推荐一些最新的科技新闻吗？”,“你知道最近有哪些科技趋势吗？”,“你能告诉我如何获得更多关于科技的信息吗？”] 智能体配置的推荐问题列表。未开启用户问题建议时，不返回此字段。

PluginInfo

参数	类型	示例	说明
plugin_id	String	730197029480849****	插件唯一标识。
name	String	头条新闻	插件名称。
icon_url	String	https://example.com/plugin_icon.png	插件的头像地址，用于展示插件的图标。
description	String	持续更新，了解最新的头条新闻和新闻文章。	插件的描述信息，用于说明插件的功能或用途。
api_info_list	Array of ApiInfo	[ { “api_id”: “730197029480851****”, “name”: “getToutiaoNews”, “description”: “搜索新闻讯息” } ]	插件的工具列表信息。

ApiInfo

参数	类型	示例	说明
api_id	String	730197029480851****	插件工具的 ID。
name	String	getToutiaoNews	插件工具的名称。
description	String	搜索新闻讯息	插件工具的描述。

ModelInfo

参数	类型	示例	说明
top_k	Integer	50	生成文本时，采样候选集的大小。该参数控制模型在生成每个词时考虑的候选词数量，值越小生成的文本越保守和确定，值越大生成的文本越多样和随机。
top_p	Double	1	Top P 采样参数，用于控制生成文本时的多样性。取值范围为 `0` 到 `1`，值越小生成的文本越保守和确定，值越大生成的文本越多样和随机。
model_id	String	1706077826	智能体绑定的模型的 ID。
max_tokens	Integer	4096	模型输出的 Tokens 长度上限。
model_name	String	豆包·Function call模型	智能体绑定的模型名称。
parameters	JSON Map	{“thinking_type”: “enabled”}	模型深度思考相关配置。开发者可以设置开启或关闭深度思考，从而灵活控制模型在交互过程中的 Token 消耗。 `thinking_type` 的值可以设置为： `enabled`：（默认值）开启深度思考。智能体在与用户对话时会先输出一段思维链内容，通过逐步拆解问题、梳理逻辑，提升最终输出答案的准确性。但该模式会因额外的推理步骤消耗更多 Token。说明开启深度思考后：模型不支持 Function Call，即工具调用。智能体不能使用插件、触发器、变量、数据库、文件盒子、不能添加工作流和对话流。不支持使用插件和工作流相关的快捷指令。 `disabled`：关闭深度思考。智能体将直接生成最终答案，不再经过额外的思维链推理过程，可有效降低 Token 消耗，提升响应速度。 `auto`：当前仅豆包·1.6·自动深度思考·多模态模型支持该参数。启用自动模式后，模型会根据对话内容的复杂度，自动判断是否启用深度思考说明当前仅如下模型支持深度思考开关配置：豆包·1.6·自动深度思考·多模态模型豆包·1.6·极致速度·多模态模型豆包·1.5·Pro·视觉深度思考豆包·GUI·Agent模型
temperature	Double	1	生成随机性。
context_round	Integer	30	携带上下文轮数。
response_format	String	text	输出格式。枚举值： text：文本。 markdown：Markdown 格式。 json：json 格式。
presence_penalty	Double	0	重复主题惩罚。用于控制模型输出相同主题的频率。当该值为正时，会阻止模型频繁讨论相同的主题，从而增加输出内容的多样性。
frequency_penalty	Double	0	重复语句惩罚。用于控制模型输出重复语句的频率。当该值为正时，会阻止模型频繁使用相同的词汇和短语，从而增加输出内容的多样性。
api_mode	String	chat_api	模型的 API 协议类型，用于指定智能体与模型交互时使用的 API 协议。枚举值： `chat_api`：智能体需要在请求时带上对话历史作为上下文。适用于日常闲聊、基础咨询、简单文本生成等轻量化需求。 `responses_api`：模型新推出的 API，不仅延续了 Chat API 的易用性，还原生支持高效的上下文管理和前缀缓存。适用于需要多步推理等复杂任务链处理的场景。说明仅部分模型支持`responses_api`协议，具体支持的模型请参见模型能力差异。

CommonKnowledge

参数	类型	示例	说明
knowledge_infos	Array of KnowledgeInfo	[ { “id”: “738694398580390****”, “name”: “text” } ]	智能体绑定的知识库信息。

KnowledgeInfo

参数	类型	示例	说明
id	String	738694398580390****	知识库 ID。
name	String	智能助手知识库	知识库名称。

Variable

参数	类型	示例	说明
enable	Boolean	true	是否启用该变量。 true：启用该变量。 false：未启用该变量。
channel	String	custom	变量的类型。当前只支持展示用户自定义变量（custom）。
keyword	String	name	变量名。
description	String	姓名	变量描述。
default_value	String	-	变量的默认值。
prompt_enable	Boolean	true	是否允许该变量被 Prompt 访问。 true：变量支持在 Prompt 中访问。 false：变量不支持在 Prompt 中访问，仅能在工作流中访问。

MediaConfig

参数类型示例说明

参数	类型	示例	说明
is_voice_call_closed	Boolean	false	是否关闭智能体的语音通话功能。 `true`：关闭语音通话。 `false`：开启语音通话（默认）。

is_voice_call_closed

Boolean

false

是否关闭智能体的语音通话功能。

true：关闭语音通话。
false：开启语音通话（默认）。

Voice

参数	类型	示例	说明
voice_id	String	7468512265134899251	音色的 ID。获取方法请参见查看音色列表。
language_code	String	zh	此音色的语种代号。获取方法请参见查看音色列表。

ShortcutCommandInfo

参数	类型	示例	说明
id	String	745701083352557****	快捷指令的唯一标识。
name	String	示例快捷指令	快捷指令的按钮名称。
tool	Object of ShortcutCommandToolInfo	{“name”:“头条新闻”,“type”:“plugin”}	快捷指令使用的工具信息。
command	String	/sc_demo	快捷指令的指令名称。
agent_id	String	745705134267144****	对于多 Agent 类型的智能体，此参数返回快捷指令指定回答的节点 ID。
icon_url	String	https://example.com/icon***.png	快捷指令的图标地址。
description	String	快捷指令示例	快捷指令的描述。
query_template	String	搜索今天的新闻讯息	快捷指令的指令内容。

ShortcutCommandToolInfo

参数	类型	示例	说明
name	String	头条新闻	快捷指令的工具名称。
type	String	plugin	工具类型。取值为： workflow：工作流。 plugin：插件。

参数

类型

示例

说明

name

String

头条新闻

快捷指令的工具名称。

type

String

plugin

工具类型。取值为：

workflow：工作流。
plugin：插件。

WorkflowInfo

参数	类型	示例	说明
id	String	746049108611037****	工作流的 ID。
name	String	示例工作流	工作流的名称。
icon_url	String	https://example.com/workflow_icon.png	工作流的头像地址，用于展示工作流的图标。
description	String	工作流示例	工作流的描述。

BackgroundImageInfo

参数	类型	示例	说明
web_background_image	Object of BackgroundImageDetail	-	Web 端背景图。
mobile_background_image	Object of BackgroundImageDetail	-	移动端背景图。

BackgroundImageDetail

参数	类型	示例	说明
image_url	String	https://example.com/image.jpg	背景图片的 URL 地址。
theme_color	String	#FFFFFF	背景图片的主题颜色，通常用于与图片搭配的其他元素的颜色。格式为十六进制颜色代码。
canvas_position	Object of CanvasPosition	{“top”:100,“left”:50,“width”:300,“height”:200}	背景图片在原始图片中的位置坐标及尺寸参数，即背景图片在画布中的实际显示区域范围。包括图片顶部 / 左侧的偏移量、宽度和高度。
gradient_position	Object of GradientPosition	{ “left”: 0.0, “right”: 800.0 }	设置背景图渐变效果。通过指定渐变的左右边界位置，控制渐变的起始和结束点，从而实现背景图的渐变效果。

CanvasPosition

参数	类型	示例	说明
top	Double	100	裁剪区域顶部起始坐标，距原始图片顶部的像素值（px）。值越大，裁剪区域越向下移动。 `top` 和 `left` 的值不能超过画布的实际尺寸
left	Double	50	裁剪区域左侧起始坐标，距原始图片左侧的像素值（px）。值越大，裁剪区域越向右移动。
width	Double	300	裁剪区域的宽度，单位为像素（px）。此值决定了裁剪区域的水平范围，必须为正数。
height	Double	200	裁剪区域的高度，单位为像素（px）。此值决定了裁剪区域的垂直范围，必须为正数。

GradientPosition

参数	类型	示例	说明
left	Double	0	渐变效果的左侧边界位置，单位为像素（px）。此值表示渐变从画布左侧开始的位置，值越小，渐变起始点越靠近画布左侧。
right	Double	800	渐变效果的右侧边界位置，单位为像素（px）。此值表示渐变在画布右侧结束的位置，值越大，渐变结束点越靠近画布右侧。

ResponseDetail

参数	类型	示例	说明
logid	String	20241210152726467C48D89D6DB2****	本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此 logid 及错误码联系扣子团队获取帮助。详细说明可参考获取帮助和技术支持。

示例

请求示例

curl --location --request GET 'https://api.coze.cn/v1/bots/749865007353125***?is_published=true' \
--header 'Authorization: Bearer pat_OYDacMzM3WyOWV3Dtj2bHRMymzxP****' \
--header 'Content-Type: application/json'

返回示例

{
    "code": 0,
    "data": {
        "description": "***",
        "bot_mode": 0,
        "model_info": {
            "temperature": 0.8,
            "context_round": 3,
            "max_tokens": 4096,
            "model_id": "173752***",
            "model_name": "ep-20250122125445-ck9wp"
        },
        "knowledge": {
            "knowledge_infos": []
        },
        "bot_id": "7515437*****",
        "folder_id": "752316125533542***",
        "version": "",
        "voice_data_list": [],
        "plugin_info_list": [
            {
                "api_info_list": [
                    {
                        "description": "当你需要获取网页、pdf 内容时，使用此工具。可以获取url链接下的标题和内容。",
                        "api_id": "0",
                        "name": "browse"
                    },
                    {
                        "api_id": "0",
                        "name": "search",
                        "description": "搜索用户询问的内容"
                    }
                ],
                "plugin_id": "7372463719***",
                "name": "头条搜索",
                "description": "使用头条的搜索功能来阅读或搜索URL链接，由于个别网站自身站点限制，无法获取网页内容。",
                "icon_url": "https://example.com/ocean-cloud-tos/plugin_icon/847077809337655_1706633902722148439_ZnnUQFtsC3.png?lk3s=cd508e2b&x-expires=1752598956&x-signature=H9xqNxbMc*****"
            },
            {
                "icon_url": "https://example.com/ocean-cloud-tos/plugin_icon/default_icon.png?lk3s=cd508e2b&x-expires=1752598956&x-signature=O8qWv%2F5dCJq****",
                "api_info_list": [
                    {
                        "api_id": "0",
                        "name": "sousuo",
                        "description": "查询解析: 系统需要能够理解用户的查询意图，并将其转换为可执行的搜索指令。\n\n数据库: 一个包含学术资源的大型数据库，如期刊文章、会议论文、学位论文等。\n\n索引: 为了提高搜索效率，数据库中的信息需要被索引，以便快速检索。\n\n搜索算法: 算法需要能够根据相关性对搜索结果进行排序。\n\n过滤和排序: 用户应能够根据日期、作者、出版物、领域等标准过滤和排序结果。\n\n高级搜索选项: 允许用户使用布尔运算符（如AND, OR, NOT）进行更精确的搜索。\n\n摘要和引用: 为每个搜索结果提供简短的摘要和引用信息。\n\n全文访问: 如果可能，提供对全文的访问链接。\n\n个性化: 根据用户的历史搜索和偏好，提供个性化的搜索建议。\n\n反馈机制: 允许用户对搜索结果进行反馈，以改进搜索算法。\n\n安全性和隐私: 确保用户数据的安全，并尊重隐私。\n\n可扩展性: 系统应能够随着数据量的增加而扩展。\n\nAPI: 提供API接口，允许其他应用程序或服务集成搜索功能。\n\n多语言支持: 支持多种语言的搜索和结果展示。\n\n移动兼容性: 确保系统在移动设备上也能良好工作。\n\n辅助功能: 为有特殊需求的用户提供辅助功能，如屏幕阅读器兼容性。\n\n帮助和支持: 提供帮助文档和客户支持。"
                    }
                ],
                "plugin_id": "736618610612***",
                "name": "学术搜索",
                "description": "学术问题？来问我"
            }
        ],
        "shortcut_commands": [],
        "name": "owner_1",
        "owner_user_id": "3290203****",
        "prompt_info": {
            "prompt": ""
        },
        "onboarding_info": {
            "Prologue": "嗨，你好！我对各种新鲜事物都很了解哦。",
            "SuggestedQuestions": [
                "有啥新鲜好玩的地方推荐吗？",
                "最近有啥新奇的科技产品吗？",
                "哪里能体验到独特的新鲜事物？"
            ],
            "OnboardingMode": 2,
            "CustomizedOnboardingPrompt": "",
            "SuggestedQuestionsShowMode": 0
        },
        "workflow_info_list": [
            {
                "icon_url": "https://example.com/plugin_icon/workflow.png?lk3s=81d4c505&x-expires=1750010557&x-signature=D910MNbN%2F****",
                "id": "751616845608***",
                "name": "summarize_article_1_903",
                "description": "示例：总结提炼文章中的要点"
            }
        ],
        "voice_info_list": [],
        "default_user_input_type": "text",
        "background_image_info": {
            "web_background_image": {
                "theme_color": "",
                "gradient_position": {},
                "canvas_position": {},
                "origin_image_url": "",
                "image_url": ""
            },
            "mobile_background_image": {
                "origin_image_url": "",
                "image_url": "",
                "theme_color": "",
                "gradient_position": {},
                "canvas_position": {}
            }
        },
        "update_time": 1749994397,
        "icon_url": "https://example.com/FileBizType.BIZ_BOT_ICON/***.jpeg",
        "suggest_reply_info": {
            "reply_mode": "enable",
            "customized_prompt": ""
        },
        "variables": [],
        "create_time": 1749972247
    },
    "msg": "",
}

错误码

如果成功调用扣子编程的 API，返回信息中 code 字段为 0。如果状态码为其他值，则表示接口调用失败。此时 msg 字段中包含详细错误信息，你可以参考错误码文档查看对应的解决方法。

查看智能体列表

开启或关闭智能体多人协作

查看智能体配置

基础信息

请求参数

Header

Path

Query

返回参数

BotInfo

PromptInfo

PrefixPromptInfo

OnboardingInfoV2

PluginInfo

ApiInfo

ModelInfo

CommonKnowledge

KnowledgeInfo

Variable

MediaConfig

Voice

ShortcutCommandInfo

ShortcutCommandToolInfo

WorkflowInfo

BackgroundImageInfo

BackgroundImageDetail

CanvasPosition

GradientPosition

ResponseDetail

示例

请求示例

返回示例

错误码