{"openapi":"3.1.0","info":{"title":"AIPanda OpenAPI","version":"1.0.0","description":"AIPanda OpenAPI v1 开放八字、六爻和疗愈能力。接入流程：\n1. 由平台运营人员创建 App、授权能力并生成 API Key；\n2. 创建由程序确定性计算的八字/六爻 Subject，或由安全与推荐规则生成 Healing Plan；\n3. 使用 Subject ID 创建首次 AI Response；\n4. 使用 previous_response_id 围绕同一 Subject 连续追问；\n5. 查询结果并提交反馈。\n\n排盘事实、安全判断和疗愈推荐均由本地确定性代码完成，AI 只解释已确认事实和不可变 Plan。完整接入示例请访问 /docs。"},"servers":[{"url":"https://api.qbb.me","description":"Production"},{"url":"/","description":"Current environment"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"BaZi","description":"创建和查询由程序确定性计算的八字命盘 Subject。"},{"name":"LiuYao","description":"围绕一个明确问题创建和查询由程序计算的六爻卦盘 Subject。"},{"name":"Healing","description":"以结构化 Check-in、安全规则和可选八字文化上下文创建不可变疗愈方案并执行 Session。"},{"name":"Responses","description":"对 Subject 进行首次 AI 解读，或通过 previous_response_id 连续追问。"},{"name":"Feedback","description":"回传第三方用户对 AI Response 的评价和纠正信息。"}],"paths":{"/v1/bazi/charts":{"post":{"tags":["BaZi"],"summary":"Create a deterministic BaZi chart","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBaziChart"}}}},"responses":{"201":{"description":"Chart created"},"400":{"$ref":"#/components/responses/Error"}}}},"/v1/bazi/charts/{chart_id}":{"get":{"tags":["BaZi"],"summary":"Get a BaZi chart","parameters":[{"$ref":"#/components/parameters/ChartId"}],"responses":{"200":{"description":"Chart"},"404":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["BaZi"],"summary":"Delete a BaZi chart","parameters":[{"$ref":"#/components/parameters/ChartId"}],"responses":{"204":{"description":"Deleted"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/liuyao/casts":{"post":{"tags":["LiuYao"],"summary":"Create a deterministic LiuYao cast","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLiuyaoCast"}}}},"responses":{"201":{"description":"Cast created"},"400":{"$ref":"#/components/responses/Error"}}}},"/v1/liuyao/casts/{cast_id}":{"get":{"tags":["LiuYao"],"summary":"Get a LiuYao cast","parameters":[{"$ref":"#/components/parameters/CastId"}],"responses":{"200":{"description":"Cast"},"404":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["LiuYao"],"summary":"Delete a LiuYao cast and its Responses","parameters":[{"$ref":"#/components/parameters/CastId"}],"responses":{"204":{"description":"Deleted"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/healing/plans":{"post":{"tags":["Healing"],"summary":"Create a deterministic Healing Plan","description":"Safety eligibility overrides recommendation scores. A safety block is returned as an auditable 201 blocked Plan.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHealingPlan"}}}},"responses":{"201":{"description":"Recommended or blocked Healing Plan"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/healing/plans/{plan_id}":{"get":{"tags":["Healing"],"summary":"Get a Healing Plan","parameters":[{"$ref":"#/components/parameters/PlanId"}],"responses":{"200":{"description":"Healing Plan"},"404":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Healing"],"summary":"Hard-delete a Healing Plan and downstream data","parameters":[{"$ref":"#/components/parameters/PlanId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"204":{"description":"Deleted"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/healing/sessions":{"post":{"tags":["Healing"],"summary":"Create a Healing Session from an eligible Plan","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHealingSession"}}}},"responses":{"201":{"description":"Session created"},"409":{"$ref":"#/components/responses/Error"}}}},"/v1/healing/sessions/{session_id}":{"get":{"tags":["Healing"],"summary":"Get a Healing Session","parameters":[{"$ref":"#/components/parameters/SessionId"}],"responses":{"200":{"description":"Healing Session"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"tags":["Healing"],"summary":"Apply a validated Session event","parameters":[{"$ref":"#/components/parameters/SessionId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateHealingSession"}}}},"responses":{"200":{"description":"Updated Session"},"409":{"$ref":"#/components/responses/Error"}}}},"/v1/healing/sessions/{session_id}/checkout":{"post":{"tags":["Healing"],"summary":"Submit immutable Healing Session checkout","parameters":[{"$ref":"#/components/parameters/SessionId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHealingCheckout"}}}},"responses":{"201":{"description":"Checkout submitted"},"409":{"$ref":"#/components/responses/Error"}}}},"/assets/healing/music_breath_10/1.0.0/hooponopono-a96c6aba.mp3":{"get":{"tags":["Healing"],"summary":"Stream the licensed music_breath_10 audio asset","description":"Public immutable MP3 asset. Supports Range requests and cross-origin browser playback.","security":[],"responses":{"200":{"description":"Complete MP3 audio"},"206":{"description":"Partial MP3 audio range"},"304":{"description":"Asset not modified"},"416":{"description":"Invalid byte range"}}}},"/v1/responses":{"post":{"tags":["Responses"],"summary":"Create an interpretation or follow-up","description":"For the first response send capability and subject_id. For a follow-up send previous_response_id.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateResponse"}}}},"responses":{"201":{"description":"Response created"},"409":{"$ref":"#/components/responses/Error"}}}},"/v1/responses/{response_id}":{"get":{"tags":["Responses"],"summary":"Get a response","parameters":[{"$ref":"#/components/parameters/ResponseId"}],"responses":{"200":{"description":"Response"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/feedback":{"post":{"tags":["Feedback"],"summary":"Submit response feedback","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFeedback"}}}},"responses":{"201":{"description":"Feedback recorded"},"404":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ap_test_ or ap_live_ API key"}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"一次业务写入使用一个稳定且唯一的值。网络重试必须复用相同 Key 和相同请求体。","schema":{"type":"string","maxLength":255},"example":"order-20260813-0001"},"ChartId":{"name":"chart_id","in":"path","required":true,"schema":{"type":"string","pattern":"^bzc_"}},"CastId":{"name":"cast_id","in":"path","required":true,"schema":{"type":"string","pattern":"^lyc_"}},"PlanId":{"name":"plan_id","in":"path","required":true,"schema":{"type":"string","pattern":"^hpl_"}},"SessionId":{"name":"session_id","in":"path","required":true,"schema":{"type":"string","pattern":"^hsn_"}},"ResponseId":{"name":"response_id","in":"path","required":true,"schema":{"type":"string","pattern":"^resp_"}}},"schemas":{"CreateBaziChart":{"type":"object","required":["birth"],"additionalProperties":false,"properties":{"birth":{"type":"object","required":["year","month","day","hour","gender"],"additionalProperties":false,"properties":{"year":{"type":"integer","minimum":1900,"maximum":2100},"month":{"type":"integer","minimum":1,"maximum":12},"day":{"type":"integer","minimum":1,"maximum":31,"description":"必须是对应公历或农历月份中真实存在的日期。"},"hour":{"type":"integer","minimum":0,"maximum":23},"minute":{"type":"integer","minimum":0,"maximum":59,"default":0},"gender":{"enum":["男","女"]},"calendar_type":{"enum":["solar","lunar"],"default":"solar"},"is_leap_month":{"type":"boolean","default":false},"birthplace":{"type":"string","maxLength":120},"time_confidence":{"enum":["exact","approximate"],"default":"exact"}}},"end_user_id":{"type":"string","maxLength":128},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"CreateLiuyaoCast":{"type":"object","required":["question","method"],"additionalProperties":false,"properties":{"question":{"type":"string","maxLength":1000},"method":{"enum":["dayan","manual_lines"]},"lines":{"type":"array","minItems":6,"maxItems":6,"items":{"type":"integer","enum":[6,7,8,9]}},"cast_at":{"type":"string","format":"date-time"},"end_user_id":{"type":"string","maxLength":128},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"CreateHealingPlan":{"type":"object","required":["check_in","safety"],"additionalProperties":false,"properties":{"bazi_chart_id":{"type":"string","pattern":"^bzc_"},"check_in":{"type":"object","additionalProperties":false,"required":["emotion_tags","intensity","arousal","goal","available_minutes","environment","posture_available","audio_available"],"properties":{"emotion_tags":{"type":"array","minItems":1,"maxItems":5,"items":{"enum":["anxiety","sadness","self_blame","guilt","regret","anger","suppression","irritability","stuck","confusion","other"]}},"intensity":{"type":"integer","minimum":0,"maximum":10},"arousal":{"enum":["low","medium","high"]},"goal":{"enum":["calm","self_compassion","release","grounding","rest"]},"available_minutes":{"type":"integer","minimum":1,"maximum":120},"environment":{"enum":["private_indoor","shared_indoor","outdoor","in_transit"]},"posture_available":{"enum":["seated","standing","either"]},"audio_available":{"type":"boolean"}}},"safety":{"type":"object","additionalProperties":false,"required":["age_group","immediate_danger","crisis_flags","physical_constraints","driving_or_operating","space_clear"],"properties":{"age_group":{"enum":["adult","minor","unknown"]},"immediate_danger":{"type":"boolean"},"crisis_flags":{"type":"array","items":{"enum":["self_harm","harm_others","chest_pain","severe_breathing_difficulty","fainting","severe_dissociation","psychotic_experience","acute_intoxication","unsafe_environment"]}},"physical_constraints":{"type":"array","items":{"enum":["mobility_limitation","balance_issue","recent_injury","pregnancy","cardiovascular_risk","vertigo","breathing_discomfort"]}},"driving_or_operating":{"type":"boolean"},"space_clear":{"type":"boolean"}}},"preferences":{"type":"object","additionalProperties":false,"properties":{"preferred_intensity":{"enum":["gentle","moderate"],"default":"gentle"},"eyes_closed_preference":{"enum":["open","closed","no_preference"],"default":"no_preference"},"voice_preference":{"enum":["guided","minimal","script_only"],"default":"guided"},"movement_preference":{"enum":["avoid","okay","prefer"],"default":"okay"},"spiritual_language":{"enum":["neutral","cultural","traditional"],"default":"neutral"},"excluded_protocol_ids":{"type":"array","maxItems":20,"items":{"type":"string"}}}},"end_user_id":{"type":"string","maxLength":128},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"CreateHealingSession":{"type":"object","required":["plan_id","playback_mode"],"additionalProperties":false,"properties":{"plan_id":{"type":"string","pattern":"^hpl_"},"playback_mode":{"enum":["guided","minimal","script_only"]},"client_session_id":{"type":"string","maxLength":128},"end_user_id":{"type":"string","maxLength":128}}},"UpdateHealingSession":{"type":"object","required":["client_event_id","event_type","elapsed_seconds","occurred_at"],"additionalProperties":false,"properties":{"client_event_id":{"type":"string","maxLength":128},"event_type":{"enum":["started","paused","resumed","progressed","completed","stopped","abandoned"]},"elapsed_seconds":{"type":"integer","minimum":0,"maximum":86400},"occurred_at":{"type":"string","format":"date-time"},"reason_code":{"type":"string","maxLength":64}}},"CreateHealingCheckout":{"type":"object","required":["before_intensity","after_intensity","perceived_change","body_state","would_repeat","adverse_experience","adverse_tags"],"additionalProperties":false,"properties":{"before_intensity":{"type":"integer","minimum":0,"maximum":10},"after_intensity":{"type":"integer","minimum":0,"maximum":10},"perceived_change":{"enum":["much_better","somewhat_better","no_change","somewhat_worse","much_worse"]},"body_state":{"enum":["more_settled","same","more_activated","mixed","not_sure"]},"would_repeat":{"type":"boolean"},"adverse_experience":{"type":"boolean"},"adverse_tags":{"type":"array","maxItems":8,"items":{"enum":["dizziness","breathing_discomfort","pain","panic_increase","dissociation","emotional_overwhelm","balance_problem","other"]}},"comment":{"type":"string","maxLength":2000}}},"CreateResponse":{"oneOf":[{"type":"object","required":["capability","subject_id","input"],"additionalProperties":false,"properties":{"capability":{"enum":["bazi","liuyao","healing"]},"subject_id":{"type":"string"},"input":{"type":"string","maxLength":1000},"end_user_id":{"type":"string","maxLength":128}}},{"type":"object","required":["previous_response_id","input"],"additionalProperties":false,"properties":{"previous_response_id":{"type":"string"},"input":{"type":"string","maxLength":1000},"end_user_id":{"type":"string","maxLength":128}}}]},"CreateFeedback":{"type":"object","required":["response_id","rating"],"additionalProperties":false,"properties":{"response_id":{"type":"string"},"rating":{"enum":["positive","negative"]},"tags":{"type":"array","maxItems":10,"items":{"type":"string"}},"comment":{"type":"string","maxLength":2000},"correction":{"type":"string","maxLength":4000}}},"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"retryable":{"type":"boolean"},"retry_after_ms":{"type":"integer"}}}}}},"responses":{"Error":{"description":"AIPanda API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}