接口文档
⚙

大肥鱼 API 接口文档

把一个已导入「大肥鱼」人格 / 插件 / 知识库的 AstrBot 实例,包装成稳定可调用的 HTTP API。 业务方只需 GATEWAY_API_KEY + 自己的 user_id;管理面另用 ADMIN_API_KEY,两套凭证物理分离。

两套凭证,别混用。业务接口用 Authorization: Bearer <GATEWAY_API_KEY>; 管理接口用 X-Admin-Key: <ADMIN_API_KEY>。用错一律 401。 本页右上角填入 Key 后可直接在线试调,Key 只存于当前页面内存,不写 Cookie、不落日志。

快速开始

最小调用

curl -s http://127.0.0.1:8080/v1/chat \\
  -H "Authorization: Bearer $GATEWAY_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"user_id":"alice","message":"你好","stream":false}'

通用约定

项目说明
Content-Typeapplication/json(除 /health 外均需)
user_id1~128 字符,你系统里的稳定用户 ID。网关用 HMAC 映射为 u_<24hex>,绝不透传原文
streamtrue 透传上游 SSE;false 聚合为 {events, session_id}
X-Request-ID每个响应都带,用于日志追踪(也可由调用方传入)
错误体{"detail": "..."},HTTP 状态码语义标准(400/401/404/409/429/503)

关键响应头

响应头含义
X-Quota-Remaining当日剩余调用额度
X-Fish-Id本次命中的鱼(未传 fish 时为空)
X-Memory-Recallhit=N/scopes=N/ok=N/ms=N/status,仅 recall:true 时出现
X-Memory-Writestatus=pending|written|denied|skipped,仅 write:true 时出现

业务接口

面向业务程序,只暴露 /health、/v1/chat、会话与通知四类。

GET/health无需鉴权

健康检查。返回上游地址、人格模式、管理态开关、召回 / 写入配置与配额水位。

响应示例

{"ok":true,"upstream":"http://astrbot:6185","persona_mode":"shared",
 "admin_enabled":true,"recall_enabled":false,"write_enabled":false,
 "write_mode":"review","write_pending":{"total":0,"pending":0}}
试一下
POST/v1/chatBearer

发起对话。默认 SSE 流式;stream:false 聚合为非流式结果。支持三种人格模式、按鱼路由、多域召回与分层写入。

请求体

字段类型说明
user_idstring必填,1~128 字符
messagestring | array必填,字符串或 AstrBot 消息链(图片/语音等富文本)
session_idstring可选,缺省自动新建;网关按用户加命名空间前缀
streambool默认 true;false 返回聚合结果
modestringshared / tenant / user,默认取服务端配置
config_idstring指定 AstrBot 配置档案(tenant 模式)
fishstring指定鱼(如 chat / work),影响人格、知识库与记忆域
recallbool开启多域召回(主 / 任务 / 用户记忆),默认关闭
writebool开启对话沉淀,默认关闭
write_modestringreview(默认,先待审)/ auto(直写)

请求示例

{"user_id":"alice","message":"用一句话介绍你自己","stream":false,"fish":"chat"}

非流式响应

{"session_id":"alice_xxx","events":["{\"type\":\"plain\",\"data\":\"...\"}"]}

⚠ events 是上游 SSE data: 的原始字符串数组,网关刻意不解析。 真实模型 + 工具链下可能混有 reasoning / tool_call 事件,取正文请优先用 type=complete。

试一下
GET/v1/sessionsBearer

列出某用户的会话。查询参数:user_id(必填)、config_id、fish。

试一下
DELETE/v1/sessions/{session_id}Bearer

删除指定会话。查询参数:user_id(必填)、config_id、fish。

试一下
POST/v1/notifyBearer

主动推送消息。需要上游 Key 额外具备 im scope,否则返回上游 403。

{"user_id":"alice","message":"这是一条主动提醒"}
试一下

管理接口

全部要求 X-Admin-Key,且所有请求(含失败)写入审计流水,只存指纹不存明文凭证。

GET/v1/admin/dashboardX-Admin-Key

一屏聚合:health / 策略 / 记忆统计 / 待审 / 审计 / 写入配额 / 限流 / Page API 可达性。

响应字段

字段说明
health网关 /health 快照
policy策略摘要(鱼数量、identity 版本等)
memory记忆总数、域分布、用户数
pending待审统计与分析
audit审计条数、成功/失败、动作分布
write_quota写入配额与活跃桶
page_api_reachableLivingMemory Page API 是否可达
试一下
GET/v1/admin/fishX-Admin-Key

列出全部鱼及其读 / 写记忆域、绑定的知识库与配置档案。

试一下
POST/v1/admin/fishX-Admin-Key

新增鱼。apply:false 只返回变更 diff,apply:true 才落盘并留 .bak。 业务鱼禁写主记忆、禁声明跨鱼读,服务端全量校验,非法直接 400。

