AIPro开放接口

公共调用约定

客户通过 QuickBI OpenAPI 使用 AK/SK 签名调用。平台根据 AK 自动解析用户和组织身份，业务请求无需传 user_id、tenant_id，也无需了解 QBI 与 ABI 服务之间的内部认证机制。

除 SSE 接口外，响应统一使用以下结构：

{
  "success": true,
  "data": {},
  "message": null,
  "code": 200,
  "trace_id": "trace-id"
}

业务错误通常仍返回 HTTP 200，通过 success=false 和 code 表达；请求参数不合法由 FastAPI 返回 HTTP 422。

提交对话（异步）

• 接口路径： /openapi/v2/abi/chat/completions/async

• 请求方式：POST

• Content-Type： application/json

• 接口描述： 异步提交一条纯文本对话，立即返回会话 ID 与消息 ID。调用方随后通过 SSE 接口获取执行事件。

• 输入参数

  参数	数据类型	描述	是否必需
  message	String	用户消息，长度 1～10000	是
  session_id	String	已有会话 ID，长度不超过 36；不传则创建新会话	否
  model	String	租户可见的模型别名，长度不超过 64，例如 qwen3.7-plus、deepseek-v4-pro；空白按未传处理；mode=lite 时忽略	否
  mode	String	会话模式：standard=完整能力，lite=轻量问答；默认 standard；仅创建会话时生效	否
  options	Object	单轮能力开关对象，按轮生效（每轮请求需重新携带）。当前支持 enable_ask_user（Boolean）：false=本轮禁用澄清反问，AI 不再向用户发起澄清性反问、直接按最合理的默认假设继续执行；省略=服务端默认开启。传 true 不突破服务端限制（如 mode=lite 时恒为禁用）。未知键或取值类型错误返回 code=400	否

• 返回参数

  参数	数据类型	描述
  session_id	String	会话 ID
  conversation_id	String	本次对话消息 ID，用于连接 SSE

• 请求示例

  {
    "message": "分析本月销售额变化",
    "model": "qwen3.7-plus",
    "mode": "standard",
    "options": {
      "enable_ask_user": false
    }
  }

• 返回示例

  {
    "success": true,
    "data": {
      "session_id": "s1",
      "conversation_id": "c1"
    },
    "message": null,
    "code": 202,
    "trace_id": "t1"
  }

• 常见错误

  code	描述
  400	mode 非法、model 不在当前租户可见模型别名列表中，或 options 包含未知开关/取值类型错误
  403	无权访问传入的已有会话
  404	已有会话不存在
  429	当前用户 Credit 余额不足
  500/502	服务内部异常或下游 CodeAgent 调用失败

获取对话事件流（Query 形式）

• 接口路径： /openapi/v2/abi/chat/completions/async/stream

• 请求方式：GET

• 返回类型： text/event-stream

• 接口说明： 获取或续传异步对话事件。该固定路径适配 QuickBI 开放平台精确 URI 验签规则，是网关调用的推荐形式。

• 输入参数

  参数	位置	数据类型	描述	是否必需
  conversation_id	Query	String	对话消息 ID，长度 1～36	是
  last_event_id	Query	String	最后收到的 SSE 事件 ID，用于断点续传	否
  Last-Event-ID	Header	String	标准 SSE 续传游标；同时传入时优先级高于 last_event_id	否

• 返回 Header

  Header	描述
  X-Trace-Id	请求追踪 ID
  X-Conversation-Id	对话消息 ID
  Cache-Control	固定为 no-cache
  X-Accel-Buffering	固定为 no，禁止代理缓冲

• 调用示例

  GET /openapi/v2/abi/chat/completions/async/stream?conversation_id=c1
  Last-Event-ID: 1721990000000-5

• 返回示例

  id: 1721990000001-0
  data: {"type":"message.content","data":{"text":"销售额同比增长"}}

已完成的对话可从持久化记录重放；对话不存在或不属于当前用户时返回 code=404，执行中且 Redis 不可用时返回 code=503。

取消进行中的对话

• 接口路径： /openapi/v2/abi/chat/cancel

• 请求方式： POST

