百宝箱开放平台 ✖️API ✖️使用生成型智能体本文介绍了生成型智能体API的调用规范，包括请求地址、参数配置和返回结果

开发者通过调用本接口，可以在自有系统中使用生成型智能体，例如生成古诗、文章以及图片等内容。

前提条件

在调用本接口前，请先完成应用的发布。
若您需要通过本接口上传多模态文件，需要先开启应用配置中的多模态配置，再添加拥有多模态处理能力的大模型或插件。

请求地址

POST``https://api.tbox.cn/api/completion

请求头

参数名	是否必填	类型	说明	示例
Authorization	是	String	用于验证客户端身份的访问令牌，你可以在百宝箱中获取，获取方式可参见：授权管理。	`pat_2j4e******THUIVRH1`

请求参数

参数名	是否必填	类型	说明	示例
appId	是	String	应用 ID，需要通过 API 进行集成的应用 ID。	`202506e******00450562`
inputs	否	Object	智能体输入项。
userId	是	String	用户 ID，指使用智能体的用户 ID，需开发者自行定义与维护。	-
inputs.key	是	String	指在智能体输入项中自定义的 API 参数名。获取路径：生成型智能体配置页 > 输入项 > 目标参数 > API 参数名。
clientProperties	否	Object	系统及环境变量参数。如果工作流应用中，开启了“系统及环境信息”中的变量开关后，可进行传值。其中，参数名与 key 的对照关系如下：- 用户id：user_id

触发时间：time
坐标：pos
经度：pos_lng
纬度：pos_lat
运行环境：runtime_env
UA：user_agent
附加数据：_biz_params | - | | files | 否 | List | 文件列表，用于在图生图应用中上传图片文件。 | - | | >>type | 是 | Enum | 指上传的文件类型。枚举值包括：- 图像：IMAGE
音频：AUDIO
视频：VIDEO
文件：FILE | IMAGE | | >>fileId | 是 | String | 上传文件id，通过上传文件接口，完成文件上传后，在返回参数中获得。 | 202502********001001 | | stream | 否 | Boolean | 是否流式返回。- true：流式（默认值）
false：非流式 | true |

请求示例

支持用 curl 命令或编程语言（如 Python、Java 等）调用接口。以下是 curl 命令示例。

--location 'https://tdoraemonopen.cloud.alipay.com/api/completion' \
--header 'Authorization: {your_token}' \
--header 'Content-Type: application/json' \
--header 'Accept: text/event-stream' \
--data '{"appId":"xxxxx","inputs": {"key": "value"},"userId":"xxx"}'

返回参数

1. 流式返回（stream=true）

该接口返回的是基于 Server-Sent Events (SSE) 的事件流，包含多个事件类型。每个事件由 event 和 data 构成。

1.1. 通用字段

参数名	类型	说明	示例
id	String	事件唯一标识符，用于客户端追踪或幂等性处理	1
event	String	事件类型，表示当前消息类别	message
data	Object	消息主体数据对象	{}

1.2. data.payload 字段

说明：

需反序列化处理后查看。
基于 data.type 的不同，而展示不同的结构，下文将分别说明。

1.2.1. 当 data.type = chunk 时（核心关注内容）

参数名	类型	说明	示例
type	String	类型标识符，如 `chunk`	`"chunk"`
lane	String	流水线标识（默认为 `default`）	`"default"`
payload.text	String	实际输出的文本片段	`"日出照东方，光辉耀四方。"`

1.2.2. 当 data.type = header 时（一般情况下无需关心其中的内容）

参数名	类型	说明	示例
type	String	类型标识符，如 `header`	`"header"`
payload.requestId	String	请求唯一标识	`"b18ecc07-5db1-4c99-bab5-e56ddf12581f"`
payload.sessionId	String	会话 ID	`"20250522X9fe28738375"`
payload.mediaType	String	输出内容类型，如 `text`	`"text"`

1.2.3. 当 data.type = meta 时

字段名	类型	描述	示例值
type	String	事件类型，如 `meta`	`"meta"`
payload.event	String	子事件名称，如 `flow.graph.start`, `flow.node.start` 等	`"flow.graph.start"`
payload.entity	Object	节点实体信息（节点类型、ID、名称等）	`{ "node_type": "input", "node_id": "node-1" }`
payload.ext_data	Object	扩展数据，如输入参数、时间戳、模型名称等	`{ "start_time": 123456789, "model_name": "通义千问 • Max" }`

