KalaKarma 會員排盤 API

以 kalakarma.app 的已驗證會員身分排盤、保存結果，並建立可撤銷的分享連結。

開啟 Chart Service →

認證

登入 Chart Service 後，按「取得短效會員 API Token」。使用 Authorization: Bearer <token> 呼叫下列 API。Token 屬於你自己的會員身分，不可分享；分享星盤請使用 /s/ 網址。

API v1

GET    /api/v1/chart-service/catalog
POST   /api/v1/chart-service/casts
GET    /api/v1/chart-service/casts
GET    /api/v1/chart-service/casts/{id}
DELETE /api/v1/chart-service/casts/{id}
POST   /api/v1/chart-service/casts/{id}/share
DELETE /api/v1/chart-service/casts/{id}/share
GET    /api/v1/chart-service/shared/{token}  # only a published snapshot

計算範例

{
  "kind": "natal",
  "title": "我的本命星盤",
  "language": "zh",
  "subjects": [{
    "display_name": "Example",
    "birth_local_date": "1990-03-04",
    "birth_local_time": "08:00",
    "birth_time_known": true,
    "birth_tz_id": "Asia/Taipei",
    "birth_latitude": 25.033,
    "birth_longitude": 121.5654
  }],
  "options": {
    "natalHouseSystem": "wholesign",
    "mundaneHouseSystem": "placidus"
  }
}

可改用 subject_ids（你的名單 UUID 陣列），不能和 subjects 同時傳送。synastry / hehun 需要兩筆資料。時間重複的日光節約切換時段，須提供 birth_utc_offset_minutes。

盤種：natal、synastry、bazi、lunar、ziwei、vedic、qimen、tibetan、swarig、perpetual、hehun。

紫微 school：ZhongZhou / FeiXing / QinTian / SanHe / ZiYun；gender：Male / Female。奇門 qimen_mode：hour / ke；qimen_method：拆補 / 符頭，night_zi：次日 / 當日。查詢時間：target_year、target_date、target_time。

結果與分享

POST /casts 回傳 id、result.data（計算資料）、result.html（唯讀盤面）、warnings 與 engine。保存預設為私人。

POST /casts/{id}/share 傳入 {} 或 {"expires_days":30}，回傳 chart.kalakarma.services/s/ 分享網址。網址只回傳一次，再呼叫會撤銷舊網址並產生新的。DELETE /casts/{id}/share 可停用。刪除星盤也會撤銷分享。

計算約定

吠陀：Swiss Ephemeris Lahiri、Whole Sign、真交點、D1 / D9、Vimshottari（每年365.25日）。奇門：UTC+8 時家拆補或符頭；刻家採 Institute 十分鐘農曆加總法。藏曆 / SwaRig 沿用現有近似規則。每張盤保存當次結果，後續更動名單不會改寫。

每位會員最多保存1000張盤。計算忙碌會回429，可稍候重試。一般排盤約數秒；萬年曆較久，請允許130秒等待。輸入錯誤422、權限不足403、找不到或撤銷404。