指南

简介

欢迎使用 Zenative OpenAPI！本指南将帮助你快速上手并高效集成我们的 API。请仔细阅读下文，了解认证方式、请求与响应格式、错误处理等核心内容。

认证

API 采用 OAuth 2.0 Client Credentials Grant（客户端凭证授权）方式进行认证。你需要通过 ClientId 和 ClientSecret 获取 AccessToken。

获取凭证：在管理后台获取 ClientId 和 ClientSecret，请妥善保管密钥信息。
申请 Access Token：向以下地址发送 POST 请求：
- URL: https://app.zenativeai.com/connect/token
- Headers:
  - Content-Type: application/x-www-form-urlencoded
- Body（表单格式）:
  - grant_type=client_credentials
  - client_id=YOUR_CLIENT_ID
  - client_secret=YOUR_CLIENT_SECRET
获取 Access Token：请求成功后，将收到包含 access_token 及有效期（秒）的 JSON 响应。
json
```
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600
}
```
使用 Access Token：在后续 API 请求的 Authorization 头中添加 Bearer YOUR_ACCESS_TOKEN。

Access Token 有效期有限，建议在过期前或收到 401 Unauthorized 时自动刷新。

请务必妥善保管 ClientId 和 ClientSecret，避免泄露到前端或不安全环境。

请求方式

API 基础地址

所有接口统一以如下地址为前缀：

https://app.zenativeai.com/api/platform

请求方法

支持标准 HTTP 方法：

GET：查询数据
POST：新增数据
PUT：更新数据
DELETE：删除数据

请求头

除认证信息外，常用请求头包括：

Content-Type：如为 POST、PUT、PATCH，一般为 application/json
Accept：期望返回的数据格式，通常为 application/json

请求参数

路径参数：直接写在 URL 路径中，如 /api/platform/chat/history/chatuser
查询参数：以 ? 追加在 URL 后，如 /api/platform/chat/history/chatuser?sessionId={sessions}
请求体：POST、PUT、PATCH 请求时，数据一般以 JSON 格式放在请求体

具体参数要求请参考各接口文档。

响应

状态码

接口返回标准 HTTP 状态码：

200 OK：请求成功
204 No Content：操作成功，无返回内容（如删除）
400 Bad Request：请求有误（如参数错误）

响应格式

成功时（2xx）返回 JSON 数据，出错时（4xx）也会返回 JSON，并包含详细错误信息。

成功示例（GET /api/platform/knowledge/query/{knowledgebaseId}）：

json

[
  {
    "score": 0.399245607763001,
    "id": "1355084446436425728",
    "byteSize": 221,
    "context": "知识点内容",
    "tagData": []
  }
]

错误示例（POST /api/platform/chat/history）：

json

{
  "data": {
    "model": [
      "The model field is required."
    ],
    "$.sendTime": [
      "Invalid token type String for DateTime conversion."
    ]
  },
  "code": "INVALID_MODEL",
  "msg": "invalid model"
}

错误处理

如遇请求失败，请关注状态码及响应体中的 code、msg 和 data 字段，便于快速定位问题。

若返回 500 Internal Server Error，说明服务端出现异常，请及时联系我们协助处理。

限流

为保障服务稳定，API 实施了限流策略：

每个 ClientId 每分钟最多 1000 次请求
超出配额时，接口会返回 429 Too Many Requests
响应头可能包含 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 等字段，方便你监控当前配额

建议应用侧做好限流处理，比如指数退避重试等。

联系我们

如有疑问或遇到问题，欢迎随时通过 support@zenative.ai 联系我们。

指南 ​

简介 ​

认证 ​

请求方式 ​

API 基础地址 ​

请求方法 ​

请求头 ​

请求参数 ​

响应 ​

状态码 ​

响应格式 ​

错误处理 ​

限流 ​

联系我们 ​

指南

简介

认证