{"fish_id":"study",
 "config":{"config_id":"fish_study","kb":["主记忆/常识基座"],
           "read":["global","fish:self","user:self"],"write":["fish:self"]},
 "apply":false}
试一下(默认 apply:false,只看 diff)
GET/v1/admin/policyX-Admin-Key

读取完整分层记忆策略。PUT 同一路径可写回,服务端强校验后落盘并自动备份。

试一下
GET/v1/admin/pending/browseX-Admin-Key

浏览待审记忆。查询参数:status(pending/approved/rejected/all)、fish、pii、q、limit。

试一下
POST/v1/admin/pending/{item_id}X-Admin-Key

批准或拒绝一条待审。approve 走专用通道写入 lm:fish:* 共享域;重复审核返回 409;写入失败保持 pending 可重试。

{"action":"approve","note":"人工确认"}
GET/v1/admin/auditX-Admin-Key

管理请求审计流水。?limit= 控制条数;/v1/admin/audit/export 可直接下载 JSON。

试一下
GET/v1/admin/runtimeX-Admin-Key

限流 / 日配额 / 写入配额的实时水位与配置,便于排障。

试一下
POST/v1/admin/selftestX-Admin-Key

一键只读自检:凭证、上游、Page API、策略、待审队列、配额逐项打勾,不触发任何写操作。

试一下

OpenAI 兼容

把 base_url 指向本网关,即可用任何 OpenAI SDK 调用大肥鱼。 鉴权用业务 Key(dfy_...)或根 Key。model 形如 dafeiyu-<fish> 时按该鱼路由。

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8080/v1", api_key="dfy_xxx")
resp = client.chat.completions.create(
    model="dafeiyu-chat",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

支持范围

能力状态说明
chat.completions支持stream / 非 stream;system 消息会作为人格前缀注入
models.list支持返回 dafeiyu 与每条鱼的 dafeiyu-<fish>
temperature / max_tokens接收但不生效参数由 AstrBot 侧 Provider 决定,网关不透传
多轮 messages 历史部分只取最后一条 user;历史由 AstrBot 会话自身维护
embeddings / images / audio不支持返回 404

⚠ 流式为「先取完整回复再按 48 字分块推送」,SDK 兼容但不是真逐字流; 需要真流式请用原生 /v1/chat。

其余端点

方法路径说明
PUT/v1/admin/policy校验并保存策略
POST/v1/admin/policy/diff策略改动预览(只读)
PUT/v1/admin/fish/{fish_id}修改鱼
DELETE/v1/admin/fish/{fish_id}删除鱼(需 apply:true)
PUT/v1/admin/allowlist服务白名单
GET/v1/admin/pending待审列表(简版)
GET/v1/admin/pending/stats待审统计
GET/v1/admin/pending/{item_id}单条详情
POST/v1/admin/batch-review批量批准 / 拒绝
GET/v1/admin/status管理态状态
GET/v1/admin/sessions会话与用户视图
GET/v1/admin/audit/export审计导出
POST/v1/admin/page/{endpoint}LivingMemory Page API 白名单代理(13 个端点)
POST/v1/admin/migrate-identityidentity 迁移 dry-run
GET/v1/admin/config-profiles配置档案候选(鱼表单下拉)
GET/v1/admin/knowledge-bases知识库候选(只读 kb.db)
GET/v1/admin/sessions/list按记忆域聚合的活跃会话
GET/v1/modelsOpenAI 兼容:模型列表
POST/v1/chat/completionsOpenAI 兼容:对话补全
GET/v1/admin/keysAPI Key 列表(含用量)
POST/v1/admin/keys签发 Key(明文只返回一次)
PATCH/v1/admin/keys/{id}修改 Key 绑定与限额
POST/v1/admin/keys/{id}/rotate轮换(旧 Key 立即失效)
POST/v1/admin/keys/{id}/revoke吊销
GET/v1/admin/usage调用量 / 错误率 / 平均耗时
GET/v1/admin/providersAI 网关:Provider 列表(凭证打码)
PATCH/v1/admin/providers/{id}/enabled启用 / 停用(实时生效)
POST/v1/admin/providers/{id}/test连通性测试(需 model)
POST/v1/admin/providers接入新 Provider(需 key)
DELETE/v1/admin/providers/{id}删除(需 confirm:true)

错误码

状态码含义处理建议
400参数非法 / 策略校验失败看 detail,修正后重试;不要盲目重试
401凭证缺失或错误检查用的是业务 Key 还是管理 Key
404路径不存在 / 非白名单核对路径拼写与方法
409重复审核 / 状态冲突刷新列表后再操作
429触发限流或日配额退避重试,或调高配额
503管理态未配置 / 上游不可用检查 ADMIN_API_KEY 与上游容器