AIPanda OpenAPI v1 接入文档

一、整体接入流程

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

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

创建 Subject创建命盘、卦盘，或经安全筛查生成 Healing Plan。

执行或解释疗愈通过 Session 执行；AI 只解释不可变事实。

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

核心数据边界：命盘、卦盘、安全判断和疗愈推荐均由本地确定性代码生成；AI 只解释确认后的 evidence，不会重新排盘、修改协议或改变安全状态。

接入前准备

向 AIPanda 平台运营人员申请 App，并说明需要 bazi、liuyao 或 healing。疗愈能力默认关闭，必须显式授权。
先获取 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": "请分析当前进展、主要阻力和应期。"
  }'

五、疗愈接入流程

产品边界：疗愈功能提供文化参考和日常身心练习，不构成医疗诊断、心理治疗或紧急援助。安全阻断优先于任何推荐分数。

步骤 1：创建不可变 Healing Plan

curl -sS -X POST "$BASE_URL/v1/healing/plans" \
  -H "Authorization: Bearer $AIPANDA_API_KEY" \
  -H "Idempotency-Key: user-1001-healing-plan-001" \
  -H "Content-Type: application/json" \
  -d '{
    "bazi_chart_id": "bzc_xxx",
    "check_in": {
      "emotion_tags": ["anxiety", "confusion"],
      "intensity": 7,
      "arousal": "high",
      "goal": "calm",
      "available_minutes": 10,
      "environment": "private_indoor",
      "posture_available": "seated",
      "audio_available": true
    },
    "safety": {
      "age_group": "adult",
      "immediate_danger": false,
      "crisis_flags": [],
      "physical_constraints": [],
      "driving_or_operating": false,
      "space_clear": false
    },
    "preferences": {
      "preferred_intensity": "gentle",
      "eyes_closed_preference": "open",
      "movement_preference": "avoid",
      "spiritual_language": "neutral"
    },
    "end_user_id": "partner-user-1001"
  }'

安全通过时返回 status=recommended 和完整协议快照；红线命中时仍返回可审计的 201 status=blocked，但不能创建 Session。八字只占推荐权重的 5%，且不参与安全判断。

步骤 2：创建并推进 Session

POST /v1/healing/sessions
{ "plan_id": "hpl_xxx", "playback_mode": "guided", "client_session_id": "ios-001" }

PATCH /v1/healing/sessions/hsn_xxx
{ "client_event_id": "evt-001", "event_type": "started", "elapsed_seconds": 0, "occurred_at": "2026-08-18T08:00:00.000Z" }

POST /v1/healing/sessions/hsn_xxx/checkout
{ "before_intensity": 7, "after_intensity": 4, "perceived_change": "somewhat_better", "body_state": "more_settled", "would_repeat": true, "adverse_experience": false, "adverse_tags": [] }

所有疗愈写请求都需要独立的 Idempotency-Key。music_breath_10 当前返回 availability=available、license_status=authorized 和可直接播放的绝对 asset_url；音频端点支持浏览器跨域播放与 Range 分段请求。其余没有对应音频的协议继续返回 script_only。

六、围绕同一 Subject 连续追问

八字、六爻和 Healing Plan 使用同一个追问接口。只传上一次 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。
`409 HEALING_PLAN_BLOCKED`	安全阻断的 Plan 不能开始 Session 或调用 AI	展示固定安全行动文案，不继续练习。
`409 SESSION_STATE_CONFLICT`	Session 事件不符合状态机或进度倒退	查询最新 Session 状态后按顺序补传事件。
`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