1.2.3.1. payload.ext_data（仅 payload.event = flow.node.end 事件有）

参数名	类型	说明	示例
ext_data.start_time	number (float)	节点开始时间戳（秒级）	1747918585.1008272
ext_data.end_time	number (float)	节点结束时间戳（秒级）	1747918585.1078308
ext_data.input_params(仅部分节点有)	JSON string	当前节点的输入参数	{"type":"json","value":...}
ext_data.query(仅部分节点有)	JSON string	用户输入查询内容	{"type":"text","value":"你好"}

1.2.3.2. ext_data.input_params.value

参数名	类型	说明	示例
input_params.value.conversationId	string	当前会话ID	2025052****738375
input_params.value.requestId	string	请求唯一标识	b18ecc07-5db1-********e56ddf12581f
input_params.value.historyChat	array	历史对话记录（空数组表示无历史）	[]

1.2.3.3. ext_data.query.value

参数名	类型	说明	示例
query.value	string	用户实际输入内容	-

1.2.3.4. payload.entity（仅节点开始事件有）

参数名	类型	说明	示例
entity.node_type	string	节点类型，表示该节点功能	input, text-completion, output
entity.execute_id	string	节点执行顺序编号（字符串格式）	0
entity.node_name	string	节点显示名称	用户输入
entity.node_id	string	节点唯一标识符	node-1

1.3. 事件枚举

事件名称	说明
flow.graph.start	流程开始执行
flow.node.start	节点开始执行
flow.node.end	节点执行结束
flow.graph.end	流程执行结束

1.4. 返回示例

id:1
event:message
data:{"payload":"{"ext_data":{},"event":"flow.graph.start"}","type":"meta"}

id:2
event:message
data:{"payload":"{"event":"flow.node.start","entity":{"node_type":"input","execute_id":"0","node_name":"用户输入","node_id":"node-1"}}","type":"meta"}

id:3
event:message
data:{"payload":"{"ext_data":{"start_time":1747918585.1008272,"input_params":{"type":"json","value":{"conversationId":"20250522X9fe28738375","requestId":"b18ecc07-5db1-4c99-bab5-e56ddf12581f","title":"太阳","historyChat":[]}},"query":{"type":"text","value":""},"end_time":1747918585.1078308},"event":"flow.node.end","entity":{"node_type":"input","execute_id":"0","node_name":"用户输入","node_id":"node-1"}}","type":"meta"}

id:4
event:message
data:{"payload":"{"event":"flow.node.start","entity":{"node_type":"text-completion","execute_id":"1","node_name":"模型推理","node_id":"node-2"}}","type":"meta"}

id:5
event:message
data:{"payload":"{"event":"flow.node.start","entity":{"node_type":"output","execute_id":"2","node_name":"输出内容","node_id":"node-3"}}","type":"meta"}

id:6
event:message
data:{"entity":{"node_type":"output","execute_id":"2","node_name":"输出内容","node_id":"node-3"},"lane":"default","payload":"{"extraParams":{},"mediaType":"text","requestId":"b18ecc07-5db1-4c99-bab5-e56ddf12581f","sessionId":"20250522X9fe28738375"}","type":"header"}

id:7
event:message
data:{"lane":"default","payload":"{"text":"日"}","type":"chunk"}

id:8
event:message
data:{"lane":"default","payload":"{"text":"出"}","type":"chunk"}

id:9
event:message
data:{"lane":"default","payload":"{"text":"照"}","type":"chunk"}

id:10
event:message
data:{"lane":"default","payload":"{"text":"东方，光辉耀"}","type":"chunk"}

id:11
event:message
data:{"lane":"default","payload":"{"text":"四方。\n炎炎热"}","type":"chunk"}

id:12
event:message
data:{"lane":"default","payload":"{"text":"如炬，万物"}","type":"chunk"}

id:13
event:message
data:{"lane":"default","payload":"{"text":"得生长。"}","type":"chunk"}

id:14
event:message
data:{"payload":"{"ext_data":{"run_id":"653a76e3dca44d7e9478fd728de7315f","usage":{"total_tokens":0,"output_tokens":0,"input_tokens":0}},"event":"flow.node.llm.end","entity":{"node_type":"text-completion","execute_id":"1","group_id":0,"parent_execute_id":"1","node_name":"模型推理","node_id":"node-2"}}","type":"meta"}

