智脑 API 小白教程

不写黑话，从零开始：10 分钟让你的程序开口和智脑对话。

①API 是什么？一句话版

②拿到钥匙（API Key）

Key 相当于你家程序的"门禁卡"。找管理员（有运维台口令的人）申请一张，可限定用途和速度。

# 管理员在服务器上执行（或运维台代为调用）：
curl -X POST https://danao.tongqiansuanzhi.com/api/v1/keys \
  -H "X-Admin-Token: <管理口令>" \
  -H "Content-Type: application/json" \
  -d '{"owner":"我的名字","scopes":["chat"],"rate_limit":60}'

# 返回里有一串 dk_live_ 开头的 api_key —— 妥善保存，只显示这一次

③发出第一个请求：对话

把 <你的Key> 换成刚拿到的钥匙，复制到终端（Windows 用 Git Bash 或 PowerShell）：

curl -X POST https://danao.tongqiansuanzhi.com/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <你的Key>" \
  -d '{"message":"你好，介绍一下你自己"}'

Python 写法（推荐，处理中文更稳）：

import httpx

resp = httpx.post(
    "https://danao.tongqiansuanzhi.com/api/v1/chat",
    headers={"X-API-Key": "<你的Key>"},
    json={"message": "你好，介绍一下你自己"},
    timeout=60,
)
print(resp.json()["reply"])

④读懂它的回答

{
  "reply": "你好，我是通千算智智脑……",   # 回答正文
  "backend": "letta",                     # 这次由哪个后端应答（letta=主脑 / gateway=降级）
  "confidence": {                         # 它的自我把握程度
    "confidence": 0.82,                   # 0~1，越高越确定
    "boundary_declared": false            # true=它明说没把握，请当参考
  },
  "skills_used": ["……"],                  # 这次回答用到了哪些技能
  "memory_hits": 2                        # 召回了几条相关记忆
}

⑤常用接口一览

接口	方法	干什么	需要的权限
/api/v1/chat	POST	对话（本文主角）	chat
/api/v1/memory	POST	写入一条记忆	memory:write
/api/v1/memory/search	GET	语义搜索记忆	memory:read
/api/v1/skills	GET	查看已掌握技能清单	skills:read
/api/v1/public/status	GET	公开计数（技能数/记忆数/适应度）	无需 Key
/healthz	GET	健康检查（适合做监控）	无需 Key

申请 Key 时在 scopes 里写上需要的权限即可，例如 ["chat","memory:read"]。

⑥出错怎么办？状态码速查

返回码	意思	怎么办
401	没带 Key 或 Key 错了	检查 X-API-Key 请求头
403	Key 没这个权限	找管理员补 scope
409	请求冲突（重复提交等）	按业务语义处理
422	参数不合法（如消息超长 >4000 字）	检查请求体
429	太快了，触发限速	放慢速度，稍等再试
502	大脑后端暂时不可用	退避重试；可提示用户稍后再问

⑦进阶：让智脑记住你的用户

curl -X POST https://danao.tongqiansuanzhi.com/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <你的Key>" \
  -d '{"message":"记住：我们项目用 FastAPI","namespace":"myproj"}'

⑧更多资源