AI 助理
备案控制台
开发者社区 物联网 行业解决方案 文章 正文

百宝箱开放平台 ✖️ 使用生成型智能体

2025-10-20 322
版权
版权声明：
本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写 侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
简介： 开发者通过调用本接口，可以在自有系统中使用生成型智能体，例如生成古诗、文章以及图片等内容。

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

前提条件

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

请求地址

POSThttps://api.tbox.cn/api/completion

请求头

参数名

是否必填

类型

说明

示例

Authorization

是

String

用于验证客户端身份的访问令牌，你可以在百宝箱中获取，获取方式可参见：授权管理。

pat_2j4e******THUIVRH1

请求参数

参数名

是否必填

类型

说明

示例

appId

是

String

应用 ID，需要通过 API 进行集成的应用 ID。获取方式可参见：获取AppID。

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<File>

文件列表，用于在图生图应用中上传图片文件。

-

>>type

是

Enum<String>

指上传的文件类型。枚举值包括：

  • 图像：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<CompletionResponse>

返回结果。

traceId

String

traceId，用于排查问题。

2.2. CompletionResponse 参数

参数名

类型

说明

示例

requestId

string

请求ID

b18ecc07-5db1-********e56ddf12581f

result

list<Answer>

返回结果

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\":[\"https://mdn.alipayobjects.com/cto_doraemon/afts/img/iVe7Q6mHhpIAAAAAAAAAAAAAehe3AQBr/original\"]}"

常见问题

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 存在绑定关系，传入的值与实际不一致。请替换为提示中的对应的内容。




文章标签：
API
数据格式
开发者
JSON
开发工具
蚂蚁百宝箱
目录
相关文章
阿里云云原生
|
1月前
|
人工智能 运维 Serverless
函数计算 × MSE Nacos : 轻松托管你的 MCP Server
本文将通过一个具体案例，演示如何基于 MCP Python SDK 开发一个标准的 MCP Server，并将其部署至函数计算。在不修改任何业务代码的前提下，通过控制台简单配置，即可实现该服务自动注册至 MSE Nacos 企业版，并支持后续的动态更新与统一管理。
阿里云云原生
526 42
JJLIN距离
|
1月前
|
存储 机器学习/深度学习 人工智能
大模型微调技术：LoRA原理与实践
本文深入解析大语言模型微调中的关键技术——低秩自适应（LoRA）。通过分析全参数微调的计算瓶颈，详细阐述LoRA的数学原理、实现机制和优势特点。文章包含完整的PyTorch实现代码、性能对比实验以及实际应用场景，为开发者提供高效微调大模型的实践指南。
JJLIN距离
1448 2
Database-Learning-helper
|
机器学习/深度学习 人工智能 自然语言处理
如何构建企业级数据智能体：Data Agent 开发实践
本篇将介绍DMS的一款数据分析智能体（Data Agent for Analytics ）产品的技术思考和实践。Data Agent for Analytics 定位为一款企业级数据分析智能体， 基于Agentic AI 技术，帮助用户查数据、做分析、生成报告、深入洞察。
Database-Learning-helper
1190 7
kde
|
1月前
|
存储 搜索推荐 数据库
🚀 RAGFlow Docker 部署全流程教程
RAGFlow是开源的下一代RAG系统，融合向量数据库与大模型，支持全文检索、插件化引擎切换，适用于企业知识库、智能客服等场景。支持Docker一键部署，提供轻量与完整版本，助力高效搭建私有化AI问答平台。
kde
1463 8
阿里云云原生
|
1月前
|
人工智能 监控 Java
零代码改造 + 全链路追踪！Spring AI 最新可观测性详细解读
Spring AI Alibaba 通过集成 OpenTelemetry 实现可观测性，支持框架原生和无侵入探针两种方式。原生方案依赖 Micrometer 自动埋点，适用于快速接入；无侵入探针基于 LoongSuite 商业版，无需修改代码即可采集标准 OTLP 数据，解决了原生方案扩展性差、调用链易断链等问题。未来将开源无侵入探针方案，整合至 AgentScope Studio，并进一步增强多 Agent 场景下的观测能力。
阿里云云原生
1286 31
阿里云云原生
|
30天前
|
人工智能 运维 Java
Spring AI Alibaba Admin 开源！以数据为中心的 Agent 开发平台
Spring AI Alibaba Admin 正式发布！一站式实现 Prompt 管理、动态热更新、评测集构建、自动化评估与全链路可观测，助力企业高效构建可信赖的 AI Agent 应用。开源共建，现已上线！
阿里云云原生
2591 40
蚂蚁百宝箱
|
13天前
|
人工智能 搜索推荐 API
蚂蚁百宝箱联手深铁打造全国首个地铁 AI 智能体「深铁宝」：你的全能城市向导来啦~
蚂蚁百宝箱联合深铁集团、深圳通推出全国首个“公共出行+城市服务”AI智能体「深铁宝」，上线于深圳地铁、深圳通及支付宝APP，实现一句话直达、秒级响应的智慧出行体验，涵盖出行规划、乘车码快捷调取、周边生活服务推荐等一站式功能，助力城市交通与服务数字化升级。
蚂蚁百宝箱
184 30