开放 API 文档

知耘排盘开放接口 · 八字排盘 / 六爻占卜 / 农历转换 · 免费接入

知耘排盘开放 API 向第三方应用、小程序、智能体（Agent）免费提供专业的八字排盘、六爻占卜与农历转换能力。所有排盘计算接口完全免费，无需申请、无需注册，拿到密钥即可接入。

一、快速开始

所有接口均通过 GET 请求调用，在请求参数中携带公开密钥即可，三步完成接入：

拼接接口地址和参数
在参数中带上 api_key=lingji_public_2026
发起请求，解析返回的 JSON

试试第一条命令（八字排盘）：

curl "https://lingjipaipanjiexi.top/api/bazi?year=1990&month=5&day=20&hour=10&gender=male&api_key=lingji_public_2026"

二、接口列表

1. 八字排盘

GET /api/bazi — 按出生日期时间排出完整八字命盘（四柱、十神、大运流年、神煞、纳音等）

参数	必填	说明
`year` / `month` / `day`	是	出生年月日（公历）
`hour`	是	出生时辰，0~23
`gender`	否	性别，`male` 男 / `female` 女，默认 male
`lunar`	否	是否农历输入，`true` / `false`，默认 false
`leap`	否	农历是否闰月，默认 false
`hour_unknown`	否	时辰未知时传 `true`，默认按子时计算
`format`	否	设为 `1` 时额外返回格式化文本字段

2. 六爻装卦（手动六爻）

GET /api/liuyao — 手动指定六个爻值，排出本卦变卦、世应六亲、伏神神煞

参数	必填	说明
`year` / `month` / `day` / `hour`	是	起卦时间
`yaos`	是	6 个爻值，逗号分隔，从初爻到上爻；0=老阴（动）、1=少阳、2=少阴、3=老阳（动）。如 `1,2,1,2,2,1`
`gender`	否	性别，默认 male

3. 六爻起卦（姓氏/数字）

GET /api/liuyao/surname-time — 按姓氏笔画或数字自动起卦

参数	必填	说明
`year` / `month` / `day` / `hour`	是	起卦时间
`surname_num`	是	姓氏笔画数或 1~64 的数字

4. 四柱排盘（按干支）

GET /api/bazi/from-pillars — 已知年柱月柱日柱时柱，直接反推出生日期并排盘

参数	必填	说明
`year_pillar` / `month_pillar` / `day_pillar` / `hour_pillar`	是	四柱干支，如 `甲子`
`gender`	否	性别，默认 male
`range_years`	否	往前搜索年数，默认 120

5. 农历转换

GET /api/lunar/solar2lunar — 公历转农历；GET /api/lunar/lunar2solar — 农历转公历

参数	必填	说明
`year` / `month` / `day`	是	待转换日期
`isleap`	否	仅 lunar2solar：是否闰月，默认 false

三、鉴权方式

公开密钥：lingji_public_2026

所有接口必须携带 api_key 参数，否则返回 403
密钥为公开免费使用，无需申请注册，可直接接入

四、限流规则

限制	额度	说明
单 IP 每秒	5 次	超出返回 429，建议调用方做间隔控制或重试退避
单 IP 每天	100 次	按自然日计算，次日自动恢复，超出返回 429

限流按请求来源 IP 计算，与密钥无关。正常使用不会触达上限，请勿使用脚本高频轮询。

五、错误码

状态码	含义	处理建议
400	参数错误或缺失	按返回提示修正参数
403	缺少或无效的密钥	检查是否携带 api_key 参数
429	调用过于频繁，触发限流	等待后重试，控制调用频率
500	服务器内部错误	稍后重试，或联系站长

六、示例代码

Python

import requests

resp = requests.get("https://lingjipaipanjiexi.top/api/bazi", params={
    "year": 1990, "month": 5, "day": 20, "hour": 10,
    "gender": "male",
    "api_key": "lingji_public_2026",
})
data = resp.json()
print(data)

JavaScript

const url = "https://lingjipaipanjiexi.top/api/bazi?" +
  "year=1990&month=5&day=20&hour=10&gender=male&" +
  "api_key=lingji_public_2026";