id:15
event:message
data:{"payload":"{"ext_data":{"start_time":1747918585.114248,"model_name":"通义千问 • Max","output_type":"text","output_result":"日出照东方，光辉耀四方。\n炎炎热如炬，万物得生长。","complete_time":1747918585.2104874,"input_params":{"type":"json","value":{"conversationId":"20250522X9fe28738375","requestId":"b18ecc07-5db1-4c99-bab5-e56ddf12581f","title":"太阳","historyChat":[]}},"output_result_length":25,"input_prompt_length":0,"end_time":1747918588.0741422},"event":"flow.node.end","entity":{"node_type":"text-completion","execute_id":"1","node_name":"模型推理","node_id":"node-2"}}","type":"meta"}

id:16
event:message
data:{"payload":"{"ext_data":{"start_time":1747918585.2311532,"output_result_length":25,"end_time":1747918588.0837722},"event":"flow.node.end","entity":{"node_type":"output","execute_id":"2","node_name":"输出内容","node_id":"node-3"}}","type":"meta"}

id:17
event:message
data:{"payload":"{"ext_data":{"start_time":1747918585.0840373,"end_time":1747918588.0975933},"event":"flow.graph.end"}","type":"meta"}

id:18
event:end
data:{"type":"end"}

说明：

要获取大模型实际的回复内容，需要过滤event=message，同时type=chunk类型的消息。
payload字段中的 text 即为生成的内容，例如在上述示例中，经过拼接得到的内容为“日出照东方....”。

2. 非流式返回（stream=false）

2.1. 通用参数

参数名	类型	说明
errorCode	String	错误码，"0" 表示成功。
errorMsg	String	错误信息。
data	List	返回结果。
traceId	String	traceId，用于排查问题。

2.2. CompletionResponse 参数

参数名	类型	说明	示例
requestId	string	请求ID	b18ecc07-5db1-********e56ddf12581f
result	list	返回结果

2.3. Answer 参数

参数名	类型	说明	示例
extraParams	object	额外输出参数	{}
mediaType	string	输出的内容类型	text/image
chunk	json-string	输出内容，根据 mediaType 有不同的结构：- 当 mediaType=text：chunk 直接表示输出的文本内容；

当 mediaType=image：chunk 返回内容需要反序列化，其中 url 字段表示返回的图片 url 集合。 | - mediaType=text，chunk = "你好，有什么可以帮助你"
mediaType=image，chunk = "{"url":["mdn.alipayobjects.com/cto_doraemo…"]}" |

常见问题

1. 接口提示：“未检测到授权令牌，请参考百宝箱 SDK 接入文档完成授权令牌的申请和配置”

在使用百宝箱 OpenAPI 时，在 HTTP Header 中必须传入 Authorization 参数。获取方式请参见：授权管理。

2. 接口提示：“授权令牌无效，请校验是否输入了有效令牌或配置新令牌”

传入的令牌不正确，请确认后重试。

3. 接口提示：“授权令牌已失效，请前往百宝箱开放平台申请新令牌并更新到调用配置中”

令牌被删除或被关闭，请根据授权管理指引，前往授权管理页确认令牌状态。

4. 接口提示：“UserId 不能为空，请检查调用参数。”

调用百宝箱OpenAPI时，userId 为必填字段，请传入后重试。

5. 接口提示：“应用访问受阻，当前授权令牌无权限访问该应用。”

个人令牌按租户空间维度生效，请确认填入的令牌 token 与应用所在空间是否匹配。

6. 接口提示：“当前传入的conversationId：xx 记录对应的appId：xx 与传入值的appId值：xx 不一致”

多轮对话 id 与 appid 存在绑定关系，需将 appid 参数值替换为提示中对应的 appid 后重试。

7. 接口提示：“ConversationId 无效，请确认是否按照 SDK 指引正确传入。”

根据对话的类型可以分为两种情况：

新开对话，无需传入 ConversationId。
多轮对话，需传入接口嗲用返回的 ConversationId。

8. 接口提示：“当前传入的requestId：xx 记录对应的appId：xx 与传入值的appId值：xx 不一致”

requestId 与 appid 存在绑定关系，传入的值与实际不一致。请替换为提示中的对应的内容。