开放对话 API

Base URL:https://openagent-os.com | 鉴权:X-API-Key | 格式:JSON | OpenAI 风格

鉴权

控制台「API 密钥」签发,形如 oas_…。secret 仅创建时显示一次, 请立即保存;吊销即时生效。所有请求头携带:

X-API-Key: $OA_KEY

POST /open/v1/chat

一次调用 = 租户智能体配置(提示词 + 知识库检索引用)+ LLM 生成 + 输出安全脱敏。 支持多轮会话与流式输出。

请求字段类型说明
messagestring必填,用户消息
kb_idsstring[]可选,覆盖智能体默认知识库
system_promptstring可选,覆盖智能体提示词
session_idstring可选,多轮会话:携带同一 ID 即注入最近 6 轮历史(滑窗),缺省无状态
streambool可选,true 时以 SSE 返回 OpenAI chunk 格式(data: {…delta…} → data: [DONE])
curl -s https://openagent-os.com/open/v1/chat \
  -H "X-API-Key: $OA_KEY" -H "Content-Type: application/json" \
  -d '{"message": "织唛和印唛有什么区别?"}'

响应:

{
  "answer": "…正文…[1]",
  "citations": [{"citation": "[1]", "doc": "faq.md", "page": 1}],
  "tenant_id": "租户ID(计费归集)",
  "session_id": "回显(未传为 null)"
}

流式响应(stream:true):

data: {"choices":[{"delta":{"role":"assistant"}}]}
data: {"choices":[{"delta":{"content":"织唛是…"}}]}
data: {"choices":[{"delta":{},"finish_reason":"stop"}]}
data: [DONE]

GET /open/v1/models

OpenAI 兼容模型清单(供 SDK/探活/下拉选择):

curl -s https://openagent-os.com/open/v1/models -H "X-API-Key: $OA_KEY"
# → {"object":"list","data":[{"id":"…","object":"model","owned_by":"…"}],"tenant_id":"…"}

限流与配额

频率:每租户每分钟 30 次(默认,可按租户调整),超限 429。 用量:每租户每月 tokens 配额(免费版 10 万,见定价), 超限返回 402,次日/次月或升级套餐后恢复;控制台「套餐与配额」可看实时进度。 建议:客户端指数退避;高频场景联系平台调整配额。

错误码

状态码含义处理建议
400JSON 非法 / message 缺失检查请求体
401X-API-Key 无效或已吊销控制台重新签发
402本月 tokens 配额已用尽下月自动恢复 / 升级套餐
429租户限流退避重试 / 提升配额
503模型服务暂不可用稍后重试;持续出现联系平台
安全说明:输出经过平台安全策略脱敏;命中注入特征的输入会被拒答并转人工, 该行为在控制台「安全策略」可配置(平台级)。