开放对话 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 生成 + 输出安全脱敏。 支持多轮会话与流式输出。
| 请求字段 | 类型 | 说明 |
|---|---|---|
| message | string | 必填,用户消息 |
| kb_ids | string[] | 可选,覆盖智能体默认知识库 |
| system_prompt | string | 可选,覆盖智能体提示词 |
| session_id | string | 可选,多轮会话:携带同一 ID 即注入最近 6 轮历史(滑窗),缺省无状态 |
| stream | bool | 可选,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,次日/次月或升级套餐后恢复;控制台「套餐与配额」可看实时进度。
建议:客户端指数退避;高频场景联系平台调整配额。
错误码
| 状态码 | 含义 | 处理建议 |
|---|---|---|
| 400 | JSON 非法 / message 缺失 | 检查请求体 |
| 401 | X-API-Key 无效或已吊销 | 控制台重新签发 |
| 402 | 本月 tokens 配额已用尽 | 下月自动恢复 / 升级套餐 |
| 429 | 租户限流 | 退避重试 / 提升配额 |
| 503 | 模型服务暂不可用 | 稍后重试;持续出现联系平台 |
安全说明:输出经过平台安全策略脱敏;命中注入特征的输入会被拒答并转人工,
该行为在控制台「安全策略」可配置(平台级)。