Server-to-Server · Tool Registry

Developer API

服务端到服务端的结构化计算与检索，与 MCP 共用同一 Registry。

打开 Console OpenAPI 规范 MCP 接入

开放工具: 37
LingXi Skill: 5
默认配额: 200 / 日
突发限流: 30 / 分

正在读取 /api/v1/public/mcp，当前显示默认值 37 / 5

POST /api/v1/tools/bazi.calculate_chart

Bearer Key 鉴权 · JSON 请求 · 只读计算

curl -sS -X POST \
  "https://www.ancientechoes.ai/api/v1/tools/bazi.calculate_chart" \
  -H "Authorization: Bearer ae_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "input_mode": "birth", "cast_time_source": "birth", "is_male": true, "calendar_type": "solar", "year": 1990, "month": 1, "day": 1, "hour": 8, "minute": 0, "is_leap_month": false, "split_zi_hour": true, "use_true_time": false, "apply_dst": false, "timezone_id": "Asia/Shanghai" }'

成功响应同时给出 api_version（传输契约）与 calculation.version（单工具计算版本）。

Quickstart

三步发出第一个请求

不需要安装 SDK。登录后在 Console 创建 Key，复制一次明文，然后用任意 HTTP 客户端调用。

1登录并创建 Key

打开 Console，选择 scope（tools:read、tools:invoke、rag:search、rag:query），设置有效期与限额。

明文 Key 只在创建/轮换时显示一次，形如 ae_live_xxx；测试环境使用 ae_test_xxx。

前往 Console

2调用 bazi.calculate_chart

curl

curl -sS -X POST \
  "https://www.ancientechoes.ai/api/v1/tools/bazi.calculate_chart" \
  -H "Authorization: Bearer ae_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "input_mode": "birth", "cast_time_source": "birth", "is_male": true, "calendar_type": "solar", "year": 1990, "month": 1, "day": 1, "hour": 8, "minute": 0, "is_leap_month": false, "split_zi_hour": true, "use_true_time": false, "apply_dst": false, "timezone_id": "Asia/Shanghai" }'

3读取计算版本

response

{
  "success": true,
  "api_version": "<当前契约版本>",
  "data": { "...": "领域结果" },
  "calculation": {
    "capability": "bazi.chart",
    "version": "<单工具计算版本>"
  }
}

Capabilities

能力矩阵与计费口径

当前开放 37 个工具、5 个 LingXi Skill；同一 Registry 同时服务 Developer API、MCP 与站内 Agent。

BaZi 八字

bazi.*

主盘、大运、串宫、禄命、合盘、论财与取名上下文；输入必须是显式民用时刻或直接四柱。

工具配额

Zi Wei 紫微斗数

ziwei.*

按有效安星码与显式目标时刻产出可复现主盘，不读取服务器当前时间。

工具配额

Qimen 奇门遁甲

qimen.*

时家转盘、二十四节气三元定局与明确的时间/地点语义。

工具配额

Astrology 西洋 · 七政四余 · Vedic

astrology.* · qizheng.* · vedic.*

宫制、坐标、时区与行运时刻全部显式传入，输出带计算溯源。

工具配额

Divination 占问

divination.*

六爻、梅花、塔罗、小六壬、大六壬、河洛等预览型起卦，结果只读。

工具配额

Almanac & Election 黄历与择日

almanac.* · election.*

农历换算、节气、逐日黄历与建除/值宿/太岁/罗喉杀师日等择日证据。

工具配额

RAG Search 检索

lingxi.rag_search

返回可追溯片段与命中元数据，不调用生成模型。

工具配额

RAG Query 生成式问答

lingxi.rag_query

检索后调用模型生成非流式 JSON；缺少 dataset_key / source_persona_id 会直接报错。

工具配额 + AI 套餐

计费口径：所有领域工具（含 lingxi.rag_search）只消耗工具调用配额；lingxi.rag_query 同时消耗工具配额与账号/组织的 AI 套餐额度，生成内容按 AI 套餐计费，不要把它当作纯检索接口。

Limits & Quotas

限额、配额与 Key 类型

配额按账号/Key 落库，所有数值都可由管理端或 Key 级配置覆盖。

默认额度

免费个人账号，可在 Console 查看实时已用量。

每日调用

200

每分钟突发

全部配额可配置；0 = 不限。组织、服务账号与单个 Key 可以拥有独立配额池。
Key 可设置日/月硬上限，避免一个 Key 打满整站额度。
响应头返回 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 与 X-RateLimit-Burst-Limit；超限返回 429 与 Retry-After。

test key 与 live key

两种前缀决定数据面，不决定权限大小。

ae_live_… Live Key

调用真实 Registry 与数据面，计入账号/Key 的真实配额；适合生产服务端。

ae_test_… Test Key

与生产数据隔离，返回受限或固定样例结果，用于联调请求结构与错误处理； test Key 禁止生成式 RAG（调用 lingxi.rag_query 返回 test_key_rag_disabled）；不要用 test key 结果做真实推断。

永不过期的 Key 只在创建时显式勾选，泄露后不会自动失效；生产环境建议设置 90 天有效期并定期轮换。

Error model

错误码与排障