• Content-Type： application/json

• 接口说明： 取消指定会话中正在执行的对话，仅会话所有者可操作；没有执行中消息时按幂等成功处理。

• 输入参数

  参数	数据类型	描述	是否必需
  session_id	String	会话 ID，长度 1～36	是

• 请求示例

  {
    "session_id": "s1"
  }

• 返回示例

  {
    "success": true,
    "data": {
      "session_id": "s1"
    },
    "message": null,
    "code": 200,
    "trace_id": "t1"
  }

二、Agent 集成

该组接口面向外部 Agent / 对话系统，覆盖“找数据 → 接入资产 → 等待学习 → 对话问数 → 查询历史”的完整链路。平台根据客户 AK 自动解析调用用户和所属组织，调用方无需传用户或组织身份参数。所有 URI 均使用固定路径并仅使用 GET/POST。

上传并发布组件

• 接口路径： /openapi/v2/abi/components/upload

• 请求方式： POST

• Content-Type： multipart/form-data

• 接口说明： 创建并立即发布一个自定义组件。

• 请求参数

  参数	数据类型	描述	是否必需
  package	File	组件产物 ZIP，压缩包不超过 10MB；根目录或单层包装目录必须含 main.js、meta.js，main.css 可选	是
  name	String	组件名称，去除首尾空格后非空，最长 200，租户内唯一	是
  desc	String	组件描述，最长 200	否
  externalAssets	String	外部依赖 JSON 数组字符串；传入时覆盖 manifest 中的 externals	否
  sourceArchive	String	源码 ZIP 的 Base64，可带 data:*;base64, 前缀；解码后不超过 10MB	否
  thumbnail	File	缩略图，仅支持 png、jpg、jpeg、svg，不超过 200KB	否

• 返回参数

  参数	数据类型	描述
  componentId	String	组件 ID
  jsUrl	String	main.js 地址
  metaJsUrl	String	meta.js 地址
  cssUrl	String	main.css 地址，没有时为 null
  sourceArchiveUrl	String	源码归档地址
  thumbnailUrl	String	缩略图地址
  revision	String	当前版本号
  autoInstalled	Boolean	是否已自动安装

• 请求示例

  POST /openapi/v2/abi/components/upload
  Content-Type: multipart/form-data
  
  name=Sankey
  package=@sankey.zip
  thumbnail=@thumbnail.png

• 返回示例

  {
    "success": true,
    "data": {
      "componentId": "c1",
      "jsUrl": "/api/v2/abi/components/c1/assets?name=main.js&v=r1",
      "metaJsUrl": "/api/v2/abi/components/c1/assets?name=meta.js&v=r1",
      "cssUrl": null,
      "sourceArchiveUrl": null,
      "thumbnailUrl": null,
      "revision": "r1",
      "autoInstalled": true
    },
    "code": 200,
    "trace_id": "t1"
  }

更新组件

• 接口路径： /openapi/v2/abi/components/update

• 请求方式： POST

• Content-Type： multipart/form-data

• 接口说明： 部分更新已有组件；未传字段不修改。替换 package 时生成新 revision，单独修改元数据、源码归档或缩略图不变更 revision。

• 请求参数

  参数	数据类型	描述	是否必需
  component_id	String	组件 ID	是
  name	String	新组件名称，最长 200；空白表示不更新	否
  desc	String	新描述，最长 200；空字符串表示清空	否
  sourceArchive	String	源码 ZIP Base64	否
  package	File	新组件产物 ZIP，校验规则同上传接口	否
  thumbnail	File	新缩略图，校验规则同上传接口	否

• 返回参数：返回字段与上传接口基本一致，额外返回 revisionChanged 表示本次是否产生新版本。

• 代码示例

  POST /openapi/v2/abi/components/update
  Content-Type: multipart/form-data
  
  component_id=c1
  desc=更新后的组件描述

查询当前用户可用组件清单（不分页）

• 接口路径： /openapi/v2/abi/components/list

• 请求方式： GET

• 接口说明： 查询当前租户的组件管理列表。

• 返回参数：返回 items 和 total（total 等于 items 条数）。

