처음 붙이신다면 붙이기 안내판부터 보십시오 — 키 받기부터 화면에 넣는 법, 오류 처리, 점검표까지 한 장에 있습니다. 이 페이지는 주소별 상세 문서입니다.
만세력(년·월·일·시주)·24절기·일진·한 달 표·대운·음양력을 JSON으로 돌려주고, 그 위에 완성 풀이(기본 풀이 · 열한 가지 풀이 · 궁합 · 오늘의 기운)를 완성 문장으로 돌려줍니다. 계산은 표준 만세력이며 공개값·한국천문연구원 자료와 대조해 검증했습니다. 풀이는 규칙 조립(생성 모델 없음)이라 같은 사주면 같은 글입니다. 요청 본문(생년월일)은 기록하지 않습니다.
인증
헤더 x-api-key: sk_... 또는 Authorization: Bearer sk_.... 응답 헤더 X-RateLimit-Remaining(분당), X-Monthly-Remaining(월간).
엔드포인트
| 방식 | 경로 | 설명 |
|---|---|---|
| GET | /v1/health | 상태 (키 불필요) |
| GET | /v1/me | 계약 단위는 호출(usage.count) — byFeature·people 은 늘 0입니다. 내 키·요금제·한도·이번 달 사용량·이벤트 칸 켜짐·연령 기준 · usage.people(이번 달 이 키로 풀이를 본 사람 수 — 생년월일은 저장하지 않고 되돌릴 수 없는 표식으로만 셈) |
| GET/POST | /v1/reading | 완성 풀이 — 신강약(15만 명식 분포 백분위)·용신·격국·오행 치우침·십신을 근거와 함께, 화면용 일곱 칸(outline), 완성 문장(prose: 제목·요약·문단마다 근거·한계·전문). length=short|normal|long(short는 맛보기·호출 0회), tone=talk|calm|plain, name, category=overview|love|money|career|children|parents|relationships|friends|partner|elements|health(열한 가지 풀이, 풀이마다 1회). 응답에 minor{under14,under19,asOf}·events[]·버전 칸(readingVersion·proseVersion·category.version) |
| GET/POST | /v1/daily | 오늘의 기운(오늘의 운세) — 그날의 일진이 이 사주에 어떻게 닿는지. 세 문단(오늘 닿는 기운 · 곁 자리와 오늘 · 오늘 살릴 것)과 근거. ?date=2001-04-30&time=13:30, 볼 날짜는 on=2026-09-20(비우면 오늘·한국 날짜). 같은 사람·같은 날이면 같은 글. 전체 키는 호출 0회(월 계약에 포함 — 매일 여는 거리라서). 맞춤 키에 넣는 값은 협의 |
| GET/POST | /v1/match | 궁합 — 두 사람 {a:{date,time,isFemale,name}, b:{…}, length}(GET은 dateA·timeA·dateB·timeB). 일간 관계·곁 자리·서로 채우는 것·묶임과 부딪힘을 근거와 완성 문장으로. 점수·판정 없음(정책). 호출 2회 |
| POST | /v1/me/policy | 회사별 연령 기준 {minAge: 0|14|19} — 기준 미만 생년월일은 403 AGE_RESTRICTED(호출 셈 안 함). 기본 0(가족 풀이 가능) |
| POST | /v1/me/events | 이벤트 칸 켜기/끄기 {enabled: true|false} — 기본 켜짐(새 이벤트가 나오면 응답 events에 자동 추가) |
| POST | /v1/keys/signup | 운영에서는 닫힘(403 NO_FREE_KEY) — 무료 체험 키 없음. 키는 결제로 발급 |
| POST | /v1/keys/rotate | 키 교체 — 새 키 발급(한 번만 표시), 옛 키 즉시 폐기, 월 사용량 이월 |
| GET/POST | /v1/readings | 여러 풀이를 한 번에 — {date,time,isFemale,categories:["love","friends","parents"]}. 응답 data.categories 에 풀이별 글, data.prose 는 한 번만. 풀이가 몇이든 호출 1회(응답 data.counted). 부르신 순서 그대로 나가고 순서는 data.order 에도 적혀 있습니다. 따로 세 번 부르면 3회. 한 번에 5개까지. 안 든 옵션이 섞이면 403·셈 0 |
| POST | /v1/support | 문의 접수(키 불필요) {email, category, message} — 이메일로 답 |
| GET/POST | /v1/manse | 년·월·일·시주, 십신, 오행, 음력 날짜. ?date=2001-04-30&time=13:30&trueSolarTime=true. detail=full이면 지장간·12운성·납음·공망·신살·형파해·대운(isFemale 필요)까지. isLunar=true면 음력 입력 |
| GET/POST | /v1/daeun | 대운 10개(양남음녀 순행·음남양녀 역행, 절까지 일수÷3). isFemale 필수 |
| GET | /v1/calendar/convert | 음양력 변환. ?direction=solar-to-lunar&year=2025&month=10&day=6 / lunar-to-solar&isLeapMonth=true |
| GET | /v1/solar-terms?year=2026 | 24절기 절입 시각(한국시) |
| GET | /v1/day-pillar?date=2024-01-01 | 일진 |
| GET | /v1/calendar/month?year=2024&month=1 | 한 달 만세력 표 |
| POST | /v1/chances | 내부 전용 — 외부(기본 정보) 키는 403. 세 번의 기회(지나간·지금·다가올 해). category: money, career, love, partner, children, relationships, health, elements, overview |
| GET | /v1/openapi.json | OpenAPI 명세 |
묶음(옵션)과 키 — V2 맞춤
키마다 옵션을 골라 넣습니다. 계산(만세력·대운·달력·절기·음양력)과 맛보기(짧은 기본 풀이, 호출 0회)는 어느 키에나 들어 있습니다. 고르는 옵션 열둘: 완성 풀이 본문(보통·긴 길이·이름) · 풀이 열하나(성향·연애·돈재물·직장사업·가족자녀·부모·친구관계·친구·배우자·오행·건강) · 궁합. 오늘의 기운은 전체 키에 들어 있고(호출 0회), 맞춤 키에 넣는 값은 협의합니다. 전체 키에는 옵션이 다 들어 있고, 맞춤 키에는 고른 것만 들어갑니다(예: 연애 풀이 + 궁합). 들어 있지 않은 옵션을 부르면 403 FEATURE_NOT_INCLUDED(호출 셈 안 함). 들어 있는 옵션은 GET /v1/me의 features에 보입니다.
계약 단위는 '호출'입니다. /v1/readings 로 여러 풀이를 한 묶음으로 부르면 풀이가 셋이든 다섯이든 호출 1회입니다. 풀이를 하나씩 따로 부르면 부른 수만큼 셉니다 — 묶어 부르시는 쪽이 싸고 빠릅니다(왕복이 줄고, 같은 사주 계산을 나눠 쓰기 때문입니다).
키 받기
요금 페이지에서 결제하면 키가 즉시 발급됩니다 — 정가 29,900원/월(부가세 별도), 계약일부터 첫 한 달 50%. 전체 키는 기능 전부, 맞춤 키는 고른 묶음만 들어가며 값은 같습니다. 무료 체험 키는 없습니다. 대량은 문의. 응답 헤더로 남은 한도를 알려주고, 문서는 이 페이지와 /v1/openapi.json(포스트맨·스웨거로 불러오기)입니다. 자바스크립트 SDK와 AI 에이전트용 MCP 서버는 저장소 saju-api/sdk, saju-api/mcp에 있습니다.
예시
curl "http://localhost:8787/v1/manse?date=2001-04-30&time=13:30" -H "x-api-key: $KEY"
// JavaScript (fetch)
const r = await fetch(BASE + "/v1/manse?date=2001-04-30&time=13:30", { headers: { "x-api-key": KEY } });
const { data } = await r.json();
# Python (표준 라이브러리만)
import json, urllib.request
req = urllib.request.Request(BASE + "/v1/manse?date=2001-04-30&time=13:30", headers={"x-api-key": KEY})
data = json.load(urllib.request.urlopen(req))["data"]
응답이 그려지는 모습 (예시)
아래 표는 /v1/manse?date=2001-04-30&time=13:30 응답값만으로 그린 기본 명식표입니다. 색·글꼴·배치·캐릭터는 전부 여러분(앱) 몫입니다 — 저희는 값만 드립니다.
| 시주 | 일주 | 월주 | 년주 | |
|---|---|---|---|---|
| 간지 | 己未 기미 | 癸亥 계해 · 일간 | 壬辰 임진 | 辛巳 신사 |
같은 응답의 오행 개수(목0 화1 토3 금1 수3)로 막대·원형 차트를, detail=full의 지장간·12운성·신살로 펼침 화면을, /v1/calendar/month 한 번으로 만세력 달력 화면을 만들 수 있습니다. 위 값은 전부 실제 계산 결과입니다.
버전·변경 정책
/v1 응답 필드는 빼거나 뜻을 바꾸지 않습니다(추가만). 바꿔야 하면 /v2를 열고 v1은 최소 6개월 유지합니다. 규칙표·계산 방식 변경은 meta.version과 문서 변경 기록에 남깁니다.
오류
{ "success": false, "error": { "code", "message" } } — 400 VALIDATION_ERROR · 401 API_KEY_REQUIRED/INVALID_API_KEY/KEY_REVOKED/KEY_EXPIRED · 402 QUOTA_EXHAUSTED(월 한도) · 403 FEATURE_NOT_INCLUDED(이 키에 없는 묶음, 호출 셈 안 함)/PLAN_REQUIRED/AGE_RESTRICTED(회사 연령 기준 미만, 호출 셈 안 함)/FORBIDDEN · 404 NOT_FOUND/CATEGORY_NOT_READY · 429 RATE_LIMITED(분당 — 다음 분에 풀림, Retry-After 없음)
개인화 옵션 정리
손님(앱)마다 다르게 줄 수 있는 설정 전부입니다. 안 주면 기본값으로 동작합니다.
| 옵션 | 값 | 기본 | 뜻 |
|---|---|---|---|
time | HH:MM | 없음(시주 없이 계산) | 출생 시각. 없으면 시주 없이 계산하고 assumedNoon 표시 |
detail | basic·full | basic | full = 지장간·12운성·신살·납음·공망·형파해·대운까지 |
isFemale | true·false | 없음 | 대운 방향(양남음녀 순행) 계산에 필수. 없으면 대운만 null |
isLunar+isLeapMonth | true·false | isLunar만 false | 음력 생일 입력(1901~2099). 음력이면 isLeapMonth 필수 — 윤달 여부를 모르면 평달로 추정하지 않고 400으로 알려드립니다 |
trueSolarTime+longitude | true / 124~132 | false / 126.98(서울) | 진태양시(경도 4분/도) — 일주·시주에만 적용, 절입 판정은 표준시 |
locale | ko·han | ko | 표기 우선(한글·한자) — 응답엔 둘 다 들어 있음 |
asOfYear | 연도 | 올해 | (내부 전용 chances) 기준 연도 고정 — 검사·재현용 |
frame | threeTimes·lifeStage | threeTimes | (내부 전용 chances) 지나간·지금·다가올 ↔ 초년·중년·말년 프레임 |
sections | true·false | false | (내부 전용 chances) 섹션 계약 reading 추가 — 공급 상태(contentStatus·reviewStatus)를 분리 표기, 완성 원고는 없으므로 text=null |
length | short·normal·long | short | (reading·match) 풀이 길이. short=맛보기(호출 0회, 어느 키에나), normal·long=1회 — '완성 풀이 본문' 묶음이 든 키 |
tone | talk·calm·plain | 기본 말투 | (reading·match) 말투 — 문장만 바뀌고 판정·근거는 같음 |
name | 문자열 | 없음 | (reading·match) 이름을 부르는 풀이 — '완성 풀이 본문' 묶음. 저장하지 않음 |
category | overview·love·money·career·children·parents·relationships·friends·partner·elements·health | 없음 | (reading) 열한 가지 풀이 — 나의 성향·연애·돈재물·직장사업·가족자녀·부모·친구인간관계·친구·배우자·오행·건강. 어느 요금제나, 풀이마다 호출 1회. 배우자는 isFemale을 주면 관행대로 별을 잡고, 없으면 추정하지 않고 두 별을 함께 읽습니다. 건강은 병·수명·몸의 부위·진단·치료를 말하지 않고 기운을 쓰고 채우는 결만 읽습니다(의학 정보가 아닙니다) |
signature | off | 켜짐 | (reading·match) 풀이 끝 서명 숨김 — 유료 요금제만 |
옛 표준시(1908~11·1954~61)와 서머타임(1948~60·1987~88)은 옵션이 아니라 자동으로 환산되며 historicClockApplied로 알려드립니다.
검증 근거 (요약)
| 검증 | 규모·결과 | 보고서 |
|---|---|---|
| 독립 계산기 2종 교차(한국 ssaju·중국 lunar-javascript) | 가상 인물 764,000명 — 확인된 우리 쪽 결함 0건, 남은 차이는 전수 규명(시간대·경계 관행) | SOAK-REPORT-2026-09-08 |
| 합성 사례 자동 검사(불변식·정책·차분) | 10,000건 통과, 단언 66,858개 | GIHOE-10K-REPORT-2026-09-09 |
| 한국천문연구원 공식 음양력 전수 대조 | 진행 중 — 1901-01-01~2009-06-27 39,625일: 일진 불일치 0, 음력 날짜 불일치 240일 = 1903~1911 여덟 달 → 원인(1912년 전 UTC+8 기준) 규명·정정(0.3.0) | KASI-대조진행-2026-09-10 |
| 공개 만세력 값 대조 | 일주 17개 날짜·8개 연대, 절기 10개 연도 120건(날짜 불일치 0) | 본 문서·저장소 |
보고서 원문은 요청 시 제공하며(발급 페이지 문의), 서비스 공개와 함께 전문을 게시할 예정입니다. "결함 0"은 위 방법으로 확인된 범위에 대한 서술이며, 발견되는 차이는 이 표에 그대로 적습니다.
한계(정직하게)
- 음력은 천문 계산(삭·동지·중기 규칙)으로 만든 값이며 1901~2099년. 1912년 전은 당시 달력의 기준 시각(UTC+8)을 따릅니다. 한국천문연구원 공식 자료와 전수 대조 진행 중 — 1901년부터 2009년 6월까지 39,625일에서 일진 불일치 0, 음력 날짜 불일치는 1903~1911년 여덟 달(240일)뿐이었고 원인(기준 시각)을 찾아 정정했습니다
- 1954~61 표준시(UTC+8:30)와 1948~60·1987~88 서머타임은 벽시계를 KST로 자동 환산(전환일 경계는 문헌차 주의). 1908~1911 구한말 +8:30도 같은 방식으로 환산
- 규칙표(지장간·12운성·신살·납음·대운)는 공개 고전·백과 표를 옮긴 것이며 유파 차이는 variants 로 표기. 신강·용신·격국은
/v1/reading이 근거와 함께 냅니다(방법은 응답의method칸) - 결과는 참고용이며 시기·운명을 단정하지 않음