AIPanda OpenAPI v1 接入文档

一、整体接入流程

创建 App平台运营人员配置环境、能力、RPM 和月配额。

获取 API KeyKey 只展示一次，服务端安全保存。

创建 Subject八字创建命盘；六爻针对明确问题起卦。

创建 ResponseAI 解释程序已经确认的命盘或卦盘事实。

追问与反馈携带上一次 Response ID 追问，并回传评价。

核心数据边界：八字命盘和六爻卦盘由本地算法计算，是事实来源；AI 只解释确认后的 evidence，不会自行重新排盘或修改卦象。

接入前准备

向 AIPanda 平台运营人员申请 App，并说明需要 bazi、liuyao 或两项能力。
先获取 ap_test_ Key 完成联调，通过验收后再申请 ap_live_ Key。
服务端保存 Key；不要放进浏览器、移动端包、日志或公开仓库。

二、地址、认证与幂等

export BASE_URL="https://api.qbb.me"
export AIPANDA_API_KEY="ap_test_xxx"

# 所有业务 API 都需要
Authorization: Bearer $AIPANDA_API_KEY

# 创建 Subject / Response 时必须提供
Idempotency-Key: partner-order-or-request-id

幂等重试：一次业务写入使用一个稳定且唯一的 Idempotency-Key。网络超时后，必须用相同 Key 和相同请求体重试。

不要复用：不同业务请求不能使用同一个 Idempotency-Key；同 Key 但请求体不同会返回 IDEMPOTENCY_CONFLICT。

三、八字接入流程

步骤 1：创建命盘 Subject

curl -sS -X POST "$BASE_URL/v1/bazi/charts" \
  -H "Authorization: Bearer $AIPANDA_API_KEY" \
  -H "Idempotency-Key: user-1001-bazi-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "birth": {
      "year": 1990,
      "month": 5,
      "day": 15,
      "hour": 10,
      "minute": 30,
      "gender": "男",
      "calendar_type": "solar",
      "birthplace": "上海",
      "time_confidence": "exact"
    },
    "end_user_id": "partner-user-1001"
  }'

保存返回的 id，格式为 bzc_xxx。同一张命盘只需创建一次，后续问题复用该 Subject。

步骤 2：创建首次解读

curl -sS -X POST "$BASE_URL/v1/responses" \
  -H "Authorization: Bearer $AIPANDA_API_KEY" \
  -H "Idempotency-Key: user-1001-response-001" \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "bazi",
    "subject_id": "bzc_xxx",
    "input": "请分析我的事业特点和更适合的工作方式。",
    "end_user_id": "partner-user-1001"
  }'

成功后保存 resp_xxx。成功创建一条 Response 计 1 个计费单位；创建或查询命盘本身不计 Response 次数。

四、六爻接入流程

步骤 1：围绕一个明确事件创建卦盘 Subject

curl -sS -X POST "$BASE_URL/v1/liuyao/casts" \
  -H "Authorization: Bearer $AIPANDA_API_KEY" \
  -H "Idempotency-Key: user-1001-liuyao-001" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "这次合作能否按计划在本月签约？",
    "method": "dayan",
    "end_user_id": "partner-user-1001"
  }'

dayan 由平台安全生成一次爻值并固定保存。若第三方已经完成起卦，可使用 manual_lines，并提供六个 6/7/8/9 数值：

{
  "question": "这次合作能否按计划在本月签约？",
  "method": "manual_lines",
  "lines": [7, 8, 9, 7, 6, 8]
}

六个爻值必须按初爻到上爻排列。六爻用于一事一问；如果用户换了事件，应重新创建 lyc_xxx，不要沿用旧卦。

步骤 2：创建首次解读

curl -sS -X POST "$BASE_URL/v1/responses" \
  -H "Authorization: Bearer $AIPANDA_API_KEY" \
  -H "Idempotency-Key: user-1001-response-002" \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "liuyao",
    "subject_id": "lyc_xxx",
    "input": "请分析当前进展、主要阻力和应期。"
  }'

五、围绕同一 Subject 连续追问

八字和六爻使用同一个追问接口。只传上一次 previous_response_id 和当前问题，不需要客户端重复发送整段历史。

curl -sS -X POST "$BASE_URL/v1/responses" \
  -H "Authorization: Bearer $AIPANDA_API_KEY" \
  -H "Idempotency-Key: user-1001-response-003" \
  -H "Content-Type: application/json" \
  -d '{
    "previous_response_id": "resp_xxx",
    "input": "结合刚才的结论，未来两年应该重点注意什么？"
  }'

平台使用固定长度的滚动摘要维持上下文，不会随着轮次无限携带全部历史。六爻检测到明显换事时会返回 NEW_SUBJECT_REQUIRED。

查询已有资源

GET /v1/bazi/charts/bzc_xxx
GET /v1/liuyao/casts/lyc_xxx
GET /v1/responses/resp_xxx

# 删除 Subject 时会同时删除其 Response
DELETE /v1/bazi/charts/bzc_xxx
DELETE /v1/liuyao/casts/lyc_xxx

六、回传用户反馈

建议第三方把点赞、点踩、标签、文字意见和纠正信息同步回来，用于持续优化外部用户体验。

curl -sS -X POST "$BASE_URL/v1/feedback" \
  -H "Authorization: Bearer $AIPANDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "response_id": "resp_xxx",
    "rating": "positive",
    "tags": ["准确", "有帮助"],
    "comment": "事业部分与实际情况比较贴合"
  }'

七、错误处理与上线检查

状态/错误码	含义	接入方处理
`401 INVALID_API_KEY`	Key 无效、过期或已撤销	停止重试并检查使用环境和 Key。
`403`	App 暂停或能力未开通	联系平台运营人员调整 App。
`409 IDEMPOTENCY_CONFLICT`	同一幂等 Key 对应了不同请求体	为新业务生成新 Key。
`409 NEW_SUBJECT_REQUIRED`	六爻追问已经明显换事	重新起卦并创建新的 Subject。
`429`	RPM、并发或月配额受限	读取 `retry_after_ms`，退避后重试；月配额需联系运营人员。
`503/504`	模型临时不可用或超时	复用原 Idempotency-Key 和原请求体进行有限重试。

上线前检查清单

Key 只保存在服务端密钥管理系统，没有进入客户端或日志。
每个写请求都有稳定、可追踪、不会跨业务复用的 Idempotency-Key。
保存 Subject ID 和 Response ID，支持查询、追问和反馈关联。
针对 429、503、504 使用有限次数的指数退避，不进行无限重试。
命理结果仅作为文化分析与自我反思参考，不替代医疗、法律或投资专业建议。

机器可读合同：OpenAPI 3.1 JSON · 服务健康检查：/health · 数据库就绪检查：/ready