• 代码示例

  GET /openapi/v2/abi/components/list?keyword=Sankey&page=1&page_size=20

查询组件详情

• 接口路径： /openapi/v2/abi/components/detail

• 请求方式： GET

• 请求参数

  参数	数据类型	描述	是否必需
  component_id	String	组件 ID	是

• 返回参数：返回 componentId、name、desc、metaJson、externalAssets、packageFilename、jsUrl、metaJsUrl、cssUrl、sourceArchiveUrl、thumbnailUrl、currentRevision、visibilityType、enabled、created_at、updated_at。

读取组件编译产物

• 接口路径： /openapi/v2/abi/components/asset

• 请求方式： GET

• 接口说明： 面向沙箱或个人 AK/SK 的 JSON 产物内容通道，读取编译产物文本。

• 请求参数

  参数	数据类型	描述	是否必需
  component_id	String	组件 ID，必须属于当前租户	是
  name	String	产物名，只允许 main.js、meta.js、main.css	是

• 返回参数：返回 name、content、contentType、revision。

• 请求示例

  GET /openapi/v2/abi/components/asset?component_id=c1&name=meta.js

• 返回示例

  {"success":true,"data":{"name":"meta.js","content":"{...}","contentType":"text/javascript;charset=utf-8","revision":"r1"},"code":200,"trace_id":"t1"}

删除组件

• 接口路径： /openapi/v2/abi/components/delete

• 请求方式： POST

• Content-Type： application/json

• 接口说明： 删除组件及其安装、可见范围记录；OSS 清理失败不阻断接口成功。

• 请求参数

  参数	数据类型	描述	是否必需
  component_id	String	组件 ID	是

• 请求示例

  {"component_id":"c1"}

• 返回示例

  {"success":true,"data":null,"message":null,"code":200,"trace_id":"t1"}

• 常见错误码

  code	描述
  400	ZIP、manifest、Base64、externalAssets 或缩略图校验失败
  403	当前用户无管理权限（上传、更新、删除）
  404	组件不存在或不属于当前租户
  409	组件名称在租户内重复
  500	数据库查询或保存失败
  502	OSS 中的文本产物不是合法 UTF-8
  503	对象存储不可用或写入失败

CreateTicket4AiPro：生成 AIPro 嵌入 Ticket（管理权限）

• POP 路径：/openapi/v2/pop/ticket/createTicket4AiPro

• 请求方式：POST

• Content-Type：application/x-www-form-urlencoded

• 接口说明：为已启用的 AIPro 嵌入配置签发免登 Ticket。签出的票据类型固定为 AI_PRO_TICKET(31)。

• 请求参数

  参数	数据类型	描述	是否必需
  aiProId	String	AIPro 嵌入配置 ID；配置须存在、属于当前组织且 status=1	是
  ticketNum	Int	票据可使用次数，默认 1，取值 1～99999	否
  userId	String	绑定访问用户的 QuickBI userId；与 accountName+accountType 二选一	条件必需
  accountName	String	绑定访问用户账号；userId 未传时配合 accountType 使用	条件必需
  accountType	Int	账号类型，须能映射到 QuickBI AccountTypeEnum	条件必需
  expireTime	Int	有效期，单位分钟，默认 240，必须大于 0	否
  systemUid	String	自定义系统标识，长度小于 150	否
  customParam	String	自定义透传参数，非空时必须为合法 JSON 字符串	否

  userId 优先于 accountName+accountType；两者都不传时默认绑定配置创建人。调用账号须为组织管理员或具备 COPILOT_ABI 功能与 COPILOT_ABI_MANAGE 操作权限的成员，与其它 AIPro 嵌入管理接口权限口径一致。

• 请求示例

  POST /openapi/v2/pop/ticket/createTicket4AiPro
  Content-Type: application/x-www-form-urlencoded
  
  aiProId=a1&ticketNum=1&expireTime=240

• 返回示例

  {
    "RequestId": "req-1",
    "Success": true,
    "Result": "generated-ticket"
  }