失败响应结构统一为 { success:false, code, message, request_id, docs_url }；排障时请提供 request_id。

429 响应还会返回 Retry-After；不要用固定 sleep 死等。
错误码	HTTP	含义	处理建议
tool_not_found	404	工具名不在 Registry 中或拼写错误	先用 GET /api/v1/tools 读取准确工具名与 input_schema
tool_authentication_required	401	未携带有效 Key，或浏览器会话已过期	检查 Authorization: Bearer；网页端重新登录后重试
tool_scope_required	403	Key 的 scope 不允许该操作	在 Console 重新签发包含 tools:invoke / rag:query 的 Key
tool_entitlement_required	403	账号套餐不包含该工具的权益	升级套餐，或改用免费开放的只读工具
tool_quota_exceeded	429	日/月配额或每分钟突发超限	读取 Retry-After 与 X-RateLimit-*，降低并发或申请更高配额
rag_dataset_required	400	RAG 生成式问答缺少 dataset_key / source_persona_id	显式传入数据集或人格 ID；纯检索改用 lingxi.rag_search
rag_service_unavailable	502	检索服务不可达，本次检索未执行	稍后重试；不要把该结果当成“库里没有相关内容”
test_key_rag_disabled	403	沙箱 Key 不允许生成式 RAG	改用 live Key 调用 lingxi.rag_query，或用 test Key 只做检索联调
tool_invocation_failed	400	其他参数或执行错误（含 schema 校验失败）	按 GET /api/v1/tools 的 input_schema 修正请求体，并附带 request_id 报障

Examples

薄封装示例

示例代码仅演示鉴权、请求结构与错误处理，不是已发布的官方 SDK。

示例代码 · curl

curl -sS -X POST \
  "https://www.ancientechoes.ai/api/v1/tools/bazi.calculate_chart" \
  -H "Authorization: Bearer ae_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "input_mode": "birth", "cast_time_source": "birth", "is_male": true, "calendar_type": "solar", "year": 1990, "month": 1, "day": 1, "hour": 8, "minute": 0, "is_leap_month": false, "split_zi_hour": true, "use_true_time": false, "apply_dst": false, "timezone_id": "Asia/Shanghai" }'

示例中的 ae_live_xxx、AE_API_KEY 均为占位符，请勿提交真实 Key；浏览器端不要直连放 Key，服务端到服务端调用才安全。

Versioning

版本与弃用策略

传输契约、计算口径、Skill 包与 MCP 协议各自独立版本，不能互相替代。

契约版本

X-Tool-API-Version 标识传输与错误模型契约版本； URI 使用语义化 /v1。破坏性变更走新版本与弃用窗口，新增可选字段只升 minor。

每个工具另带 calculation_capability 与 calculation_version；复现结果时必须同时校验契约版本和计算版本。

与 MCP / Skill 的差异

Developer API 是给程序调用的 REST 工具接口；MCP 是给 Agent 的工具协议，额外承载 resources 与 MCP Apps；Skill 只是分发与提示词层，不单独定义能力或权限边界。

三者共用同一 Registry、权益、配额与计算版本，差异只在传输与呈现方式。

查看 MCP / LingXi 接入

curl -sS -X POST \ "https://www.ancientechoes.ai/api/v1/tools/bazi.calculate_chart" \ -H "Authorization: Bearer ae_live_xxx" \ -H "Content-Type: application/json" \ -d '{ "input_mode": "birth", "cast_time_source": "birth", "is_male": true, "calendar_type": "solar", "year": 1990, "month": 1, "day": 1, "hour": 8, "minute": 0, "is_leap_month": false, "split_zi_hour": true, "use_true_time": false, "apply_dst": false, "timezone_id": "Asia/Shanghai" }'

429 响应还会返回 Retry-After；不要用固定 sleep 死等。

错误码

HTTP

含义

处理建议

tool_not_found

404

工具名不在 Registry 中或拼写错误

先用 GET /api/v1/tools 读取准确工具名与 input_schema

tool_authentication_required

401

未携带有效 Key，或浏览器会话已过期

检查 Authorization: Bearer；网页端重新登录后重试

tool_scope_required

403

Key 的 scope 不允许该操作

在 Console 重新签发包含 tools:invoke / rag:query 的 Key

tool_entitlement_required

403

账号套餐不包含该工具的权益

升级套餐，或改用免费开放的只读工具

tool_quota_exceeded

429

日/月配额或每分钟突发超限

读取 Retry-After 与 X-RateLimit-*，降低并发或申请更高配额

rag_dataset_required

400

RAG 生成式问答缺少 dataset_key / source_persona_id

显式传入数据集或人格 ID；纯检索改用 lingxi.rag_search

rag_service_unavailable

502

检索服务不可达，本次检索未执行

稍后重试；不要把该结果当成“库里没有相关内容”

test_key_rag_disabled

403

沙箱 Key 不允许生成式 RAG

改用 live Key 调用 lingxi.rag_query，或用 test Key 只做检索联调

tool_invocation_failed

400

其他参数或执行错误（含 schema 校验失败）

按 GET /api/v1/tools 的 input_schema 修正请求体，并附带 request_id 报障