获取卡片智能洞察

8.4.0 入参、出参补充说明

本接口生成指定卡片的智能洞察。目标卡片由 URL 中的 cdId 决定；先按账号同步令牌确定租户，再选择本次调用用户并校验其卡片读取权限。模型服务须已配置并启用。

调用身份与参数

token 放在 JSON 请求体中，使用开放平台设置中的账号同步令牌。账号同步通道须启用，请求来源 IP 须符合配置的白名单。

loginId 与 uId 同时传入时优先使用 loginId；两者均不传时使用该租户管理员。指定的账号无法找到时会报错，不会自动改用另一个身份。

locale 未传时按系统默认语言策略确定，并非固定使用 zh-CN；海外功能开启时采用 en-US，其他情况采用配置的默认语言，配置为空时回退到 zh-CN。

selectorValues 中每项包含 selectorId 和字符串数组 defaultValue；筛选器与取值应使用目标页面、卡片的真实配置。

pgId 用于传递页面上下文，不会替代路径 cdId。后端请求模型允许省略该字段；页面上下文的具体使用由洞察服务处理。

prompt 的输出要求、洞察思路、业务知识作为本次提示配置传入；与已保存配置的合并方式由洞察服务决定，不承诺一律追加或整体覆盖。

stream 默认 true；temperature 默认 0。温度的可接受范围取决于配置的模型服务，此接口未设置统一范围。

响应读取方式

stream=true 接收 text/event-stream 事件流；stream=false 等待模型返回后接收普通响应。此接口不返回供客户端轮询的任务 ID。

模型成功响应不增加 result/response 包装。非流式模式直接返回模型服务的响应正文或缓存正文；现有 JSON 结构为 OpenAI 兼容格式示例，其他供应商可能不同。

流式模式按 data: 事件分段读取，不能把整个响应作为单个 JSON 解析。OpenAI 兼容流通常通过 choices[].delta.content 返回正文增量；供应商字段不会被统一转换。注释行作为 SSE 注释转发。

正常读取结束或缓存回放结束时，后端补发 [DONE]。该标记仅表示流结束，不保证正文非空或业务成功。客户端应同时检查错误事件、实际正文、模型结束原因及连接结束状态。

流建立后，上游错误可能通过 HTTP 200 下的 data: 错误事件返回，例如 {"error":"Request failed with status 429"}，之后仍可能出现 [DONE]。本地异常会尝试发送含 error 信息的数据并结束；异常或超时不能保证还出现 [DONE]。

非流式上游成功或缓存命中时，响应为 HTTP 200、application/json，正文保持模型原始内容。上游非 200 会转换为 HTTP 500 并返回上游错误正文；本地异常也可能返回 HTTP 500，错误正文及 Content-Type 不保证与成功结构相同。

鉴权、权限校验或洞察准备阶段失败时，可能返回平台普通错误响应；不能假定所有错误都采用 SSE 格式。连接超时也可能直接结束流。

以下是 OpenAI 兼容服务的流式格式示意，具体数据字段以实际模型为准：

data: {"choices":[{"index":0,"delta":{"content":"洞察内容片段"}}]}

data: [DONE]

接口简介

如果指定了具体的用户信息，将以特定的用户名义（数据权限）获取卡片智能洞察。
特别说明：
① 该接口为限时免费API接口。不排除未来额外收费可能。

请求参数

Path 参数

Body 参数application/json

示例

{
    "token": "string",
    "loginId": "string",
    "uId": "string",
    "locale": "string",
    "selectorValues": [
        {
            "selectorId": "string",
            "defaultValue": [
                "string"
            ]
        }
    ],
    "prompt": {
        "requirements": "string",
        "analysis": "string",
        "knowledge": "string"
    },
    "stream": true,
    "temperature": 0,
    "pgId": "string"
}

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200成功

text/event-stream

流式响应：stream 默认 true，响应 Content-Type 为 text/event-stream，后端禁用 Nginx 缓冲并返回 SSE，不增加 result/response 包装。应逐条处理 data: 事件、错误信息及结束状态，不能把整段事件流按单个 JSON 解析。事件 JSON 字段随所配置模型服务而变化；[DONE] 由后端在读取完成或缓存回放结束时补发，不能作为洞察正文生成成功的唯一依据。

Body