集成第三方 API

通过 API，可以读取外部系统的数据或调用其业务能力。Zion 会根据配置生成可绑定的入参和响应结构，使同一个 API 可以在页面、行为流或 AI Agent 中复用。

开始前

准备第三方服务提供的接口文档，并确认以下信息：

⚠️

如果请求需要不能暴露给客户端的 API Key、Token 或私钥，请从行为流调用该 API，并通过 Secret 绑定凭证。不要把敏感凭证绑定到页面或前端行为。

打开顶部的行为，进入 API，点击 添加配置，并填写便于识别的 API 名称。

操作类型决定 API 在编辑器中的主要用途：

操作类型	用途
查询	读取外部数据，可以配置为页面或列表的数据源
修改	执行创建、更新、删除或其他有副作用的请求，可以通过前端行为或行为流节点调用

查询型 API 还可以按接口能力配置分页方式、页码字段、每页数量字段和起始页码。

进入编辑状态后，选择请求方法并填写 URL。根据接口文档，在对应位置添加参数：

为每个字段设置名称、类型、是否必填以及调试时使用的值。Body 只能有一个根节点，可以继续添加对象字段或列表字段。

点击调试，为请求参数填写测试值，然后点击发送。确认请求内容、响应状态和响应数据符合第三方接口文档。

调试成功后进入高级：

API 将 2xx 响应归入成功结果，将 4xx、5xx 响应归入失败结果。调用方会根据这里保存的结构提供对应的数据绑定字段。

当响应字段不是直接可用的数据类型时，可以设置编码方式：

编码方式	适用情况
URL 媒体编码	字段是图片或其他媒体文件的 URL，需要转换为 Zion 媒体数据
Base64 媒体编码	字段是 Base64 媒体内容，需要解析并转换为 Zion 媒体数据
JSON 字符串编码	字段是经过转义的 JSON 字符串，需要解析为对象或列表

例如，接口可能返回：


{
  "profile": "{\"name\":\"Ada\",\"level\":3}"
}

将 profile 设置为 JSON 字符串编码 后，可以继续绑定其中的 name 和 level。

API 修改会自动保存，但需要发布后才会在运行环境生效。更新预览 和 同步变更 都会发布最新的 API、行为流和 AI Agent 等后端配置；更新预览还会更新前端预览内容。

修改已经被页面、行为流或 AI Agent 使用的入参和响应结构时，应同步检查所有调用方。

查询型 API 可以作为页面、列表等位置的数据源。选择目标 API，绑定其入参，并指定响应中作为数据源结果的字段。

如果接口支持分页，还需要根据 API 配置绑定页码、每页数量或加载更多相关参数。

修改型 API 可以从页面或组件调用：

在行为流中添加 API 节点，选择目标 API 并绑定入参。后续节点可以读取该 API 节点的成功结果；失败分支可以记录错误、重试或执行补偿逻辑。

API 节点从发起请求到接收完整响应的时长上限为 60 秒。其他超时规则请参阅搭建行为流。

在 AI Agent 的工具中添加 API，并为工具填写清晰的名称、用途和参数说明。模型会根据对话内容判断是否调用该工具。

涉及创建订单、修改数据等必须执行的业务步骤时，不应依赖模型自主选择工具。请将固定步骤放入行为流，并将该行为流作为工具。详见搭建 AI Agent。