开发文档Chat API

把Studio接入企业现有系统

企业后端通过兼容OpenAI的Chat API调用Studio。Studio根据可信身份组合业务数据、语义检索、知识和工具，再将回答与业务依据返回原有应用。

快速开始
请求协议
错误处理

POST /v1/chat/completions

流式响应

curl https://<your-id>.api.strcpy.cn/v1/chat/completions \
  -H "Authorization: Bearer $STUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-UserId: customer-10086" \
  -d '{
    "model": "model-for-fruit",
    "stream": true,
    "messages": [
      {"role": "user", "content": "查询我的订单状态"}
    ]
  }'

快速开始

从一个企业应用入口和一条可验证的业务问题开始，先跑通身份、数据与回答链路，再逐步扩展知识和工具。

准备企业空间
创建企业账户，在后台生成API Key。API Key只保存在企业后端。
选择模型
请求中填写model-for-fruit即使用平台模型，费用从套餐额度扣除；也可以在后台添加自有模型的网关、API Key与模型标识。
配置业务能力
连接数据源，定义数据集，并按场景配置知识、检索和工具。
建立可信身份
由企业后端认证用户，并在X-UserId请求头中传递最终用户标识。
发送首个请求
使用企业调用地址和API Key调用/v1/chat/completions。
核对返回结果
检查回答、业务标识、来源和请求ID，再接入现有前端。

调用地址中的<your-id>是每个企业账户的唯一标识，请替换为企业账户提供的实际子域名。

请求协议

Chat API使用兼容OpenAI的消息结构，支持连续对话与流式响应。企业服务端保存Studio API Key，浏览器和最终用户不直接持有平台凭据。

`Endpoint`	路径`POST /v1/chat/completions`
`Authorization`	必填`Bearer <STUDIO_API_KEY>`，API Key在后台生成。
`X-UserId`	必填最终用户标识，由企业后端认证后填写。
`model`	string填写`model-for-fruit`使用平台模型，调用费用从套餐额度扣除；填写后台配置的自有模型标识，则使用该模型。
`messages`	array兼容system、user、assistant与tool消息结构。
`stream`	可选设为`true`时通过Server-Sent Events持续返回生成内容。

API Key只保存在企业服务端。商城、客服和内部系统的浏览器端应调用企业自己的后端，再由企业后端访问Studio。

可信身份映射

企业后端在X-UserId请求头中传递经过认证的最终用户标识。管理员还可以在Studio中配置Header解析规则，把其他请求头解析为数据查询、检索和工具调用可使用的变量。

租户身份由API Key与服务端认证确定，不接受客户端任意声明租户。
最终用户身份由企业后端认证后放在X-UserId中传递，用于区分会话，也可作为变量使用。
业务权限由企业系统、数据源权限和管理员配置的查询条件共同控制。

响应结构

非流式响应沿用兼容OpenAI的回答结构，并可在扩展字段中返回业务标识、依据和请求ID，便于企业应用继续处理和排查问题。

application/json

响应示例

{
  "id": "chatcmpl_01J...",
  "choices": [{
    "message": {"role": "assistant", "content": "订单已进入配送环节。"}
  }],
  "studio": {
    "business_refs": [{"type": "order", "id": "O-20260928"}],
    "request_id": "req_01J..."
  }
}

业务扩展字段随实际调用能力返回。企业应用应以业务标识继续查询或执行动作，不从自然语言回答中反向解析订单号或商品ID。

流式响应

流式模式使用Server-Sent Events返回内容增量。企业后端可将增量转发给现有前端，也可以在服务端汇总完整回答后再返回。

data: response.chunk

SSE

data: {"choices":[{"delta":{"content":"订单"}}]}
data: {"choices":[{"delta":{"content":"已进入配送环节"}}]}
data: [DONE]

数据变更推送

企业系统的商品、订单等数据变化后，可以向Studio推送一条事件，让对应数据集立即同步，不必等到下一次定时同步。事件只携带库、表和记录ID，不含业务数据本身，Studio会自行回源查询最新内容。

`Endpoint`	路径`POST /v1/events`
`Authorization`	必填`Bearer <STUDIO_API_KEY>`，须使用用途为“事件推送”的API Key。该Key只能调用本接口，对话Key也不能推送事件。
`database`	必填源库名，须与数据源连接的库名一致。
`table`	必填发生变化的源表名，须已在数据集的“变更触发”中配置监听。
`ids`	array变化记录的ID，字符串或数字，一次1到5000个。新增、修改、删除都用同样的方式推送。

POST /v1/events

返回 202

curl https://<your-id>.api.strcpy.cn/v1/events \
  -H "Authorization: Bearer $STUDIO_EVENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"database":"shop","table":"products","ids":["P1001","P1002"]}'

HTTP 202 {"accepted": true, "matchedDatasets": 1}

合并执行事件先进入队列，安静5秒后合并成一次同步，最久等待30秒；同一批内重复的ID只处理一次。
精确同步数据集为该表指定了“记录ID对应的字段”时，只查询并更新这几条；源表里已查不到的ID视为已删除，对应数据和向量一并移除。未指定字段，或ID数量过多时，退化为一次增量同步。
接收即返回202只表示事件已接收，matchedDatasets为命中的数据集数量，为0表示库表没有被任何数据集监听。同步结果在后台“数据同步”页查看。
兜底事件暂存在服务内存中，服务重启可能丢失最近30秒内尚未执行的事件。建议同时开启定时同步作为兜底。

推送事件的API Key同样只保存在企业服务端，请在后台API Key页面签发时选择用途“事件推送”。

错误处理

企业后端应根据HTTP状态码区分请求内容、身份权限、用量限制和临时服务异常，并记录响应中的请求ID。

400	请求结构或参数不符合协议。检查消息、模型标识和Header格式。
401	API Key缺失、无效或已失效。不要在浏览器端重试或暴露密钥。
403	当前企业或最终用户无权访问目标能力或数据范围；或API Key用途不符，例如用对话Key推送事件，或用事件Key调用对话。
429	达到调用频率、并发或可用额度限制。按响应提示等待或调整账户设置。
5xx	服务暂时不可用。使用请求ID排查，并采用有限次数的退避重试。

生产接入检查

身份在企业后端完成登录认证和最终用户映射，不让浏览器直接声明可信身份。
密钥API Key保存在服务端密钥管理环境中，不写入前端代码和公开仓库。
数据使用只读数据源账号，按业务表结构配置查询条件与资源限制。
网络数据源须为公网可访问的MySQL，平台不连接内网与本机地址；传输默认加密，可按数据源选择是否校验证书。
验收使用约定业务问题核对查询结果、业务标识、权限范围和失败处理。
观测记录请求标识、耗时和错误信息，避免在日志中输出模型密钥与敏感业务内容。

联系销售获取报价

没有开发团队？可以由我们完成对接，按范围单独报价。