DEVELOPER

超级大脑 Open API

通过 RESTful API 将 AI 知识能力集成到你的现有系统。支持知识库管理、智能问答、文档上传、知识图谱等核心功能。

QUICK START

快速开始

三步即可开始使用超级大脑 API

在线调试 · 打开客户端 API 文档

1

获取 API Key

立即入驻后,在管理后台的「开发者设置」中创建 API Key。

Authorization: Bearer sk-xxxx
2

发起请求

所有 API 均通过 HTTPS 调用,请求头需携带 API Key 进行鉴权。

https://api.super-brain.cn/v1
3

处理响应

统一 JSON 格式响应,包含 code、message、data 三个标准字段。

{"code":0,"data":{...}}
POST /v1/auth/token

获取访问令牌

使用 API Key 换取访问令牌(Access Token)。令牌有效期为 2 小时,过期后需重新获取。

参数名类型必填说明
api_keystring在管理后台获取的 API Key
api_secretstring对应的 API Secret
curl -X POST https://api.super-brain.cn/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key":"sk-xxxx","api_secret":"your-secret"}'
200 OK
{
  "code": 0,
  "message": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 7200,
    "token_type": "Bearer"
  }
}
GET /v1/knowledge-bases

获取知识库列表

分页获取当前租户下的所有知识库列表。

参数名类型必填说明
pageint页码,默认 1
page_sizeint每页数量,默认 20,最大 100
keywordstring按名称模糊搜索
200 OK
{
  "code": 0,
  "data": {
    "total": 15,
    "items": [
      {
        "id": "kb_001",
        "name": "产品技术文档库",
        "doc_count": 328,
        "status": "active",
        "created_at": "2026-01-15T08:30:00Z"
      }
    ]
  }
}
POST /v1/knowledge-bases

创建知识库

创建一个新的知识库,可指定名称、描述及可见范围。

参数名类型必填说明
namestring*知识库名称(1-50 字符)
descriptionstring知识库描述
visibilitystring可见范围:private / shared / public
curl -X POST https://api.super-brain.cn/v1/knowledge-bases \
  -H "Authorization: Bearer eyJhbG..." \
  -H "Content-Type: application/json" \
  -d '{"name":"研发知识库","description":"研发团队技术文档","visibility":"shared"}'
POST /v1/knowledge-bases/{kb_id}/documents

上传文档

向指定知识库上传文档。支持 PDF、Word、Excel、PPT、Markdown、TXT 等 20+ 格式,单文件最大 100MB。

200 OK
{
  "code": 0,
  "data": {
    "doc_id": "doc_20260115_001",
    "status": "processing",
    "message": "文档已上传,正在解析..."
  }
}
POST /v1/qa/ask

智能问答

基于 RAG 架构的智能问答接口。返回包含引用来源和置信度的精准答案。

参数名类型必填说明
filefile*上传的文件(multipart/form-data)
titlestring文档标题,默认使用文件名
auto_parsebool是否自动解析入库,默认 true
参数名类型必填说明
questionstring*用户问题
kb_idsarray指定检索的知识库 ID 列表
top_kint检索返回的引用片段数,默认 5
include_citationsbool是否返回引用来源,默认 true
200 OK
{
  "code": 0,
  "data": {
    "answer": "超级大脑支持 Docker Compose 一键部署...",
    "confidence": 0.92,
    "citations": [
      {
        "doc_id": "doc_001",
        "doc_name": "部署指南.pdf",
        "page": 3,
        "snippet": "Docker Compose 部署方式...",
        "score": 0.95
      }
    ]
  }
}
POST /v1/qa/stream

流式问答(SSE)

使用 Server-Sent Events 流式返回问答结果,适合需要打字机效果的前端场景。请求参数与 /v1/qa/ask 一致。

import requests

response = requests.post(
    "https://api.super-brain.cn/v1/qa/stream",
    headers={"Authorization": "Bearer eyJhbG..."},
    json={"question": "如何部署私有化版本?"},
    stream=True
)

for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))
GET /v1/knowledge-graph/entities

查询知识图谱实体

按名称或类型检索知识图谱中的实体节点。

参数名类型必填说明
kb_idstring*知识库 ID
keywordstring实体名称关键词
entity_typestring实体类型筛选
GET /v1/knowledge-graph/relations

查询实体关系

获取指定实体的关联实体及关系类型,支持多跳查询。

参数名类型必填说明
entity_idstring*起始实体 ID
depthint查询深度(1-3),默认 1
relation_typestring关系类型筛选

错误码参考

所有 API 响应均包含 code 字段,0 表示成功,非 0 表示错误。

错误码含义说明
0成功请求处理成功
1001认证失败API Key 无效或已过期
1002权限不足无权访问该资源
2001参数错误请求参数缺失或格式不正确
2002资源不存在请求的知识库或文档不存在
3001文件格式不支持上传的文件格式不在支持列表中
3002文件大小超限单文件超过 100MB 限制
5001服务内部错误服务器处理异常,请稍后重试

SDK 使用指南

超级大脑提供 Python 和 JavaScript 两种官方 SDK,简化 API 调用流程。

pip install super-brain-sdk
from super_brain import Client

client = Client(api_key="sk-xxxx", api_secret="your-secret")

# 智能问答
result = client.qa.ask(
    question="如何部署私有化版本?",
    kb_ids=["kb_001"]
)
print(result["answer"])
npm install @super-brain/sdk
import { Client } from '@super-brain/sdk';

const client = new Client({
  apiKey: 'sk-xxxx',
  apiSecret: 'your-secret'
});

// 智能问答
const result = await client.qa.ask({
  question: '如何部署私有化版本?',
  kbIds: ['kb_001']
});
console.log(result.answer);

接口限流策略

为保障服务稳定性,API 接口实行分级限流策略。超限将返回 429 状态码。

接口类别限流规则说明
认证接口10 次/分钟获取 Token 接口
读接口(GET)100 次/分钟知识库列表、实体查询等
写接口(POST/PUT)30 次/分钟创建知识库、上传文档等
智能问答20 次/分钟qa/ask 和 qa/stream
文件上传10 次/分钟文档上传接口

私有化部署版限流策略可自定义配置,不设默认限制。

Webhook 事件通知

当知识库发生特定事件时,系统会向你配置的 Webhook URL 发送 POST 请求,实现事件驱动的自动化流程。

事件类型触发条件说明
document.uploaded文档上传完成文档解析完成后触发
document.approved文档审核通过企业空间文档审核通过时触发
document.rejected文档审核驳回企业空间文档被驳回时触发
kb.created知识库创建新知识库创建完成时触发
qa.completed问答完成智能问答生成答案后触发
{
  "event": "document.approved",
  "timestamp": "2026-03-15T10:30:00Z",
  "data": {
    "kb_id": "kb_001",
    "doc_id": "doc_20260315_001",
    "doc_name": "产品规格说明书.pdf",
    "approved_by": "admin@company.com"
  },
  "signature": "sha256=xxxxxxx"
}

Webhook 请求头包含 X-SuperBrain-Signature 签名字段,用于验证请求来源。请使用你的 Webhook Secret 进行 HMAC-SHA256 签名校验。

开始集成超级大脑

立即入驻后即可获取 API Key,开始将 AI 知识能力集成到你的系统。