• 免登地址

  https://{QuickBI访问域名}/token3rd/ai/chat?accessTicket={accessTicket}&aiProId={aiProId}

  /token3rd/ai/chat 必须使用本接口签发的 31 类型票据。不要使用 create4Abi：该接口签发的是 ABI_ARTIFACT(28) 产物票，打开 AIPro 对话页会报 AE0580800019 禁止访问。

• 常见错误

  错误码	描述
  AE0566662010	配置不存在或不属于当前组织
  AE0566662011	嵌入配置已停用
  AE0530010025	ticketNum 超出允许范围
  AE0510000038	参数不合法
  AE0591000014	无法解析绑定用户

ModifyAiproEmbedConfig：新建/修改嵌入配置（管理权限）

• POP 路径：/openapi/v2/pop/aipro/modifyAiproEmbedConfig

• 请求方式：POST

• Content-Type：application/json

• 接口说明：aiProId 为空时新建配置，非空时部分更新已有配置。需组织管理员或具备 COPILOT_ABI 管理权限的账号调用。

• 请求参数

  参数	数据类型	描述	是否必需
  aiProId	String	配置 ID；不传或空白表示新建，非空表示修改	修改时是
  showName	String	配置名称；新建时必填且组织内唯一；修改时空白表示不更新	新建时是
  agentName	String	智能体昵称；新建默认“智能数据分析助手”	否
  chatHistoryStatus	Int	展示历史对话：1=展示，0=不展示；新建默认 1	否
  memoryEnabled	Int	启用记忆：1=开，0=关；新建默认 0	否
  uploadEnabled	Int	允许上传文件：1=开，0=关；新建默认 0	否
  config	String	前端保存的嵌入外观 JSON 字符串	否

  新建配置固定为 status=0（停用），本接口不支持修改 status；创建后需到嵌入配置管理页启用，才能签票。

• 请求示例

  {
    "showName": "客户门户",
    "agentName": "智能数据分析助手",
    "chatHistoryStatus": 1,
    "memoryEnabled": 0,
    "uploadEnabled": 0,
    "config": "{\"themes\":{\"type\":\"light\"}}"
  }

• 返回示例

  {
    "RequestId": "req-1",
    "Success": true,
    "Result": true
  }

• 常见错误码

  错误码	描述
  AE0510000005	新建时 showName 为空
  AE0566662010	修改的配置不存在或不属于当前组织
  AE0566662017	配置名称在组织内重复

QueryAiproEmbedConfig：查询嵌入配置（管理权限）

• POP 路径：/openapi/v2/pop/aipro/queryAiproEmbedConfig

• 请求方式：POST

• 接口说明：查询当前组织下的 AIPro 嵌入配置，按数据库 ID 倒序返回，最多 10000 条。需组织管理员或具备 COPILOT_ABI 管理权限的账号调用。

• 请求参数

  参数	数据类型	描述	是否必需
  keyword	String	按 showName 模糊搜索	否

• 返回参数

  参数	数据类型	描述
  aiProId	String	嵌入配置 ID，用于 CreateTicket4AiPro
  showName	String	配置名称
  agentName	String	智能体昵称
  status	Int	启停状态：1=启用，0=停用
  chatHistoryStatus	Int	展示历史对话：1=展示，0=不展示
  memoryEnabled	Int	启用记忆：1=开，0=关
  uploadEnabled	Int	允许上传文件：1=开，0=关
  config	String	嵌入外观配置 JSON 字符串
  createUser	String	创建人 ID
  createUserName	String	创建人昵称
  modifyUser	String	最近修改人 ID
  gmtCreate	Datetime	创建时间
  gmtModified	Datetime	修改时间

• 返回示例

  {
    "RequestId": "req-1",
    "Success": true,
    "Result": [
      {
        "aiProId": "a1",
        "showName": "客户门户",
        "agentName": "智能数据分析助手",
        "status": 1,
        "chatHistoryStatus": 1,
        "memoryEnabled": 0,
        "uploadEnabled": 0,
        "config": "{\"themes\":{\"type\":\"light\"}}",
        "createUser": "u1",
        "createUserName": "张三",
        "modifyUser": "u1",
        "gmtCreate": "2026-09-01 10:00:00",
        "gmtModified": "2026-09-01 10:00:00"
      }
    ]
  }