const data = await fetch(url).then(r => r.json());
console.log(data);

七、深度解读（AI 解读）

在免费排盘的基础上，平台提供基于命理知识库的 AI 深度解读（付费服务）。由专属命理师人设（苏姐 / 陈三更）结合知识库对命盘进行真人感解读，按次计费。

费用说明

项目	费用	说明
AI 深度解读	3 元/次	正常价格，从账户余额扣除
优惠解读	1 元/次	账户有优惠次数时优先按优惠价扣费
排盘计算接口	免费	不受影响

接入步骤

在官网 lingjipaipanjiexi.top 注册账号并充值（余额用于支付解读费用）
调用登录接口获取访问令牌（token）
用公开密钥调用排盘接口，得到命盘数据
携带 token 和命盘数据调用解读接口，获得解读内容

1. 登录获取令牌

POST /api/user/login

curl -X POST "https://lingjipaipanjiexi.top/api/user/login" \
  -H "Content-Type: application/json" \
  -d '{"phone": "你的手机号", "password": "你的密码"}'

返回中的 token 即为后续调用解读接口所需的令牌。

2. 调用深度解读

POST /api/ai/chat — 在 URL 参数中携带 token，请求体携带命盘数据和问题

请求体字段	必填	说明
`bazi`	否	八字排盘接口返回的完整命盘数据
`gua_data`	否	六爻排盘接口返回的卦象数据
`question`	是	要咨询的问题，如"看看今年事业运"
`prompt_type`	否	`bazi` 八字解读 / `liuyao` 六爻解读，默认 bazi
`role`	否	解读人设：`laozhou` 苏姐 / `laowang` 陈三更，默认 laozhou
`history`	否	历史对话消息列表，多轮对话时传入

curl -X POST "https://lingjipaipanjiexi.top/api/ai/chat?token=你的令牌" \
  -H "Content-Type: application/json" \
  -d '{"bazi": {"...命盘数据..."}, "prompt_type": "bazi", "question": "帮我看看事业"}'

3. 返回说明

字段	说明
`answer`	解读内容（纯文本）
`sources`	引用来源（通常为空）
`fee`	本次扣费金额（单位：分），如 100 = 1 元
`balance_remaining`	剩余余额（分）
`bonus_remaining`	剩余优惠次数

余额不足时，answer 返回 __BALANCE_INSUFFICIENT__，本次不扣费。解读按次计费，调用前请确认余额充足。

4. 保存排盘记录（可选）

登录后支持保存排盘记录，保存后可在多轮对话中自动关联历史命盘（多盘对比）。

POST /api/record/save — 保存命盘

curl -X POST "https://lingjipaipanjiexi.top/api/record/save" \
  -H "Content-Type: application/json" \
  -d '{"token": "你的令牌", "name": "张伟", "type": "bazi", "data": {...命盘数据...}}'

查看已保存的记录：GET /api/record/list?token=你的令牌

5. 完整示例（Python）

import requests

BASE = "https://lingjipaipanjiexi.top"

# 1) 登录拿令牌
login = requests.post(f"{BASE}/api/user/login", json={
    "phone": "你的手机号", "password": "你的密码",
}).json()
token = login["token"]

# 2) 排盘（免费，公开密钥）
pan = requests.get(f"{BASE}/api/bazi", params={
    "year": 1990, "month": 5, "day": 20, "hour": 10,
    "gender": "male", "api_key": "lingji_public_2026",
}).json()

# 3) 深度解读（付费，按次扣费）
resp = requests.post(f"{BASE}/api/ai/chat", params={"token": token}, json={
    "bazi": pan, "prompt_type": "bazi",
    "question": "帮我看看这个八字的事业发展",
}).json()

print(resp["answer"])
print("本次扣费:", resp["fee"], "剩余余额:", resp["balance_remaining"])

八、使用约定

本接口免费开放，请合理使用，禁止用于任何违法用途
禁止以任何形式转售、倒卖本接口能力
接口可能随版本迭代微调，请以本页为准