接入说明

能做什么

下面是接入时会用到的端点；请求怎么写、会返回什么，见后面的调用示例。

• POST/api/v1/chart排盘公开
• POST/api/v1/chart/overview解读概览，只回数字公开
• POST/api/v1/readings/retro-scan重点年份扫描，只回数字需要 readings:write
• POST/api/v1/readings按计划生成一份解读报告需要 readings:write
• GET/api/v1/readings/{id}取一份报告需要 readings:read
• GET/api/v1/readings列出自己的报告需要 readings:read
• GET/api/v1/catalog商品与价格公开
• GET/api/v1/samples/{slug}一份示例报告（内容固定不变）公开

解读概览、重点年份扫描、浏览示例都不调用 AI 模型；报告生成是异步的，提交后轮询报告接口看进度。

接入方式一：HTTP 接口

要先成为开发者，才能创建 API Key：登录后在个人中心的「开发者」页提交申请，通过之后就能自己创建，调用时放在请求头里。完整的 Key 只在创建的那一刻显示一次，请当场保存；丢了就在同一页把它吊销，再创建一把。

Authorization: Bearer ok_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

上面这串是占位符，请换成您自己的 Key。请勿把真正的 Key 提交到代码仓库。

六个权限范围

• chart排盘
• overview解读概览
• catalog商品与价格
• samples示例报告
• readings:read读、列解读报告
• readings:write生成报告、重点年份扫描、对照打分

每把 Key 每分钟最多 60 次调用，超了回 429 并带 Retry-After。Key 不存在、已吊销、权限不够三种情况回同一个 403 和同一句话——客户端只需要分清「慢一点」和「这把 Key 不能用了」。

接入方式二：MCP

MCP 是 AI 助手调用外部工具的开放协议。配好之后，Claude 这类助手就能自己排盘、自己取解读，不用另外写程序。服务名 cyber-oracle，地址就是站点下的 /mcp。

claude mcp add --transport http cyber-oracle \
  https://<站点>/mcp \
  --header "Authorization: Bearer ok_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "mcpServers": {
    "cyber-oracle": {
      "type": "http",
      "url": "https://<站点>/mcp",
      "headers": {
        "Authorization": "Bearer ok_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

八个工具，入参出参与对应的 HTTP 端点完全一致：

• bazi_chart
• reading_overview
• reading_retro_scan
• reading_create
• reading_get
• reading_list
• catalog_list
• sample_get

调用示例

示例里的出生信息是一张虚构盘（1984-03-21 07:40、北京），不是任何真人的。

排盘

{
  "name": "示例",
  "birth": { "year": 1984, "month": 3, "day": 21, "hour": 7, "minute": 40 },
  "gender": "female",
  "place": {
    "lng": 116.397, "lat": 39.908,
    "tz": "Asia/Shanghai", "coord_system": "GCJ-02", "label": "北京"
  },
  "policy": "default",
  "locale": "zh"
}

不知道出生时刻时用 "birth": {"year": 1984, "month": 3, "day": 21, "time_unknown": true}——盘照排，时辰相关的部分留空；但解读不接受这种盘。

解读概览

body 同排盘，但不许带 options。回的全是数字，用来告诉访客这张盘各项有多少可写的内容：

{"available": true, "as_of": {"year": 2026, "month": 8},
 "products": {"retro": {"total": 4, "years": [{"year": 2023, "count": 4}]},
              "personality": 5, "marriage": 4, "wealth": 7, "health": 1, "career": 1}}

生成一份报告

要带 Idempotency-Key 请求头；报告以提交的这一刻为准，所以不要再给年份。plan.retro.mode 有三种：recent（最近五年）、key（服务端先扫一遍挑重点年份）、custom（自己给 1–5 个年份）。

{
  "…": "同上的出生信息",
  "dimensions": ["性格", "财运", "婚姻", "事业", "健康"],
  "plan": { "version": 2, "retro": { "mode": "key" } }
}

202 = 已排进生成队列，之后轮询报告接口；200 = 这张盘没有足够的内容可写，什么都没排。同一个 Idempotency-Key 重复提交同一份内容回同一份报告，内容不同则回 409。

错误

{"code": "validation_error", "message": "…", "request_id": "…", "fields": {"…": "…"}}

错误体统一是这个形状，message 已按请求里的 locale 本地化。鉴权失败是例外，响应体的形状不同，按状态码处理即可。

定价

也接受按需定制开发；想先聊聊怎么接、怎么收费，来信即可，邮箱在页面最下方。

联系方式

接入、报价与定制开发，请发邮件到 954607206@qq.com

也可以先看示例报告与隐私政策，了解这项服务到底做什么、怎么处理数据。