사주 API 완벽 가이드 2026 — 연동하는 세 가지 방법과 선택 기준 7가지

사주 API 는 생년월일·출생시간·성별·달력 구분(양력/음력)을 입력하면 사주팔자와 만세력 계산 결과를 JSON 형태로 반환하는 REST API 입니다. 운세 앱, 사주 상담 서비스, 궁합 기능을 직접 만들 때 명리학 계산 엔진을 처음부터 구현하는 대신 API 호출 한 번으로 해결할 수 있습니다.

이 글은 사주 API·만세력 API 를 도입하려는 개발자·창업자를 위해 연동하는 세 가지 방법, 선택 기준 7가지, 도입 전 검증 체크리스트를 정리합니다.

사주·만세력을 연동하는 세 가지 방법

서비스에 사주 기능을 넣는 길은 크게 셋입니다. 셋은 대체재가 아니라 목적이 다르므로, 각 방법이 무엇을 해결하고 무엇을 남겨 두는지부터 봅니다.

① 전문 사주·만세력 API 를 연동한다

생년월일·시간·성별을 요청으로 보내면 사주 원국(연·월·일·시주)과 그 위의 분석 결과를 응답으로 받는 방식입니다. 계산과 원표 관리를 제공자가 맡고, 서비스는 결과를 화면에 그리는 일만 합니다.

• 적합 — 실제 사용자에게 내보낼 서비스. 계산이 틀리면 그대로 신뢰 손실이 된다
• 적합 — 출시 일정이 정해져 있다. 명리 계산을 처음부터 구현하면 통상 수개월이 든다
• 적합 — 격국·용신·합형충파해·12운성·신살처럼 해석 단계까지 필요하다
• 감수할 점 — 외부 서비스에 의존하므로 응답 지연과 장애가 그대로 사용자 경험이 되고, 호출량에 따라 비용이 발생한다

② 오픈소스 만세력 라이브러리로 직접 구현한다

음양력 변환과 간지 계산을 담은 공개 패키지를 서버에 올려 직접 계산하는 방식입니다. 비용이 들지 않고 외부 의존도 없습니다. 학습용·토이 프로젝트, 필요한 것이 간지 변환까지인 경우(예: 날짜별 일진 표시), 외부 호출을 둘 수 없는 폐쇄망 환경에 적합합니다.

다만 공개 라이브러리 대부분은 음양력 변환과 사주 원국 산출까지를 다룹니다. 실제 서비스가 필요로 하는 부분은 그 다음입니다 — 격국·용신 판정, 합·형·충·파·해 관계, 12운성, 신살, 대운·세운 흐름. 이 해석 계층은 규칙과 예외가 많아 구현 난도와 검증 비용이 원국 계산보다 훨씬 큽니다.

원국 계산 자체에도 함정이 있습니다.

• 월주는 달이 아니라 절기로 갈린다 — 새해 기준은 1월 1일이 아니라 입춘이고, 매달의 경계도 절기다. 달력 월로 계산하면 경계 부근 생일이 통째로 틀린다
• 윤달 — 윤달이 드는 해에는 같은 달이 두 번 오므로, 음력 연·월·일만으로는 양력 하루가 정해지지 않는다. 평달과 윤달은 약 29일 차이라 월주·일주·시주가 모두 달라진다
• 시주 경계 — 자시를 23:00 로 볼지 23:30 으로 볼지에 따라 시주가 달라지고, 출생지 경도와 균시차를 반영하는 진태양시를 쓰면 또 달라진다

이 셋은 조용히 틀립니다. 대부분의 입력에서는 맞는 값이 나오고 경계 부근에서만 어긋나므로, 눈으로 훑는 검증으로는 잡히지 않습니다.

③ AI 에 연결한다 — 계산은 맡기지 않는다

AI 챗봇이나 에이전트에 사주 기능을 붙이는 방식입니다. 이때 계산과 문장의 역할을 나누는 것이 핵심이며, 그 이유는 다음 장에서 따로 다룹니다. 계산 API 를 AI 에이전트의 도구로 등록하는 MCP(Model Context Protocol) 를 쓰면 코드를 거의 쓰지 않고도 연동됩니다.

목적별로 무엇을 고를까

• 학습·토이 프로젝트 → 오픈소스 라이브러리. 비용이 없고, 틀려도 잃을 것이 없다
• 날짜별 간지·일진만 필요 → 오픈소스 라이브러리로 충분하다
• 사용자에게 내보낼 서비스 → 전문 API. 해석 계층까지 필요하고 오답의 비용이 크다
• AI 챗봇·에이전트 → 전문 API + MCP. 계산과 문장의 역할을 나눈다
• 개발자 없이 웹사이트에 붙이고 싶다 → 설치형 위젯. 코드를 쓰지 않는다

LLM 에게 사주 계산을 시키지 않는다

AI 로 사주 서비스를 만들 때 가장 흔한 실수입니다. 언어모델에게 명리 계산을 맡기면 안 됩니다. 간지·십성·12운성·신살·합충형해·용신·격국·대운·세운은 원표와 규칙이 필요한 결정론적 계산입니다. 언어모델은 그럴듯한 값을 만들어 내며, 그 값이 계산 결과인지 추측인지 읽는 사람은 가릴 수 없습니다. 검증 없이 내보내면 틀린 사주가 서비스 이름을 달고 나갑니다.

역할을 나누면 해결됩니다.

• 계산은 엔진이 — 원국·대운·신살 같은 판정값은 API 나 계산 라이브러리에서 받는다
• 문장은 AI 가 — 받은 판정값을 근거로 읽을 만한 풀이를 쓴다
• 값이 없으면 비워 둔다 — 모델이 채우게 두면 그럴듯한 오답이 나간다. 「미제공」이라 적는 편이 낫다

