사주 만세력 계산 API · 개발자와 AI 에이전트용
LLM이 틀리는 만세력,
계산은 API에 맡기세요.
출생 시각을 보내면 사주팔자·대운·계산 근거를 돌려줍니다. 절기는 천문력으로, 시간은 한국 표준시·서머타임 이력과 진태양시로 계산합니다. 같은 입력이면 언제나 같은 결과가 나오고, 결과마다 어떤 근거로 계산했는지가 함께 옵니다.
시계는 09:30이지만 진태양시로는 08:48:47입니다. 사시(巳)가 아니라 진시(辰)입니다.
Why
만세력은 조회가 아니라 계산입니다
사주 한 장이 맞으려면 아래가 모두 맞아야 합니다. 언어 모델은 여기서 그럴듯하게 틀리고, 틀렸다는 표시도 하지 않습니다.
Response
답과 함께 근거도 돌려줍니다
결과와 그 결과가 나온 과정이 한 응답에 들어 있습니다. 서비스 화면에 보여 주든 에이전트가 설명에 쓰든, 근거를 그대로 인용할 수 있습니다.
사주팔자
연·월·일·시주를 한글과 한자로, 60갑자·천간·지지 인덱스와 함께 제공합니다.
대운
순행·역행, 대운 시작 나이(정확한 분수), 각 대운의 시작·끝 시각을 제공합니다.
십신 · 지장간
요청하면 십신과 지장간을 계산합니다. 승인된 규칙표 버전만 서비스합니다.
계산 근거
기준이 된 입춘·절기의 순간과 오차 범위, 일주 기준 날짜와 율리우스일(JDN)입니다.
시간 해석
UTC 순간, 적용된 표준시·서머타임, 경도 보정, 균시차, 계산 시계 시각, 음력 날짜입니다.
재현 정보
데이터셋, 천문력 해시, tzdb 버전, 적용 정책과 계산 지문. 나중에 같은 결과를 다시 확인할 수 있습니다.
Verified
검증 결과
엔진과 독립적으로 구현한 기준 코드, 그리고 외부 공식 자료와 교차 검증했습니다.
지원 범위: 양력 출생일 1900-01-01 – 2100-12-31, 시간대 Asia/Seoul. 모든 계산이 정수 연산이라 CPU 아키텍처와 관계없이 결과가 같습니다.
For agents
에이전트가 바로 쓸 수 있게
사람이 읽는 이 페이지와 별도로, 에이전트가 기계적으로 읽을 수 있는 입구를 두었습니다.
에이전트용 요약
엔드포인트, 필수 입력, 예시, 응답 해석 규칙을 한 파일에 담았습니다. 전체 설명은 /llms-full.txt.
OpenAPI 3.1 계약
모든 필드의 타입·제약·예시와 오류 코드. 도구 정의(function calling)로 바로 변환할 수 있습니다.
GET api.…/API 루트 안내
API 호스트 루트는 문서·계약·상태 링크를 JSON으로 돌려줍니다. 오류도 모두 같은 JSON 형식입니다.
같은 입력, 같은 답
provenance.dataset_id와 정책이 같으면 결과가 같습니다. 캐시해도 되고, 설명할 때 근거로 인용하면 됩니다.
추측하지 않는 응답
boundary_status가 stable이 아니면 candidates를 모두 사용자에게 보여 주세요. 하나를 고르는 건 에이전트의 몫이 아닙니다.
Quickstart
시작하기
필수 입력은 출생 시각, 시간대, 경도 세 가지입니다. 나머지는 정책 기본값을 쓰고, 적용된 값은 응답의 resolved_policy에 남습니다.
# 양력 1990-03-15 09:30, 서울 curl -X POST https://api.perpetual.smartlink.ai.kr/v1/charts \ -H "X-API-Key: $FOUR_PILLARS_KEY" \ -H "Content-Type: application/json" \ -d '{ "birth": { "calendar": "gregorian", "local_datetime": "1990-03-15T09:30:00", "timezone": "Asia/Seoul", "longitude": 126.978 } }'
{
"pillars": {
"year": { "hangul": "경오", "hanja": "庚午" },
"month": { "hangul": "기묘", "hanja": "己卯" },
"day": { "hangul": "기묘", "hanja": "己卯" },
"hour": { "hangul": "무진", "hanja": "戊辰" }
},
"uncertainty": {
"boundary_status": "stable",
"nearest_boundaries": [
{ "kind": "hour", "distance_seconds": 672.75 }
]
},
"provenance": {
"dataset_id": "kr-v3-2026c-de440s-0c26b6295d",
"calculation_fingerprint": "…"
}
}
| 엔드포인트 | 설명 |
|---|---|
| POST/v1/charts | 사주·대운·파생 관계·불확실성·계산 근거. 양력(gregorian)과 음력(korean_lunar, 윤달 포함) 입력. |
| GET/v1/convert | 양력↔음력 날짜 변환(윤달 포함)과 그 날짜의 일진. ?calendar=korean_lunar&date=1985-08-15 |
| GET/v1/ganzhi | 날짜의 일진, 그날 시작 시점의 연주·월주, 그날 절기가 들어오면 그 시각과 바뀐 기둥. ?date=2024-02-04 |
| GET/v1/policies | 승인된 계산 정책, 기본값, 선택 가능한 옵션(시계 기준·자시 처리·음력 자오선), 데이터셋. |
| GET/v1/solar-terms | 연도별 24절기 시각. ?year=YYYY |
| GET/v1/lunar-months | 음력 연도의 달 목록(윤달 포함). ?lunar_year=YYYY |
옵션: 시계 기준 civil · local_mean_solar · local_apparent_solar(기본),
자시 처리 midnight(기본) · zi_start_23 · split_zi.
오류 형식은 {"code","message","request_id","details"}입니다.
Access
이용 방법
개발팀은 API 키로, AI 에이전트는 호출할 때마다 결제하는 방식으로 이용할 수 있습니다.
X-API-Key헤더 인증, 키별 레이트리밋- 서비스·앱에 사주 계산을 넣으려는 팀
- 출생 정보는 저장하지 않습니다 (
Cache-Control: no-store)
- 계정 없이 호출할 때마다 결제 (x402, Base USDC)
- AI 에이전트가 스스로 결제하고 호출
- 입력 검증에 실패한 요청은 과금하지 않습니다