{"openapi":"3.1.0","info":{"title":"D8ly Read Developer API","version":"2026-08-20","description":"Bazi (八字), tarot, number energy, compatibility, and image-reading APIs. MCP clients should connect to https://d8ly.app/mcp."},"servers":[{"url":"https://d8ly.app"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Deterministic","description":"Structured calculations / 結構化計算"},{"name":"AI readings","description":"AI-generated interpretations / AI 生成解讀"},{"name":"Agent protocol","description":"Model Context Protocol transport / MCP 傳輸"}],"paths":{"/mcp":{"post":{"tags":["Agent protocol"],"operationId":"mcpStreamableHttp","summary":"MCP Streamable HTTP / MCP Streamable HTTP 端點","description":"Stateless MCP endpoint exposing get_daily_almanac, calculate_bazi_chart, and get_daily_bazi_guidance. Use an MCP client rather than calling this operation as a conventional REST endpoint.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"JSON-RPC 2.0 MCP message","additionalProperties":true}}}},"responses":{"200":{"description":"MCP JSON-RPC response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid MCP request","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-mcp-transport":"streamable-http","x-mcp-tools":["get_daily_almanac","calculate_bazi_chart","get_daily_bazi_guidance"]}},"/api/v1/bazi":{"post":{"tags":["Deterministic"],"operationId":"calculateBazi","summary":"Calculate Bazi chart / 八字排盤","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date","description":"Birth date / 出生日期"},"time":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d$","default":"12:00","description":"Local birth time / 出生地當地時間"},"city":{"type":"string","maxLength":100,"description":"Birth city; use instead of coordinates / 出生城市，可取代經緯度"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"timezone":{"type":"number","minimum":-12,"maximum":14,"description":"UTC offset in hours / UTC 小時時差"},"includeDaily":{"type":"boolean","default":false,"description":"Include the current day calculation / 包含今日運勢計算"}}}}}},"responses":{"200":{"description":"Bazi chart and resolved location / 八字命盤與解析後的地點","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request / 請求資料無效","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid API key / API 金鑰遺失或無效","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Daily request limit reached / 已達每日請求上限","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Service error / 服務錯誤","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/v1/daily":{"post":{"tags":["AI readings"],"operationId":"generateDailyFortune","summary":"Generate daily fortune / 生成每日運勢","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date","description":"Birth date / 出生日期"},"time":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d$","default":"12:00","description":"Local birth time / 出生地當地時間"},"city":{"type":"string","maxLength":100,"description":"Birth city; use instead of coordinates / 出生城市，可取代經緯度"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"timezone":{"type":"number","minimum":-12,"maximum":14,"description":"UTC offset in hours / UTC 小時時差"},"locale":{"type":"string","enum":["en","zh"],"default":"en"},"model":{"type":"string","enum":["openai","gemini"]}}}}}},"responses":{"200":{"description":"Chart, current-day reading, and narrative / 命盤、今日資料與解讀","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request / 請求資料無效","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid API key / API 金鑰遺失或無效","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Daily request limit reached / 已達每日請求上限","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Service error / 服務錯誤","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/v1/number-energy":{"post":{"tags":["AI readings"],"operationId":"analyzeNumberEnergy","summary":"Analyze phone number energy / 分析手機號碼能量","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","description":"Phone number containing 6–15 digits / 含 6 至 15 位數字的電話號碼"},"countryCode":{"type":"string"},"locale":{"type":"string","enum":["en","zh"],"default":"en"},"model":{"type":"string","enum":["openai","gemini"]},"includeAi":{"type":"boolean","default":true},"dayMasterGan":{"type":"string","maxLength":2},"birthYear":{"type":"integer"},"sex":{"type":"string","enum":["male","female"]}}}}}},"responses":{"200":{"description":"Number analysis and optional narrative / 數字分析與選用的 AI 解讀","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request / 請求資料無效","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid API key / API 金鑰遺失或無效","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Daily request limit reached / 已達每日請求上限","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Service error / 服務錯誤","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/v1/tarot":{"post":{"tags":["AI readings"],"operationId":"generateTarotReading","summary":"Generate tarot reading / 生成塔羅解讀","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cardId":{"type":"integer","minimum":0,"maximum":77,"description":"Random when omitted / 未提供時隨機抽牌"},"reversed":{"type":"boolean","description":"Random when omitted / 未提供時隨機決定正逆位"},"question":{"type":"string","maxLength":500},"model":{"type":"string","enum":["openai","gemini"]}}}}}},"responses":{"200":{"description":"Tarot card and bilingual interpretation / 塔羅牌與雙語解讀","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request / 請求資料無效","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid API key / API 金鑰遺失或無效","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Daily request limit reached / 已達每日請求上限","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Service error / 服務錯誤","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/v1/compatibility":{"post":{"tags":["AI readings"],"operationId":"calculateCompatibility","summary":"Calculate Bazi compatibility / 計算八字合盤","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["person1","person2"],"properties":{"person1":{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date","description":"Birth date / 出生日期"},"time":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d$","default":"12:00","description":"Local birth time / 出生地當地時間"},"city":{"type":"string","maxLength":100,"description":"Birth city; use instead of coordinates / 出生城市，可取代經緯度"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"timezone":{"type":"number","minimum":-12,"maximum":14,"description":"UTC offset in hours / UTC 小時時差"}}},"person2":{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date","description":"Birth date / 出生日期"},"time":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d$","default":"12:00","description":"Local birth time / 出生地當地時間"},"city":{"type":"string","maxLength":100,"description":"Birth city; use instead of coordinates / 出生城市，可取代經緯度"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"timezone":{"type":"number","minimum":-12,"maximum":14,"description":"UTC offset in hours / UTC 小時時差"}}},"locale":{"type":"string","enum":["en","zh"],"default":"en"},"model":{"type":"string","enum":["openai","gemini"]},"includeNarrative":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Both charts, score, and optional narrative / 雙方命盤、分數與選用解讀","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request / 請求資料無效","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid API key / API 金鑰遺失或無效","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Daily request limit reached / 已達每日請求上限","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Service error / 服務錯誤","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/v1/kids":{"post":{"tags":["AI readings"],"operationId":"generateKidsFortune","summary":"Generate kids daily fortune / 生成兒童每日運勢","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["childName","date"],"properties":{"childName":{"type":"string","minLength":1,"maxLength":50},"date":{"type":"string","format":"date","description":"Birth date / 出生日期"},"time":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d$","default":"12:00","description":"Local birth time / 出生地當地時間"},"city":{"type":"string","maxLength":100,"description":"Birth city; use instead of coordinates / 出生城市，可取代經緯度"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"timezone":{"type":"number","minimum":-12,"maximum":14,"description":"UTC offset in hours / UTC 小時時差"},"parentDayMaster":{"type":"string","maxLength":2},"locale":{"type":"string","enum":["en","zh"],"default":"en"},"model":{"type":"string","enum":["openai","gemini"]}}}}}},"responses":{"200":{"description":"Child chart, current-day data, and positive narrative / 兒童命盤、今日資料與正向解讀","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request / 請求資料無效","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid API key / API 金鑰遺失或無效","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Daily request limit reached / 已達每日請求上限","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Service error / 服務錯誤","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/v1/face":{"post":{"tags":["AI readings"],"operationId":"generateFaceReading","summary":"Generate face reading / 生成面相解讀","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["image","mimeType"],"properties":{"image":{"type":"string","format":"byte","description":"Base64 JPEG, PNG, or WebP; 4 MB decoded maximum / Base64 圖片，解碼後最多 4 MB"},"mimeType":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"locale":{"type":"string","enum":["en","zh"],"default":"en"}}}}}},"responses":{"200":{"description":"Structured face reading or refusal / 結構化面相解讀或拒絕原因","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request / 請求資料無效","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid API key / API 金鑰遺失或無效","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Daily request limit reached / 已達每日請求上限","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Service error / 服務錯誤","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/v1/aura":{"post":{"tags":["AI readings"],"operationId":"generateAuraReading","summary":"Generate aura reading / 生成氣場解讀","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["image","mimeType"],"properties":{"image":{"type":"string","format":"byte","description":"Base64 JPEG, PNG, or WebP; 4 MB decoded maximum / Base64 圖片，解碼後最多 4 MB"},"mimeType":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"locale":{"type":"string","enum":["en","zh"],"default":"en"}}}}}},"responses":{"200":{"description":"Structured aura reading or refusal / 結構化氣場解讀或拒絕原因","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request / 請求資料無效","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid API key / API 金鑰遺失或無效","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Daily request limit reached / 已達每日請求上限","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Service error / 服務錯誤","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/v1/couple-face":{"post":{"tags":["AI readings"],"operationId":"generateCoupleFaceReading","summary":"Generate couple face match / 生成夫妻臉分析","description":"Provide either one group image or two separate portraits. / 提供一張合照或兩張個人照。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image":{"type":"string","format":"byte","description":"Base64 JPEG, PNG, or WebP; 4 MB decoded maximum / Base64 圖片，解碼後最多 4 MB"},"mimeType":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"imageA":{"type":"string","format":"byte","description":"Base64 JPEG, PNG, or WebP; 4 MB decoded maximum / Base64 圖片，解碼後最多 4 MB"},"mimeA":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"imageB":{"type":"string","format":"byte","description":"Base64 JPEG, PNG, or WebP; 4 MB decoded maximum / Base64 圖片，解碼後最多 4 MB"},"mimeB":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"locale":{"type":"string","enum":["en","zh"],"default":"en"}},"oneOf":[{"required":["image","mimeType"]},{"required":["imageA","mimeA","imageB","mimeB"]}]}}}},"responses":{"200":{"description":"Structured couple face reading or refusal / 結構化夫妻臉分析或拒絕原因","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request / 請求資料無效","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid API key / API 金鑰遺失或無效","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Daily request limit reached / 已達每日請求上限","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Service error / 服務錯誤","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Create an API key at https://d8ly.app/settings/api-keys"}}}}