MCP 는 이 분리를 구조로 강제합니다. 계산 API 를 에이전트의 도구로 등록해 두면, 에이전트가 필요할 때 스스로 호출해 정확한 값을 가져온 뒤 그 값으로만 문장을 씁니다.

사주 API 와 만세력 API 의 차이

만세력 API 는 특정 일자의 천간지지(연주·월주·일주·시주)를 돌려주는 기초 데이터 API 이고, 사주 API(사주팔자 API) 는 그 위에 오행 분포·십신·격국·용신·대운·12운성 같은 해석 모듈을 더한 분석 API 입니다. 만세력만 필요한지, 해석 데이터까지 필요한지가 첫 번째 갈림길입니다.

사주 API 선택 기준 7가지

SAZU 사주 API — 기준 7가지를 모두 충족하는 단일 엔드포인트

사주팔자·만세력·운세를 하나의 REST 엔드포인트로 제공하는 개발자용 API 입니다.

• 분석 모듈 한 벌 — 만세력(천간지지)부터 오행 분포, 십신, 합형충파해, 격국, 용신, 대운, 세운, 12운성, 12신살, 귀인, 공망, 허자, 음양력 변환까지 한 번의 호출로 반환
• 평균 약 100ms 동기 응답, 음력·윤달(isLeapMonth) 입력 지원, 진태양시 보정
• 출생 시간을 모르는 경우도 시주 없이 계산하며, 그 사실이 응답에 표시됩니다
• 무료 키 — 신용카드 없이 발급, 샘플 프로필 기반 샌드박스로 전체 응답 구조 검증
• 유료 플랜 — 실계산과 전체 분석 모듈. 포함 건수에 따라 다섯 가지가 있으며 연간 결제 시 할인이 붙습니다 (요금 안내)
• 공식 TypeScript SDK(@sazuapp/client) 와 MCP 서버(@sazuapp/mcp-server, 유료 전용) — AI 에이전트가 사주 계산을 직접 호출
• API 문서 전체 공개 — 엔드포인트·응답 필드·에러 코드까지 가입 없이 열람

👉 SAZU 사주 API 자세히 보기 · 요금 안내

도입 전 검증 체크리스트

• 1990년대·2000년대 절기 경계일(입춘·경칩 전후) 생년월일로 월주가 정확한지 교차 검증
• 음력 윤달 생일(예: 1998년 윤5월)을 윤달 플래그와 함께 보내 일주·시주 확인
• 23시~1시 출생(야자시·조자시) 케이스의 일주 처리 방식 확인
• 출생 시간을 모를 때 시주 없이 계산되는지, 그 사실이 응답에 표시되는지 확인 — 실제 사용자의 상당수가 시간을 모릅니다
• 응답 스키마의 버전 정책 확인 — 필드가 예고 없이 바뀌면 배포 후에 깨집니다
• 동시 요청 시 rate limit 과 에러 응답 형식 확인

자주 묻는 질문

Q. 사주 API 란 무엇인가요?
A. 생년월일·출생시간·성별·달력 구분을 입력하면 사주팔자와 만세력 계산 결과를 JSON 으로 반환하는 REST API 입니다. 명리학 계산 엔진을 직접 구현하지 않고 사주·운세 기능을 서비스에 넣을 수 있습니다.

Q. 사주·만세력을 연동하는 방법에는 무엇이 있나요?
A. 크게 세 가지입니다. 전문 사주·만세력 API 를 연동하거나, 오픈소스 만세력 라이브러리로 직접 구현하거나, AI 에이전트에 MCP 로 계산 API 를 연결하는 방식입니다. 학습·토이 프로젝트라면 오픈소스가, 사용자에게 내보낼 서비스라면 전문 API 가 적합합니다.

Q. 무료 사주 API 가 있나요?
A. SAZU 는 신용카드 등록 없이 무료 키를 발급하며, 샌드박스에서 실제 응답과 동일한 구조를 검증할 수 있습니다. 무료 한도는 요금 안내에 있습니다. 오픈소스를 직접 운영하는 방법도 있지만 정확도 검증과 유지보수 부담이 따릅니다.

Q. AI 에게 사주 계산을 직접 시켜도 되나요?
A. 권장하지 않습니다. 간지·십성·12운성·신살·용신·격국은 원표와 규칙이 필요한 결정론적 계산이며, 언어모델은 그럴듯한 값을 만들어 냅니다. 계산은 API 나 계산 라이브러리에서 받고, AI 는 그 값을 근거로 문장을 쓰는 역할만 맡기는 구조가 안전합니다.

Q. 코딩을 못해도 사주 API 를 쓸 수 있나요?
A. API 는 개발 지식이 필요하지만, 코드 한 줄로 설치하는 사주 위젯이나 프롬프트만 정의하는 노코드 빌더 SAZU Studio 처럼 개발 없이 도입하는 선택지도 있습니다.

Q. AI 챗봇에서 사주 계산을 호출할 수 있나요?
A. MCP(Model Context Protocol) 서버를 지원하는 API 라면 가능합니다. SAZU 는 @sazuapp/mcp-server 를 제공해 AI 에이전트가 자연어 요청으로 사주 계산을 직접 호출합니다.

마치며

사주 API 선택의 핵심은 정확도 검증 가능성과 분석 모듈의 깊이입니다. 절기 경계·윤달·야자시 같은 경계 사례를 무료 구간에서 직접 검증해 보고 결정하시기 바랍니다.

👉 SAZU 사주 API 시작하기 · API 문서 · MCP 서버로 AI 에서 사주 계산하기 · 코드를 몰라도 되는 연동 — 바이브 코딩 가이드