사주 API 는 생년월일·출생시간·성별·달력 구분(양력/음력)을 입력하면 사주팔자와 만세력 계산 결과를 JSON 형태로 반환하는 REST API 입니다. 운세 앱, 사주 상담 서비스, 궁합 기능을 직접 만들 때 명리학 계산 엔진을 처음부터 구현하는 대신 API 호출 한 번으로 해결할 수 있습니다.
이 글은 사주 API·만세력 API 를 도입하려는 개발자·창업자를 위해 선택 기준 7가지와 도입 전 검증 체크리스트를 정리합니다.
사주 API 와 만세력 API 의 차이
만세력 API 는 특정 일자의 천간지지(연주·월주·일주·시주)를 돌려주는 기초 데이터 API 이고, 사주 API(사주팔자 API) 는 그 위에 오행 분포·십신·격국·용신·대운·12운성 같은 해석 모듈을 더한 분석 API 입니다. 만세력만 필요한지, 해석 데이터까지 필요한지가 첫 번째 갈림길입니다.
사주 API 선택 기준 7가지
| 기준 | 확인할 것 |
|---|---|
| 1. 계산 정확도 | 절기(節氣) 경계 처리, 야자시/조자시 옵션, 진태양시 보정 여부. 같은 생년월일이라도 절기 경계·자시 처리에 따라 월주·시주가 달라집니다. |
| 2. 음력·윤달 지원 | 음력 입력과 윤달(isLeapMonth) 구분을 받는지. 윤달을 구분하지 못하면 윤5월생의 사주가 통째로 어긋납니다. |
| 3. 분석 모듈 범위 | 만세력만인지, 합형충파해·격국·용신·대운·신살까지 주는지. 모듈이 부족하면 결국 명리 로직을 직접 구현하게 됩니다. |
| 4. 응답 속도 | 실시간 서비스라면 100ms 이하 동기 응답이 필요합니다. 대기열·비동기 방식은 UX 를 제약합니다. |
| 5. 무료 체험 | 결제 전에 응답 구조를 검증할 수 있는지. 신용카드 없이 시작 가능한지. |
| 6. 문서·SDK | 공개 API 문서, 타입 정의(TypeScript SDK), 에러 코드표. 문서가 상담 요청 뒤에 숨어 있으면 도입 기간이 길어집니다. |
| 7. AI 에이전트 연동 | MCP(Model Context Protocol) 지원 여부. AI 코딩 도구·챗봇이 사주 계산을 직접 호출하는 구조가 표준화되고 있습니다. |
SAZU 사주 API — 기준 7가지를 모두 충족하는 단일 엔드포인트
사주팔자·만세력·운세를 하나의 REST 엔드포인트로 제공하는 개발자용 API 입니다.
- 15개 분석 모듈 — 만세력(천간지지)부터 오행 분포, 십신, 합형충파해, 격국, 용신, 대운, 세운, 12운성, 12신살, 귀인, 공망, 허자, 음양력 변환까지 한 번의 호출로 반환
- 평균 50ms 이하 동기 응답, 음력·윤달(isLeapMonth) 입력 지원, 진태양시 보정
- 무료 키 — 신용카드 없이 발급, 샘플 프로필 기반 샌드박스로 전체 응답 구조 검증 (월 500회)
- Pro 월 29,900원(연간 결제 시 월 23,900원) — 실계산 월 10,000건 포함, 초과 건당 10원 이하
- 공식 TypeScript SDK(@sazuapp/client) 와 MCP 서버(@sazuapp/mcp-server, Pro 전용) — AI 에이전트가 사주 계산을 직접 호출
- API 문서 전체 공개 — 엔드포인트·응답 필드·에러 코드까지 가입 없이 열람
도입 전 검증 체크리스트
- 1990년대·2000년대 절기 경계일(입춘·경칩 전후) 생년월일로 월주가 정확한지 교차 검증
- 음력 윤달 생일(예: 1998년 윤5월)을 윤달 플래그와 함께 보내 일주·시주 확인
- 23시~1시 출생(야자시·조자시) 케이스의 일주 처리 방식 확인
- 동시 요청 시 rate limit 과 에러 응답 형식 확인
자주 묻는 질문
Q. 사주 API 란 무엇인가요?
A. 생년월일·출생시간·성별·달력 구분을 입력하면 사주팔자와 만세력 계산 결과를 JSON 으로 반환하는 REST API 입니다. 명리학 계산 엔진을 직접 구현하지 않고 사주·운세 기능을 서비스에 넣을 수 있습니다.
Q. 무료 사주 API 가 있나요?
A. SAZU 는 신용카드 등록 없이 무료 키를 발급하며, 샌드박스에서 실제 응답과 동일한 구조를 월 500회까지 검증할 수 있습니다. 오픈소스를 직접 운영하는 방법도 있지만 정확도 검증과 유지보수 부담이 따릅니다.
Q. 코딩을 못해도 사주 API 를 쓸 수 있나요?
A. API 는 개발 지식이 필요하지만, 코드 한 줄로 설치하는 사주 위젯이나 프롬프트만 정의하는 노코드 빌더 SAZU Studio 처럼 개발 없이 도입하는 선택지도 있습니다.
Q. AI 챗봇에서 사주 계산을 호출할 수 있나요?
A. MCP(Model Context Protocol) 서버를 지원하는 API 라면 가능합니다. SAZU 는 @sazuapp/mcp-server 를 제공해 AI 에이전트가 자연어 요청으로 사주 계산을 직접 호출합니다.
마치며
사주 API 선택의 핵심은 정확도 검증 가능성과 분석 모듈의 깊이입니다. 절기 경계·윤달·야자시 같은 경계 사례를 무료 구간에서 직접 검증해 보고 결정하시기 바랍니다.