嵌入常见错误

创建产物

• 接口路径：/openapi/v2/abi/artifacts/create

• 请求方式： POST

• Content-Type：application/json

• 接口说明： 创建 AI 仪表板产物并落库，返回产物 ID 与版本号。产物内容随后可通过 content 接口读取、通过 embed-ticket 签发免登预览链接。

• 请求参数

  参数	数据类型	描述	是否必需
  artifact_type	String	产物类型	是
  title	String	产物标题，不能为空	是
  content	Object	产物内容对象，含 dsl 字段（DashboardSpec）	是
  session_id	String	会话 ID	否
  conversation_id	String	消息 ID	否

• 返回参数

  参数	数据类型	描述
  artifact_id	String	产物 ID
  draft_id	String	草稿 ID（二次编辑用）
  version	Int	当前版本号

• 请求示例

  {
    "artifact_type": "ai_dashboard",
    "title": "销售趋势看板",
    "content": {
  
      "dsl": {"type": "ai_dashboard", "title": "销售趋势看板", "charts": [ ]}
  
    }
  }

• 返回示例

  {
    "success": true,
    "data": {
      "artifact_id": "3f8e9b2a-...",
      "draft_id": "d7c1a5b3-...",
      "version": 1
    },
    "code": 200,
    "trace_id": "t1"
  }

读取产物内容（网关固定路径）

• 接口路径：/openapi/v2/abi/artifacts/content

• 请求方式： GET

• 接口说明： 按产物 ID 和版本号读取产物内容。网关验签精确匹配 URI，故 artifact_id 走 query 参数（不使用 RESTful 模板路径）。

• 请求参数

  参数	位置	数据类型	描述	是否必需
  artifact_id	Query	String	产物 ID	是
  version	Query	Int	指定版本号；未传返回最新版	否

• 返回参数

  参数	数据类型	描述
  artifact_id	String	产物 ID
  version	Int	当前版本号
  current_version	Int	最新版本号（version < current_version 表示本版本已不是最新）
  content	Object	产物内容
  created_at	String	创建时间
  updated_at	String	更新时间

• 代码示例

  GET /openapi/v2/abi/artifacts/content?artifact_id=a1&version=1

签发产物嵌入免登票据

• 接口路径：/openapi/v2/abi/artifacts/embed-ticket

• 请求方式： POST

• Content-Type：application/json

• 接口说明： 用 artifact_id 换取嵌入免登票据与 iframe 预览 URL。票据免登身份默认为调用 AK 对应的用户，可经 ticket_user_id 指定（需有产物权限）。

• 请求参数

  参数	数据类型	描述	是否必需
  artifact_id	String	产物 ID	是
  ticket_num	Int	票据可打开次数，默认 1	否
  expire_minutes	Int	有效期分钟数，默认 240 分钟	否
  ticket_user_id	String	指定绑定用户 ID（需有产物权限）	否
  watermark_param	String	水印参数 JSON	否
  global_param	String	全局透传参数 JSON	否

• 返回参数

  参数	数据类型	描述
  embed_url	String	嵌入预览 URL
  ticket	String	免登票据
  expire_at	String	过期时间

• 请求示例

  {
    "artifact_id": "a1",
    "ticket_num": 99999,
    "expire_minutes": 525600
  }

• 返回示例

  {
    "success": true,
    "data": {
      "embed_url": "https://bi.aliyun.com/token3rd/ai-dashboard/view/pc.htm?accessTicket=xxx&artifactId=a1",
      "ticket": "generated-ticket",
      "expire_at": "2027-09-10T12:00:00"
    },
    "code": 200,
    "trace_id": "t1"
  }

• 常见错误码

  code	描述
  400	参数校验失败
  403	当前用户无产物权限（或指定的 ticket_user_id 用户无权访问）
  404	产物不存在
  502	下游 QuickBI 签票失败

  嵌入预览链接通过 iframe 或可点击 URL 展示产物看板，可与三、嵌入集成的 AIPro 嵌入配合使用。