API 문서
SAZU 사주분석 API를 5분 안에 연동하세요.
최종 업데이트:
사주 계산은 저희가, 서비스는 회원님이 만드시면 됩니다
처음 운세 서비스를 만드시는 분을 위한 전체 그림입니다. 어떤 함수를 부르는지보다, 여섯 조각이 어떤 순서로 이어지고 그중 무엇을 저희가 맡는지를 먼저 보시면 나머지가 쉬워집니다.
사주 계산은 절기·진태양시·음력 변환 등 고급 명리 계산이 얽혀 있어 직접 만들면 오래 걸리고, 틀려도 티가 안 납니다. AI 에게 시키면 더 위험합니다 — 그럴듯한 오답이 나오고 사용자는 그걸 믿습니다.
그 부분만 저희가 맡습니다. 회원님은 어떤 서비스를 만들지에만 집중하시면 됩니다.
각 단계 자세히
SAZU API 대시보드에서 키를 발급합니다. 사용 기간(만료 기간)은 자유롭게 정하시고, 만료되면 추가로 발급받으시면 됩니다.
브라우저에서 직접 호출하실 계획이라면 허용 도메인(CORS) 등록이 필요한데, 이는 유료 키 전용입니다.
고객으로부터 운세 분석용 생년월일시·성별·출생도시 등을 입력받습니다.
입력받은 사주로 SAZU API 에 질의를 보내 명리 계산 결과를 받습니다. 이것이 운세 작성의 소스가 됩니다.
운세별 프롬프트(오늘의 운세 · 연애운 · 평생운 등)를 준비합니다. 적당한 프롬프트가 아직 없으시면 '프롬프트 만들기'에서 운세 토픽과 몇 가지만 선택하시면 원하시는 방향에 맞는 운세 프롬프트가 만들어집니다.
3번(명리 계산 결과) + 4번(운세 프롬프트) 을 합쳐 AI 서비스를 호출하고 운세 문장을 받습니다.
최종적으로 받은 운세 문장을 화면에 표시하시면 됩니다.
명리 판정 자체를 AI 에게 다시 시키지는 마세요 — AI 환각이 발생하여 오류의 원인이 됩니다.
키 발급
SAZU API 를 사용하시려면 먼저 API 키가 필요합니다. 발급은 무료이며, 5분 안에 끝납니다.
- 1
- 2
대시보드에서 키 발급
로그인 후 대시보드의 키 발급 버튼을 누르시면 Free 키가 즉시 생성됩니다. 키 이름·만료일을 설정하실 수 있습니다. 허용 도메인(CORS 화이트리스트)은 Pro 키 전용이라 Free 키 목록에는 등록 버튼이 나타나지 않습니다.
대시보드로 이동 →Free 키 형식 예:
sazu_free_a1b2c3d4... - 3
키를 안전하게 보관
발급 직후 한 번만 전체 키 값이 표시됩니다. 즉시 안전한 곳에 복사·보관해 주세요. 분실 시 새 키를 발급하셔야 합니다.
서버 환경변수 (예:
SAZU_API_KEY) 또는 비밀 저장소 (Vault·1Password·Vercel Env 등) 에 보관하세요. - 4
유료 키가 필요하다면
Free 키로는 유료 토픽까지 샘플 프로필 5종의 입력으로 시험하실 수 있습니다 — 유료 플랜과 동일한 17개 모듈 구조를 고정 데이터로 반환하며, 샘플 입력은
유료 플랜 보기 →GET /v2/sazu/samples로 받으실 수 있습니다. 월 500회·분당 10회 제한이 적용되며, 실제 생년월일 계산이 필요하시면 유료 플랜을 이용해 주십시오. 격국·용신·합형충파해 등 깊은 명리 분석이 필요하시면 유료 구독 후 대시보드에서 유료 키를 추가 발급하실 수 있습니다.
⚠ 키는 절대 브라우저·공개 git 저장소에 노출하지 마세요
HTML·JavaScript 클라이언트 코드·GitHub public 저장소·이메일·메신저 첨부 등에 키를 직접 포함하시면 누구나 회원님의 월 호출 한도를 즉시 소진할 수 있습니다. 항상 서버 사이드 (Next.js API route · Vercel Function · Supabase Edge Function 등) 환경변수에만 보관하세요.
한눈에 비교
Free vs 유료 플랜
2026년 8월 25일 이후 발급된 Free 키는 샌드박스로 동작합니다. 전체 응답 구조를 고정 샘플로 확인하고, 실제 생년월일 계산이 필요해지면 유료 플랜으로 전환하세요.
💰 누구나 운세 1건만 판매해도 구독 비용 즉시 회수 가능
| 항목 | Free | 유료 |
|---|---|---|
| 데이터 | 고정 샘플 문서화된 프로필 5종 | 실제 생년월일 계산 절기·진태양시·음양력 보정 적용 |
| 월 호출 한도 | 500회 | 500 ~ 4,000회 플랜별 |
| 분당 호출 | 10회 | 30 ~ 120회 플랜별 |
| 모듈 | 17개 전체 구조 샘플 데이터 · 유료와 동일한 응답 형태 | 17개 전체 + 격국·용신·신살·허자·합형충파해·원국상호작용·세운·월률분야·종합평가 |
| AI 에이전트 (MCP) | 미지원 | @sazuapp/mcp-server Claude Code · Cursor · Windsurf · Codex · Antigravity |
| TypeScript SDK | @sazuapp/client | @sazuapp/client |
| 키 만료 | 90일 | 만료 없음 (구독 기간) |
| 기술지원 | 커뮤니티 큐 | 우선 응대 (대기열 건너뛰기) |
| 가격 | 무료 | 월 ₩47,500부터 연간 결제 시 최대 30% 할인 |
유료 플랜 모듈은 명리학 정통 해석의 핵심입니다. 격국·용신 없이는 사주의 골격·운의 흐름·개운 방향을 판별할 수 없습니다.
첫 호출 — 30초
발급받은 키로 아래를 그대로 실행하면 만세력 명식 재료(원국·오행·신강약·대운)가 JSON 으로 옵니다. 입력값은 Free 샌드박스 샘플 프로필이라 Free 키로도 정상 응답이 나옵니다. 목적별 다른 토픽(연간·궁합·금전·건강 등)은 참조.
import { SazuClient } from '@sazuapp/client'
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
const result = await sazu.readings.manse({
"birthYear": 1998,
"birthMonth": 5,
"birthDay": 19,
"birthHour": 10,
"birthMinute": 0,
"isFemale": false,
"isLunar": false,
"birthCity": "서울"
})
// result.modules 가 계산 결과, result.guide 가 활용 안내입니다.맞춤 프롬프트 빌더
신규 프로젝트인지, 기존 앱에 추가인지, 노코드 자동화인지에 따라 AI 가 만들 코드가 완전히 달라집니다. 몇 가지 질문에 답하시면 그대로 붙여넣을 수 있는 맞춤 프롬프트를 만들어 드립니다.
맞춤 프롬프트 빌더
몇 가지 질문에 답하시면 AI 에게 그대로 붙여넣을 프롬프트를 만들어 드립니다
코딩을 잘 모르셔도 괜찮아요. 사용 중인 환경에 맞춰 알려드립니다.
현재 어떤 상황이세요?
가장 가까운 것 하나를 선택해 주세요.
인증
모든 API 요청에 아래 두 헤더 형식 중 하나를 포함하세요. 두 형식 모두 동일하게 동작합니다.
권장: x-api-key
x-api-key: sazu_free_xxxx... 또는 sazu_pro_xxxx...대안: Authorization: Bearer (REST 관용)
Authorization: Bearer sazu_free_xxxx... 또는 sazu_pro_xxxx...Postman·Swagger·OpenAPI 코드 생성기 등 표준 Bearer 인증을 사용하는 도구 호환용.
INVALID_API_KEY
키 값 자체가 틀렸을 때. 대시보드에서 키를 다시 복사하세요.
KEY_REVOKED
키가 폐기됐을 때. 새 키를 발급하고 코드를 업데이트하세요.
AUTH_UNAVAILABLE
인증 서버 일시 장애. 잠시 후 재시도하세요.
🔧 환경변수 설정 후 반드시 재배포
Netlify · Vercel · Cloudflare 등 호스팅 환경에서는 환경변수를 추가만 해도 이미 배포된 함수에 자동 반영되지 않습니다. 환경변수 등록 후 반드시 "Trigger Deploy" · "Redeploy" 를 한 번 실행해야 새 값이 적용됩니다.
검증: 함수 첫 줄에 console.log('key length:', process.env.SAZU_API_KEY?.length) 를 추가한 뒤 함수 로그(Netlify Functions logs · Vercel logs 등) 에서 출력을 확인하세요. 값이 0 이거나 undefined 이면 환경변수가 함수 런타임에 주입되지 않은 상태입니다.
도메인 화이트리스트 (CORS)
기본적으로 모든 호출은 서버 사이드(Origin 헤더 없음)로 가정합니다. 브라우저에서 직접 호출하려면 키별 허용 도메인 등록이 필요합니다.
권장: 서버 사이드 호출
자체 백엔드(Next.js API route, Vercel Functions, Cloudflare Worker 등)에서 SAZU API 를 호출하고 결과만 프론트엔드로 전달하는 패턴. API 키는 서버 환경변수로만 보관되어 노출 위험 0.Origin 헤더 없는 요청은 도메인 등록 없이도 항상 통과합니다.
대안: 브라우저 직접 호출 (유료 키만)
정적 사이트 등 백엔드 없이 브라우저에서 직접 호출해야 한다면, Pro 키에 허용 도메인을 반드시 먼저 등록하세요. 등록하면 그 순간부터 등록 도메인과 sazu.app 외의 브라우저 호출이 403 ORIGIN_NOT_ALLOWED 로 차단됩니다. 등록 전에는 이 차단이 적용되지 않으므로, 키가 브라우저에 노출되는 구성이라면 등록을 마친 뒤 배포하세요.
등록 방법
- 대시보드 → API 키 접속
- 유료 활성 키 행 우측의 "도메인" 버튼 클릭
- 모달에서 허용 도메인을 한 줄에 하나씩 입력 (예:
https://your-app.com) - 저장 → 즉시 적용. 비워두면 화이트리스트 해제.
origin 만 입력 (protocol + host[:port]). 경로(/path) · 쿼리(?q=) · 해시(#) 는 포함하지 않습니다.
⚠ 보안 안내
브라우저 직접 호출은 API 키가 클라이언트 JavaScript 코드에 평문 노출되는 구조입니다. DevTools(F12) 로 누구든 추출할 수 있어 도용 시 한도가 제3자에게 소진될 수 있습니다. 화이트리스트는 차선의 보호장치 — 등록된 도메인 외에서는 차단되어 도용 범위는 제한되지만, 가능하면 서버 사이드 호출 패턴을 우선 검토해 주세요.
오류 이력 조회
본인 키로 발생한 최근 4xx/5xx 오류를 직접 조회할 수 있습니다. 본인 데이터만 반환되며, 다른 사용자 데이터는 절대 노출되지 않습니다. 15일간 보존됩니다.
대시보드 → 사용량 페이지의 "최근 호출 로그" 표에서 상태가 빨간색(4xx/5xx)인 행 오른쪽 상세 버튼을 누르면 오류 진단 정보(error.code, errorDetail.issues)를 즉시 확인할 수 있습니다. 외부 도구 (Slack bot · Datadog · 자체 admin) 통합 시 본 API 를 사용하세요.
# 최근 24시간 모든 오류
curl https://api.sazu.app/v2/me/errors \
-H "x-api-key: YOUR_API_KEY"
# 최근 7일, 400 만, 특정 엔드포인트, 최대 50건
curl "https://api.sazu.app/v2/me/errors?since=2026-05-16T00:00:00Z&status=400&endpoint=/v2/sazu/yearly&limit=50" \
-H "x-api-key: YOUR_API_KEY"응답 예시
{
"success": true,
"data": {
"errors": [
{
"requestId": "abc-123",
"createdAt": "2026-05-23T17:00:00Z",
"endpoint": "/v2/sazu/yearly",
"method": "POST",
"statusCode": 400,
"errorCode": "VALIDATION_ERROR",
"errorDetail": {
"issues": [
{ "field": "birthMonth", "code": "too_small", "minimum": 1,
"hint": "JS Date.getMonth() 는 0~11 — getMonth()+1 로 보정 필요" }
]
},
"clientIp": "3.144.126.47",
"userAgent": "node"
}
],
"total": 42,
"limit": 20,
"offset": 0,
"since": "2026-05-22T17:00:00Z"
},
"meta": { "responseMs": 18 }
}⚠ 쿼터 안내
본 API 호출도 일반 호출과 동일하게 월간 quota·분당 rate limit 에 차감됩니다 (어뷰즈 방지). 실시간성이 필요한 경우 이벤트 기반(웹훅) 대신 본 API polling 으로 충분히 대응 가능합니다.
💡 응답의 errorDetail JSON 을 그대로 AI(ChatGPT·Claude·Cursor 등) 에 붙여넣고 "이 오류 원인 알려줘" 라고 물어보면 즉답을 얻을 수 있습니다. sanitized 화이트리스트로 가공된 필드명·기대 타입·hint 정보가 포함되어 있습니다.
AI 코딩 도구로 오류 바로 고치기
400(검증 오류) 응답은 사람이 읽고 고치기 좋은 형태로 구조화되어 있습니다. 응답 전체를 복사해 AI 에게 그대로 주면 코드를 즉시 수정해 줍니다.
1. 400 응답을 그대로 받아 보기
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "요청 형식이 올바르지 않습니다.",
"issues": [
{ "field": "birthYear", "code": "invalid_type", "expected": "number", "received": "undefined", "hint": "필수 필드입니다." },
{ "field": "birthMonth", "code": "invalid_type", "expected": "number", "received": "undefined", "hint": "필수 필드입니다." },
{ "field": "birthDay", "code": "invalid_type", "expected": "number", "received": "undefined", "hint": "필수 필드입니다." }
]
}
}issues[].field = 문제 필드명, expected = 기대 타입,received = 실제로 받은 값, hint = 고치는 방법.
2. AI 에게 붙여넣을 프롬프트 (복사해서 사용)
SAZU API(POST https://api.sazu.app/v2/sazu/manse) 를 호출하는데
아래 400 오류가 납니다. 내 요청 코드를 고쳐 주세요.
[여기에 위 400 응답 JSON 전체를 붙여넣기]
[여기에 내 요청 코드(fetch/axios/curl)를 붙여넣기]
규칙:
- 필수 필드는 birthYear, birthMonth, birthDay (camelCase, "birth" 접두사) 이고 모두 정수다.
- year/month/day (접두사 없음) 는 음양력 변환 API 전용이니 사주 분석에는 쓰지 마라.
- 월(birthMonth)은 1~12 다. JavaScript의 Date.getMonth() 는 0~11 을 주므로 +1 해야 한다.
- 고친 전체 코드와, 무엇을 왜 바꿨는지 한 줄로 알려줘.3. 고친 코드 테스트하기 (성공까지 반복)
# 터미널에서 바로 검증 — 200 이 나오면 성공, 400 이면 응답을 다시 AI 에 주고 반복
# 입력은 샘플 프로필이라 Free 키로도 200 이 나옵니다("API 소개 → Free 키로 시험하기" 참고).
curl -i -X POST https://api.sazu.app/v2/sazu/manse \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"birthYear":1998,"birthMonth":5,"birthDay":19,"birthHour":10,"birthMinute":0,"isFemale":false,"isLunar":false,"birthCity":"서울"}'
# 응답 첫 줄이 HTTP/.. 200 → 성공
# HTTP/.. 400 → 본문의 issues 를 다시 복사해 2번 프롬프트로 반복
# 단 code 가 SAMPLE_PROFILE_REQUIRED 면 코드 문제가 아니라 Free 키의 샘플 제한입니다 —
# GET /v2/sazu/samples 의 input 으로 바꾸거나 유료 플랜으로 전환하세요.과거 오류는 GET /v2/me/errors 로도 다시 받아볼 수 있습니다(위 참고). 테스트 호출도 quota 에 차감되니, 성공 형태를 한 번 확인한 뒤에는 실제 코드에 반영하세요.
v2 리딩 API
v2 는 질문 단위입니다. “연간 운세를 만들려면 어떤 모듈을 켜야 하나”를 고민하는 대신 POST /v2/sazu/yearly 하나를 부르면, 그 목적에 필요한 모듈이 필요한 범위로만 담겨 옵니다 — SAZU 가 자체 운세 상품에 쓰는 바로 그 구성입니다.
사용자 편리성
모듈을 선택하고 조합하는 일이 사라졌습니다. 만들려는 것에 맞는 질문 하나를 선택하시면 끝입니다.
직관성
엔드포인트 이름이 곧 질문입니다 — /v2/sazu/yearly 는 “그 해 1년의 흐름”을 답합니다. 문서를 오가지 않아도 코드가 스스로 읽힙니다.
속도
토픽이 실제로 쓰는 범위만 담아 응답이 가볍습니다 — 전송과 파싱이 빨라지고, LLM 에 넣을 때도 낭비가 없습니다.
개발 편의성
모든 응답에 AI 참조(data.guide)가 내장되어, AI 코딩 도구가 응답만 보고도 무엇을 어떻게 쓸지 압니다.
분석 모듈은 13개의 질문 안에 저마다 제자리를 찾아 담깁니다. 원국은 모든 토픽의 바닥에, 세운은 시기를 묻는 토픽에, 격국·용신은 판단이 필요한 토픽에 놓입니다. 어떤 모듈을 쓸지 선택하는 일은 API 의 몫이고, 회원님은 질문만 선택하시면 됩니다.
| 항목 | 토픽 엔드포인트의 동작 |
|---|---|
| 호출 | POST /v2/sazu/<topic> — 모듈을 선택하는 파라미터가 없습니다 |
| 응답 범위 | 토픽이 실제로 쓰는 범위만 담깁니다 (예: 세운은 1~3개년) |
| 모듈 순서 | 해석 순서 (원국 → 축 → 격국·용신 → 종합) |
| 필드명 | 모든 토픽이 같은 모듈 어휘를 씁니다 — 파싱 코드 하나로 모든 토픽을 읽으실 수 있습니다. |
- 모듈 키·필드명은 토픽이 달라도 같습니다 — 한 번 만든 파싱 코드를 모든 토픽에 그대로 쓰실 수 있습니다.
- modules 파라미터가 없습니다 — 토픽이 목적에 맞는 모듈 세트를 정합니다.
- seun(세운)은 토픽이 실제로 쓰는 연도 범위로 서버가 미리 좁혀 보냅니다 (recentSeuns·upcomingSeuns 원본 배열은 담기지 않습니다).
- 응답 모듈 순서는 해석 순서입니다 — 원국 → 그 토픽의 축 → 격국·용신 → 보조 → 종합(evaluation) 맨 끝.
- 필드는 추가만 됩니다(additive) — 담긴 필드가 이후 버전에서 빠지지 않습니다.
- 모든 응답에 data.guide(AI 참조 안내)와 data.glossary(그 응답에 나온 용어의 뜻)가 실립니다 — 응답만으로 AI 코딩 도구·LLM 이 활용법과 용어를 압니다.
- decadeCount(대운 개수, 11~20)를 받습니다 — 생략하면 13개입니다.
- food 토픽은 foodRotation(daily·weekly·monthly·yearly·decade)으로 식단이 바뀌는 주기를 고릅니다 — 생략하면 daily 로, 자리마다 제 주기로 바뀝니다(밥은 한 달, 국·단백은 닷새, 반찬·차·간식은 하루). 분석은 달라지지 않고 기준을 다시 잡는 간격만 달라집니다.
- food 토픽은 foodPlan(weekly=일주일치 · monthly=한 달치)으로 기간 식단을 함께 받습니다 — 생략하면 foodBalance.plan 이 null 이고 기준일 하루치만 나갑니다.
- food 토픽은 foodAvoid 에 가려야 할 것을 한 줄로 적으면 걸리는 재료를 빼고 상을 차립니다 — 문장으로 「빼고 드세요」라 이르는 것이 아니라 고를 때부터 빠지므로, 표 어디에도 그 재료가 오르지 않습니다.
- food 토픽은 foodPromptGuide: true 로 붙여 쓸 수 있는 가이드 프롬프트를 함께 받습니다 — 프롬프트를 처음 쓰실 때 그대로 쓰시면 됩니다. 기본은 꺼져 있어 응답이 불어나지 않습니다.
- 유료 토픽도 Free 키로 시험하실 수 있습니다 — 샘플 프로필 5종의 입력(목록은 GET /v2/sazu/samples)이면 키 발급일과 관계없이 유료와 같은 구조의 동결 샘플로 응답합니다.
- 다인 토픽(compatibility·love)은 metrics: true 옵트인 시 상대별 관계 등급(상/중/하 — 관계 조화·오행 상보·시기 흐름·종합)을 함께 줍니다. 등급은 문장 표현 강도 조절용이고, 사실 근거는 modules·crossRelations 입니다. 기본값은 미포함.
응답이 곧 안내서입니다 — data.guide
모든 v2 응답에는 AI 참조 안내가 함께 실립니다. 응답을 받은 AI 코딩 도구·LLM 이 문서를 열지 않고도 무엇을 어떻게 쓰면 되는지 즉시 알게 되어, 연동 코드와 풀이 생성이 모두 쉬워집니다 — 응답 전체를 LLM 에 넘기기만 해도 활용법이 저절로 전달됩니다.
"data": {
"topic": "yearly",
"guide": {
"purpose": "그 해의 세운 축 — 직전·당해·다음 해 3개년 세운, …",
"howToUse": [
"data.modules 는 계산된 사실 근거입니다 — 여기에 없는 사실을 지어내지 마세요.",
"data.modules 의 키 순서가 해석 순서입니다 — 원국(fourPillars)부터 그 순서대로 읽고, …",
"prose·note 필드는 판정 결론이 담긴 문장 재료입니다 — 요약과 톤 변환만으로 풀이 문장을 만들 수 있습니다.",
"data.reference 가 해석 기준 시점입니다 — 풀이 문장에 기준 시점을 명시하세요."
]
},
"modules": { … }
}Free 키로 시험하기
유료 토픽을 Free 키로 호출하면 키 발급일과 관계없이 샘플 프로필 5종의 입력에만 응답하며, 응답은 유료 플랜과 같은 구조의 동결 샘플입니다. 연동·화면·로딩 UX 검증을 결제 없이 끝내실 수 있습니다.
샘플 입력은 GET /v2/sazu/samples 로 받으실 수 있습니다 — 응답의 samples[].input 을 요청의 출생 입력으로 그대로 보내시면 됩니다.
무료 토픽 /v2/sazu/manse 는 발급일에 따라 다릅니다 — 2026년 8월 25일 이후 발급된 Free 키는 샌드박스로 동작합니다. 그 전에 발급된 Free 키는 무료 모듈 범위를 실제로 계산해 응답합니다.
| id | 특성 | 입력값 | 확인 용도 |
|---|---|---|---|
| strong-male | 신강 · 남 · 합충 풍부 | 1998-05-19 10:00 · 남 · 서울 | 관계 목록이 길 때의 레이아웃·줄바꿈 |
| weak-female | 신약 · 여 · 대운 역행 | 1970-05-05 10:00 · 여 · 서울 | 대운이 역순일 때의 정렬·나이 표기 |
| unknown-hour | 출생시간 미상 (시주 없음) | 1985-08-12 · 시각 null · 남 · 서울 | 기둥 하나가 비는 화면·null 처리 |
| balanced | 중화 · 관계 희소 | 1972-05-19 10:00 · 남 · 서울 | 합충이 거의 없을 때의 빈 상태 |
| rich-sinsal | 신살 풍부 · 여 | 1993-11-19 10:00 · 여 · 서울 | 뱃지가 많을 때의 넘침·접힘 |
다인 토픽(compatibility·love)은 본인과 상대 전원이 샘플 프로필이어야 합니다. 일치하지 않는 입력은 400 SAMPLE_PROFILE_REQUIRED 로 응답하며, error.details.nearestSample 에 가장 가까운 샘플(어긋난 필드 mismatchedFields, 그대로 보낼 input)이, error.details.samplesEndpoint 에 샘플 목록을 받을 주소가 담깁니다. 성공 응답에는 meta.sample 이 붙어 샘플 여부를 코드에서 구분하실 수 있습니다.
토픽 카탈로그
| 엔드포인트 | 답하는 질문 | 기준 시점 | 플랜 |
|---|---|---|---|
| POST /v2/sazu/manse | 이 사람의 사주 명식은 어떻게 생겼나? | — | 무료 |
| POST /v2/sazu/today | 오늘 하루, 이 사주에 무엇이 작용하나? | date (선택) | 유료 |
| POST /v2/sazu/daily | 그날 일진이 이 사주의 일간에 어떻게 작용하나? | date (선택) | 유료 |
| POST /v2/sazu/monthly | 이번 달(또는 지정한 달)의 흐름은? | month (선택) | 유료 |
| POST /v2/sazu/yearly | 그 해 1년의 흐름은? | year (선택) | 유료 |
| POST /v2/sazu/decade | 지금 대운은 어디쯤이고, 다음 10년은? | — | 유료 |
| POST /v2/sazu/life | 이 사주의 골격과 평생의 큰 흐름은? | — | 유료 |
| POST /v2/sazu/consult | 이 고민, 사주 데이터는 어느 방향을 가리키나? | — | 유료 |
| POST /v2/sazu/compatibility | 이 두(세) 사람 사이에 무엇이 걸려 있나? | — | 유료 |
| POST /v2/sazu/love | 내 연애, 지금 어느 흐름에 있나? (상대가 있으면 그 관계까지) | — | 유료 |
| POST /v2/sazu/money | 재물은 언제, 어떤 구조로 들어오나? | date (선택) | 유료 |
| POST /v2/sazu/health | 어느 기운·장부 계통을 유의해서 보나? | — | 유료 |
| POST /v2/sazu/food | 오늘 무엇을 먹으면 좋은가? | date (선택) | 유료 |
기계가 읽는 카탈로그는 GET /v2/sazu/topics 로도 제공됩니다.
각 모듈의 필드는 토픽마다 아래 「이 요청의 실제 응답 보기」(로그인 후 확인)에서, 필드를 어떻게 쓰는지는 에서 확인하실 수 있습니다. 모듈마다 어느 토픽에 담기는지는 GET /v2/sazu/modules 가 알려 드립니다.
POST/v2/sazu/manse— 만세력 (명식 조회)예제 보기
만세력 화면의 표준 구성입니다. 원국(십성·12운성·지장간 포함)이 바닥이고, 오행 분포와 신강/신약이 첫 진단, 신살이 표기를 채우고, 대운이 시간축을 엽니다. Free 키는 무료 모듈 범위(신살 제외)로 응답합니다.
포함 모듈: fourPillars · elements · sinStrength · sinsal · decadeFortune
import { SazuClient } from '@sazuapp/client'
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
const result = await sazu.readings.manse({
"birthYear": 1998,
"birthMonth": 5,
"birthDay": 19,
"birthHour": 10,
"birthMinute": 0,
"isFemale": false,
"isLunar": false,
"birthCity": "서울"
})
// result.modules 가 계산 결과, result.guide 가 활용 안내입니다.이 요청의 실제 응답 보기
위 요청(샘플 프로필 「신강 · 남 · 합충 풍부」)을 그대로 호출한 응답입니다. 모듈 5종과 함께 guide(활용 안내)·glossary(용어 뜻)가 응답 안에 담겨 옵니다. 긴 배열은 예시 길이로 줄이고 남은 건수를 적어 두었습니다.
받은 값을 문장에 넣기
말단 값을 변수로 꺼내 문장 안에서는 짧게 참조합니다. 이 facts 를 guide.howToUse 와 함께 프롬프트에 실으시면 됩니다.
const { fourPillars, elements, sinStrength, sinsal, decadeFortune } = modules
const yearPillar = fourPillars.year.full
const monthPillar = fourPillars.month.full
const dayPillar = fourPillars.day.full
const hourPillar = fourPillars.hour.full
const strength = sinStrength.strength
const strengthAnalysis = sinStrength.analysis
const decadeDirection = decadeFortune.direction
// elements 는 오행 다섯 키를 가진 객체입니다 — 값만 훑습니다.
const elementLine = Object.values(elements)
.map(({ name, total: { count } }) => `${name} ${count}개`)
.join(' · ')
// 길신 목록 — 흉신은 sinsal.devils 에 같은 모양으로 옵니다.
const sinsalNames = sinsal.angels
.map(({ name }) => `${name}`)
.join(', ')
// 대운은 시작 나이 오름차순입니다 — 나이로 현재 대운을 고르시면 됩니다.
const decadeFlow = decadeFortune.list
.map(({ startAge, full }) => `${startAge}세 ${full}`)
.join(' → ')
const facts = [
`년주는 ${yearPillar}, 월주는 ${monthPillar} 입니다.`,
`일주는 ${dayPillar}, 시주는 ${hourPillar} 입니다.`,
`오행 분포는 ${elementLine} 입니다.`,
`신강약은 ${strength} — ${strengthAnalysis}`,
`신살은 ${sinsalNames} 입니다.`,
`대운은 ${decadeDirection}으로 흐릅니다: ${decadeFlow}`,
]
// guide 와 함께 프롬프트에 싣습니다.
const prompt = [
guide.purpose,
...guide.howToUse,
...facts,
].join('\n')Java · Go 는 응답을 먼저 record · struct 로 매핑한 뒤 같은 순서로 문장을 조립하시면 됩니다 — 꺼내는 필드와 문장 구성은 위와 같습니다.
POST/v2/sazu/today— 오늘의 운세예제 보기
축은 일진 상호작용입니다 — 그날 간지가 일간에 갖는 십성, 원국과의 합충, 발동 신살. 월운·세운은 그 하루를 놓는 맥락으로 최소 범위만 담깁니다. 날짜별 재호출 없이 하루 1건으로 개인화 운세를 만들 수 있습니다.
포함 모듈: fourPillars · dailyInteraction · sinsal · weolun · seun
date: 분석 대상 날짜 (양력 "YYYY-MM-DD"). 생략 시 서버 현재 날짜.
import { SazuClient } from '@sazuapp/client'
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
const result = await sazu.readings.today({
"birthYear": 1998,
"birthMonth": 5,
"birthDay": 19,
"birthHour": 10,
"birthMinute": 0,
"isFemale": false,
"isLunar": false,
"birthCity": "서울",
"date": "2026-08-29"
})
// result.modules 가 계산 결과, result.guide 가 활용 안내입니다.이 요청의 실제 응답 보기
위 요청(샘플 프로필 「신강 · 남 · 합충 풍부」)을 그대로 호출한 응답입니다. 모듈 5종과 함께 guide(활용 안내)·glossary(용어 뜻)가 응답 안에 담겨 옵니다. 긴 배열은 예시 길이로 줄이고 남은 건수를 적어 두었습니다.
받은 값을 문장에 넣기
말단 값을 변수로 꺼내 문장 안에서는 짧게 참조합니다. 이 facts 를 guide.howToUse 와 함께 프롬프트에 실으시면 됩니다.
const { fourPillars, dailyInteraction, sinsal, weolun, seun } = modules
const yearPillar = fourPillars.year.full
const monthPillar = fourPillars.month.full
const dayPillar = fourPillars.day.full
const hourPillar = fourPillars.hour.full
const iljin = dailyInteraction.ilju.ganji
const stemSipseong = dailyInteraction.toDayMaster.stemSipseong
const branchSipseong = dailyInteraction.toDayMaster.branchSipseong
const monthLabel = weolun.currentWeolun.monthLabel
const monthGanji = weolun.currentWeolun.ganji
const seunYear = seun.currentSeun.year
const seunGanji = seun.currentSeun.ganji
const todayRelations = dailyInteraction.relations
.map(({ type, targetPosition, meaning }) => `${type}(${targetPosition}): ${meaning}`)
// 그날 발동한 신살입니다.
const todaySinsal = dailyInteraction.sinsal
.map(({ name, meaning }) => `${name} — ${meaning}`)
// 길신 목록 — 흉신은 sinsal.devils 에 같은 모양으로 옵니다.
const sinsalNames = sinsal.angels
.map(({ name }) => `${name}`)
.join(', ')
const facts = [
`년주는 ${yearPillar}, 월주는 ${monthPillar} 입니다.`,
`일주는 ${dayPillar}, 시주는 ${hourPillar} 입니다.`,
`타고난 신살은 ${sinsalNames} 입니다.`,
`오늘 일진은 ${iljin} 입니다.`,
`일간 기준으로 천간은 ${stemSipseong}, 지지는 ${branchSipseong} 작용입니다.`,
...todayRelations,
...todaySinsal,
`맥락: ${seunYear}년 세운 ${seunGanji}, ${monthLabel} 월운 ${monthGanji}.`,
]
// guide 와 함께 프롬프트에 싣습니다.
const prompt = [
guide.purpose,
...guide.howToUse,
...facts,
].join('\n')Java · Go 는 응답을 먼저 record · struct 로 매핑한 뒤 같은 순서로 문장을 조립하시면 됩니다 — 꺼내는 필드와 문장 구성은 위와 같습니다.
POST/v2/sazu/daily— 일일 운세예제 보기
today 와 축(일진)은 같고 보조 범위가 다릅니다 — today 가 그날 하루에 머무는 반면, daily 는 일진이 약한 주제를 월운→세운→대운 순으로 끌어와 메우는 구독형 구성이라 대운까지 담습니다. 매일 발송하는 구독 운세의 재료입니다.
포함 모듈: fourPillars · dailyInteraction · sinsal · weolun · seun · decadeFortune
date: 분석 대상 날짜 (양력 "YYYY-MM-DD"). 생략 시 서버 현재 날짜.
import { SazuClient } from '@sazuapp/client'
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
const result = await sazu.readings.daily({
"birthYear": 1998,
"birthMonth": 5,
"birthDay": 19,
"birthHour": 10,
"birthMinute": 0,
"isFemale": false,
"isLunar": false,
"birthCity": "서울",
"date": "2026-09-01"
})
// result.modules 가 계산 결과, result.guide 가 활용 안내입니다.이 요청의 실제 응답 보기
위 요청(샘플 프로필 「신강 · 남 · 합충 풍부」)을 그대로 호출한 응답입니다. 모듈 6종과 함께 guide(활용 안내)·glossary(용어 뜻)가 응답 안에 담겨 옵니다. 긴 배열은 예시 길이로 줄이고 남은 건수를 적어 두었습니다.
받은 값을 문장에 넣기
말단 값을 변수로 꺼내 문장 안에서는 짧게 참조합니다. 이 facts 를 guide.howToUse 와 함께 프롬프트에 실으시면 됩니다.
const { fourPillars, dailyInteraction, sinsal, weolun, seun, decadeFortune } = modules
const yearPillar = fourPillars.year.full
const monthPillar = fourPillars.month.full
const dayPillar = fourPillars.day.full
const hourPillar = fourPillars.hour.full
const iljin = dailyInteraction.ilju.ganji
const stemSipseong = dailyInteraction.toDayMaster.stemSipseong
const branchSipseong = dailyInteraction.toDayMaster.branchSipseong
const monthLabel = weolun.currentWeolun.monthLabel
const monthGanji = weolun.currentWeolun.ganji
const seunYear = seun.currentSeun.year
const seunGanji = seun.currentSeun.ganji
const todayRelations = dailyInteraction.relations
.map(({ type, targetPosition, meaning }) => `${type}(${targetPosition}): ${meaning}`)
// 그날 발동한 신살입니다.
const todaySinsal = dailyInteraction.sinsal
.map(({ name, meaning }) => `${name} — ${meaning}`)
// 길신 목록 — 흉신은 sinsal.devils 에 같은 모양으로 옵니다.
const sinsalNames = sinsal.angels
.map(({ name }) => `${name}`)
.join(', ')
// 대운은 시작 나이 오름차순입니다 — 나이로 현재 대운을 고르시면 됩니다.
const decadeFlow = decadeFortune.list
.map(({ startAge, full }) => `${startAge}세 ${full}`)
.join(' → ')
const facts = [
`년주는 ${yearPillar}, 월주는 ${monthPillar} 입니다.`,
`일주는 ${dayPillar}, 시주는 ${hourPillar} 입니다.`,
`타고난 신살은 ${sinsalNames} 입니다.`,
`오늘 일진은 ${iljin} 입니다.`,
`일간 기준으로 천간은 ${stemSipseong}, 지지는 ${branchSipseong} 작용입니다.`,
...todayRelations,
...todaySinsal,
`맥락: ${seunYear}년 세운 ${seunGanji}, ${monthLabel} 월운 ${monthGanji}.`,
`대운 흐름: ${decadeFlow}`,
]
// guide 와 함께 프롬프트에 싣습니다.
const prompt = [
guide.purpose,
...guide.howToUse,
...facts,
].join('\n')Java · Go 는 응답을 먼저 record · struct 로 매핑한 뒤 같은 순서로 문장을 조립하시면 됩니다 — 꺼내는 필드와 문장 구성은 위와 같습니다.
POST/v2/sazu/monthly— 월 운세예제 보기
축은 월률분야(절기 기반 사령)입니다. 세운은 그 달이 놓인 해의 맥락 한 건만, 용신은 그 달의 기운을 유리/불리로 판정할 기준으로 들어갑니다. 신강/신약이 용신 바로 앞에 오는 것은 용신이 거기서 나온 결론이기 때문입니다 — 근거가 결론보다 먼저 읽혀야 풀이가 "왜 그런지"를 말할 수 있습니다.
포함 모듈: fourPillars · weolun · seun · sinStrength · yongsin · sinsal
month: 분석 대상 월 (양력 "YYYY-MM"). 생략 시 서버 현재 월. 지난달·다음달도 정확 산출.
import { SazuClient } from '@sazuapp/client'
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
const result = await sazu.readings.monthly({
"birthYear": 1998,
"birthMonth": 5,
"birthDay": 19,
"birthHour": 10,
"birthMinute": 0,
"isFemale": false,
"isLunar": false,
"birthCity": "서울",
"month": "2026-08"
})
// result.modules 가 계산 결과, result.guide 가 활용 안내입니다.이 요청의 실제 응답 보기
위 요청(샘플 프로필 「신강 · 남 · 합충 풍부」)을 그대로 호출한 응답입니다. 모듈 6종과 함께 guide(활용 안내)·glossary(용어 뜻)가 응답 안에 담겨 옵니다. 긴 배열은 예시 길이로 줄이고 남은 건수를 적어 두었습니다.
받은 값을 문장에 넣기
말단 값을 변수로 꺼내 문장 안에서는 짧게 참조합니다. 이 facts 를 guide.howToUse 와 함께 프롬프트에 실으시면 됩니다.
const { fourPillars, weolun, seun, sinStrength, yongsin, sinsal } = modules
const strength = sinStrength.strength
const strengthAnalysis = sinStrength.analysis
const yearPillar = fourPillars.year.full
const monthPillar = fourPillars.month.full
const dayPillar = fourPillars.day.full
const hourPillar = fourPillars.hour.full
const monthLabel = weolun.currentWeolun.monthLabel
const monthGanji = weolun.currentWeolun.ganji
const termName = weolun.currentWeolun.termInfo.name
const monthGan = weolun.currentWeolun.sipseongRelation.gan
const monthJi = weolun.currentWeolun.sipseongRelation.ji
const nextTermName = weolun.currentWeolun.nextTermTransition.termName
const nextTermDate = weolun.currentWeolun.nextTermTransition.date
const seunYear = seun.currentSeun.year
const seunGanji = seun.currentSeun.ganji
const yongsinElement = yongsin.yongsin.ko
const huisinElement = yongsin.huisin.ko
const gisinElement = yongsin.gisin.ko
const yongsinBasis = yongsin.reasoning
// 길신 목록 — 흉신은 sinsal.devils 에 같은 모양으로 옵니다.
const sinsalNames = sinsal.angels
.map(({ name }) => `${name}`)
.join(', ')
const facts = [
`년주는 ${yearPillar}, 월주는 ${monthPillar} 입니다.`,
`일주는 ${dayPillar}, 시주는 ${hourPillar} 입니다.`,
`${monthLabel} 월운은 ${monthGanji}, 절기는 ${termName} 입니다.`,
`천간은 ${monthGan}, 지지는 ${monthJi} 로 작용합니다.`,
`다음 절기 ${nextTermName} 는 ${nextTermDate} 입니다.`,
`${seunYear}년 세운 ${seunGanji} 흐름 안의 한 달입니다.`,
`도움이 되는 기운은 ${yongsinElement}·${huisinElement} 입니다.`,
`피할 기운은 ${gisinElement} 입니다.`,
`용신 판정 근거: ${yongsinBasis}`,
`신살은 ${sinsalNames} 입니다.`,
]
// guide 와 함께 프롬프트에 싣습니다.
const prompt = [
guide.purpose,
...guide.howToUse,
...facts,
].join('\n')Java · Go 는 응답을 먼저 record · struct 로 매핑한 뒤 같은 순서로 문장을 조립하시면 됩니다 — 꺼내는 필드와 문장 구성은 위와 같습니다.
POST/v2/sazu/yearly— 연간 운세예제 보기
축은 세운이고, 해의 흐름은 앞뒤와 견줘야 읽히므로 직전·당해·다음 3개년이 담깁니다 (v2 토픽 중 유일하게 window 범위). 격국·용신이 판단 프레임을, 종합 평가가 마무리를 맡습니다.
포함 모듈: fourPillars · seun · weolun · decadeFortune · gyeokguk · yongsin · sinsal · evaluation
year: 분석 대상 연도 (숫자). 생략 시 서버 현재 연도.
import { SazuClient } from '@sazuapp/client'
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
const result = await sazu.readings.yearly({
"birthYear": 1998,
"birthMonth": 5,
"birthDay": 19,
"birthHour": 10,
"birthMinute": 0,
"isFemale": false,
"isLunar": false,
"birthCity": "서울",
"year": 2026
})
// result.modules 가 계산 결과, result.guide 가 활용 안내입니다.이 요청의 실제 응답 보기
위 요청(샘플 프로필 「신강 · 남 · 합충 풍부」)을 그대로 호출한 응답입니다. 모듈 8종과 함께 guide(활용 안내)·glossary(용어 뜻)가 응답 안에 담겨 옵니다. 긴 배열은 예시 길이로 줄이고 남은 건수를 적어 두었습니다.
받은 값을 문장에 넣기
말단 값을 변수로 꺼내 문장 안에서는 짧게 참조합니다. 이 facts 를 guide.howToUse 와 함께 프롬프트에 실으시면 됩니다.
const { fourPillars, seun, weolun, decadeFortune } = modules
const { gyeokguk, yongsin, sinsal, evaluation } = modules
const yearPillar = fourPillars.year.full
const monthPillar = fourPillars.month.full
const dayPillar = fourPillars.day.full
const hourPillar = fourPillars.hour.full
const seunYear = seun.currentSeun.year
const seunGanji = seun.currentSeun.ganji
const seunAge = seun.currentSeun.age
const yearGan = seun.currentSeun.sipseongRelation.gan
const yearJi = seun.currentSeun.sipseongRelation.ji
const seunStage = seun.currentSeun.twelveFortune.name
const monthLabel = weolun.currentWeolun.monthLabel
const monthGanji = weolun.currentWeolun.ganji
const gyeokgukName = gyeokguk.name
const yongsinElement = yongsin.yongsin.ko
const huisinElement = yongsin.huisin.ko
const gisinElement = yongsin.gisin.ko
const yongsinBasis = yongsin.reasoning
const phaseTheme = evaluation.lifePhase.current.theme
const phaseSummary = evaluation.lifePhase.current.summary
const keywords = evaluation.personality.keywords.join('·')
const yearRelations = seun.currentSeun.hapChungRelations
.map(({ type, targetPosition, meaning }) => `${type}(${targetPosition}): ${meaning}`)
// 대운은 시작 나이 오름차순입니다 — 나이로 현재 대운을 고르시면 됩니다.
const decadeFlow = decadeFortune.list
.map(({ startAge, full }) => `${startAge}세 ${full}`)
.join(' → ')
// 길신 목록 — 흉신은 sinsal.devils 에 같은 모양으로 옵니다.
const sinsalNames = sinsal.angels
.map(({ name }) => `${name}`)
.join(', ')
// 주의점은 evaluation.personality.cautions 에 같은 모양으로 옵니다.
const traitLines = evaluation.personality.strengths
.map(({ trait, basis }) => `${trait} (근거: ${basis})`)
const facts = [
`년주는 ${yearPillar}, 월주는 ${monthPillar} 입니다.`,
`일주는 ${dayPillar}, 시주는 ${hourPillar} 입니다.`,
`격국은 ${gyeokgukName} 입니다.`,
`${seunYear}년(${seunAge}세) 세운은 ${seunGanji} 입니다.`,
`천간 ${yearGan}, 지지 ${yearJi}, 12운성 ${seunStage}.`,
...yearRelations,
`대운 흐름: ${decadeFlow}`,
`이번 달(${monthLabel})은 ${monthGanji} 입니다.`,
`도움이 되는 기운은 ${yongsinElement}·${huisinElement} 입니다.`,
`피할 기운은 ${gisinElement} 입니다.`,
`용신 판정 근거: ${yongsinBasis}`,
`신살은 ${sinsalNames} 입니다.`,
`지금 국면은 ${phaseTheme} — ${phaseSummary}`,
`성향 키워드: ${keywords}`,
...traitLines,
]
// guide 와 함께 프롬프트에 싣습니다.
const prompt = [
guide.purpose,
...guide.howToUse,
...facts,
].join('\n')Java · Go 는 응답을 먼저 record · struct 로 매핑한 뒤 같은 순서로 문장을 조립하시면 됩니다 — 꺼내는 필드와 문장 구성은 위와 같습니다.
POST/v2/sazu/decade— 대운 10년예제 보기
축은 대운 목록입니다. 세운은 현재 위치를 찍는 한 건만, 용신은 각 대운의 기운을 판정할 기준으로 들어갑니다. 월 운세와 같은 이유로 신강/신약이 용신 앞에 옵니다 — 판정의 근거가 결론보다 먼저 읽혀야 합니다.
포함 모듈: fourPillars · decadeFortune · seun · sinStrength · yongsin · sinsal
import { SazuClient } from '@sazuapp/client'
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
const result = await sazu.readings.decade({
"birthYear": 1998,
"birthMonth": 5,
"birthDay": 19,
"birthHour": 10,
"birthMinute": 0,
"isFemale": false,
"isLunar": false,
"birthCity": "서울"
})
// result.modules 가 계산 결과, result.guide 가 활용 안내입니다.이 요청의 실제 응답 보기
위 요청(샘플 프로필 「신강 · 남 · 합충 풍부」)을 그대로 호출한 응답입니다. 모듈 6종과 함께 guide(활용 안내)·glossary(용어 뜻)가 응답 안에 담겨 옵니다. 긴 배열은 예시 길이로 줄이고 남은 건수를 적어 두었습니다.
받은 값을 문장에 넣기
말단 값을 변수로 꺼내 문장 안에서는 짧게 참조합니다. 이 facts 를 guide.howToUse 와 함께 프롬프트에 실으시면 됩니다.
const { fourPillars, decadeFortune, seun, sinStrength, yongsin, sinsal } = modules
const strength = sinStrength.strength
const strengthAnalysis = sinStrength.analysis
const yearPillar = fourPillars.year.full
const monthPillar = fourPillars.month.full
const dayPillar = fourPillars.day.full
const hourPillar = fourPillars.hour.full
const decadeDirection = decadeFortune.direction
const decadeBasisTerm = decadeFortune.basisTermsName
const currentAge = seun.currentSeun.age
const seunYear = seun.currentSeun.year
const seunGanji = seun.currentSeun.ganji
const yongsinElement = yongsin.yongsin.ko
const huisinElement = yongsin.huisin.ko
const gisinElement = yongsin.gisin.ko
const yongsinBasis = yongsin.reasoning
// 대운은 시작 나이 오름차순입니다 — 나이로 현재 대운을 고르시면 됩니다.
const decadeFlow = decadeFortune.list
.map(({ startAge, full }) => `${startAge}세 ${full}`)
.join(' → ')
// 길신 목록 — 흉신은 sinsal.devils 에 같은 모양으로 옵니다.
const sinsalNames = sinsal.angels
.map(({ name }) => `${name}`)
.join(', ')
const facts = [
`년주는 ${yearPillar}, 월주는 ${monthPillar} 입니다.`,
`일주는 ${dayPillar}, 시주는 ${hourPillar} 입니다.`,
`대운은 ${decadeDirection}이며 ${decadeBasisTerm} 절기를 기준으로 셉니다.`,
`지금 나이는 ${currentAge}세입니다.`,
`대운 흐름: ${decadeFlow}`,
`올해(${seunYear}) 세운 ${seunGanji} 가 그 위에 놓입니다.`,
`도움이 되는 기운은 ${yongsinElement}·${huisinElement} 입니다.`,
`피할 기운은 ${gisinElement} 입니다.`,
`용신 판정 근거: ${yongsinBasis}`,
`신살은 ${sinsalNames} 입니다.`,
]
// guide 와 함께 프롬프트에 싣습니다.
const prompt = [
guide.purpose,
...guide.howToUse,
...facts,
].join('\n')Java · Go 는 응답을 먼저 record · struct 로 매핑한 뒤 같은 순서로 문장을 조립하시면 됩니다 — 꺼내는 필드와 문장 구성은 위와 같습니다.
POST/v2/sazu/life— 평생 흐름예제 보기
평생 풀이의 뼈대입니다. 원국 8글자 사이의 합·형·충·파·해(인접/격각 구분)가 구조를, 격국·용신이 골격 판정을, 대운 전체가 시간축을 만듭니다.
포함 모듈: fourPillars · wongukInteraction · gyeokguk · yongsin · decadeFortune · sinsal · evaluation
import { SazuClient } from '@sazuapp/client'
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
const result = await sazu.readings.life({
"birthYear": 1998,
"birthMonth": 5,
"birthDay": 19,
"birthHour": 10,
"birthMinute": 0,
"isFemale": false,
"isLunar": false,
"birthCity": "서울"
})
// result.modules 가 계산 결과, result.guide 가 활용 안내입니다.이 요청의 실제 응답 보기
위 요청(샘플 프로필 「신강 · 남 · 합충 풍부」)을 그대로 호출한 응답입니다. 모듈 7종과 함께 guide(활용 안내)·glossary(용어 뜻)가 응답 안에 담겨 옵니다. 긴 배열은 예시 길이로 줄이고 남은 건수를 적어 두었습니다.
받은 값을 문장에 넣기
말단 값을 변수로 꺼내 문장 안에서는 짧게 참조합니다. 이 facts 를 guide.howToUse 와 함께 프롬프트에 실으시면 됩니다.
const { fourPillars, wongukInteraction, gyeokguk, yongsin } = modules
const { decadeFortune, sinsal, evaluation } = modules
const yearPillar = fourPillars.year.full
const monthPillar = fourPillars.month.full
const dayPillar = fourPillars.day.full
const hourPillar = fourPillars.hour.full
const gyeokgukName = gyeokguk.name
const gyeokgukLevel = gyeokguk.strength.level
const gyeokgukBasis = gyeokguk.reasoning
const yongsinElement = yongsin.yongsin.ko
const huisinElement = yongsin.huisin.ko
const gisinElement = yongsin.gisin.ko
const yongsinBasis = yongsin.reasoning
const phaseTheme = evaluation.lifePhase.current.theme
const phaseSummary = evaluation.lifePhase.current.summary
const keywords = evaluation.personality.keywords.join('·')
const natalRelations = wongukInteraction.relations
.map(({ type, meaning }) => `${type}: ${meaning}`)
// 대운은 시작 나이 오름차순입니다 — 나이로 현재 대운을 고르시면 됩니다.
const decadeFlow = decadeFortune.list
.map(({ startAge, full }) => `${startAge}세 ${full}`)
.join(' → ')
// 길신 목록 — 흉신은 sinsal.devils 에 같은 모양으로 옵니다.
const sinsalNames = sinsal.angels
.map(({ name }) => `${name}`)
.join(', ')
// 주의점은 evaluation.personality.cautions 에 같은 모양으로 옵니다.
const traitLines = evaluation.personality.strengths
.map(({ trait, basis }) => `${trait} (근거: ${basis})`)
const facts = [
`년주는 ${yearPillar}, 월주는 ${monthPillar} 입니다.`,
`일주는 ${dayPillar}, 시주는 ${hourPillar} 입니다.`,
...natalRelations,
`격국은 ${gyeokgukName}(${gyeokgukLevel}) — ${gyeokgukBasis}`,
`도움이 되는 기운은 ${yongsinElement}·${huisinElement} 입니다.`,
`피할 기운은 ${gisinElement} 입니다.`,
`용신 판정 근거: ${yongsinBasis}`,
`대운 흐름: ${decadeFlow}`,
`신살은 ${sinsalNames} 입니다.`,
`지금 국면은 ${phaseTheme} — ${phaseSummary}`,
`성향 키워드: ${keywords}`,
...traitLines,
]
// guide 와 함께 프롬프트에 싣습니다.
const prompt = [
guide.purpose,
...guide.howToUse,
...facts,
].join('\n')Java · Go 는 응답을 먼저 record · struct 로 매핑한 뒤 같은 순서로 문장을 조립하시면 됩니다 — 꺼내는 필드와 문장 구성은 위와 같습니다.
POST/v2/sazu/consult— 고민 상담예제 보기
상담 풀이의 재료입니다. 축은 월률분야(지금 어느 기운의 구간인가)이고, 용신·격국이 조언의 근거를 만듭니다. 고민 텍스트는 받지 않습니다 — 질문 해석과 문장은 호출자의 LLM 몫이고, 이 토픽은 근거 데이터를 냅니다.
포함 모듈: fourPillars · weolun · seun · yongsin · gyeokguk · decadeFortune · sinsal · evaluation
import { SazuClient } from '@sazuapp/client'
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
const result = await sazu.readings.consult({
"birthYear": 1998,
"birthMonth": 5,
"birthDay": 19,
"birthHour": 10,
"birthMinute": 0,
"isFemale": false,
"isLunar": false,
"birthCity": "서울"
})
// result.modules 가 계산 결과, result.guide 가 활용 안내입니다.이 요청의 실제 응답 보기
위 요청(샘플 프로필 「신강 · 남 · 합충 풍부」)을 그대로 호출한 응답입니다. 모듈 8종과 함께 guide(활용 안내)·glossary(용어 뜻)가 응답 안에 담겨 옵니다. 긴 배열은 예시 길이로 줄이고 남은 건수를 적어 두었습니다.
받은 값을 문장에 넣기
말단 값을 변수로 꺼내 문장 안에서는 짧게 참조합니다. 이 facts 를 guide.howToUse 와 함께 프롬프트에 실으시면 됩니다.
const { fourPillars, weolun, seun, yongsin } = modules
const { gyeokguk, decadeFortune, sinsal, evaluation } = modules
const yearPillar = fourPillars.year.full
const monthPillar = fourPillars.month.full
const dayPillar = fourPillars.day.full
const hourPillar = fourPillars.hour.full
const monthLabel = weolun.currentWeolun.monthLabel
const monthGanji = weolun.currentWeolun.ganji
const seunYear = seun.currentSeun.year
const seunGanji = seun.currentSeun.ganji
const currentAge = seun.currentSeun.age
const gyeokgukName = gyeokguk.name
const yongsinElement = yongsin.yongsin.ko
const huisinElement = yongsin.huisin.ko
const gisinElement = yongsin.gisin.ko
const yongsinBasis = yongsin.reasoning
const phaseTheme = evaluation.lifePhase.current.theme
const phaseSummary = evaluation.lifePhase.current.summary
const keywords = evaluation.personality.keywords.join('·')
// 대운은 시작 나이 오름차순입니다 — 나이로 현재 대운을 고르시면 됩니다.
const decadeFlow = decadeFortune.list
.map(({ startAge, full }) => `${startAge}세 ${full}`)
.join(' → ')
// 길신 목록 — 흉신은 sinsal.devils 에 같은 모양으로 옵니다.
const sinsalNames = sinsal.angels
.map(({ name }) => `${name}`)
.join(', ')
// 주의점은 evaluation.personality.cautions 에 같은 모양으로 옵니다.
const traitLines = evaluation.personality.strengths
.map(({ trait, basis }) => `${trait} (근거: ${basis})`)
const facts = [
`년주는 ${yearPillar}, 월주는 ${monthPillar} 입니다.`,
`일주는 ${dayPillar}, 시주는 ${hourPillar} 입니다.`,
`격국은 ${gyeokgukName} 입니다.`,
`지금은 ${currentAge}세, ${seunYear}년 세운 ${seunGanji} 입니다.`,
`${monthLabel} 월운은 ${monthGanji} 입니다.`,
`대운 흐름: ${decadeFlow}`,
`도움이 되는 기운은 ${yongsinElement}·${huisinElement} 입니다.`,
`피할 기운은 ${gisinElement} 입니다.`,
`용신 판정 근거: ${yongsinBasis}`,
`신살은 ${sinsalNames} 입니다.`,
`지금 국면은 ${phaseTheme} — ${phaseSummary}`,
`성향 키워드: ${keywords}`,
...traitLines,
]
// guide 와 함께 프롬프트에 싣습니다.
const prompt = [
guide.purpose,
...guide.howToUse,
...facts,
].join('\n')Java · Go 는 응답을 먼저 record · struct 로 매핑한 뒤 같은 순서로 문장을 조립하시면 됩니다 — 꺼내는 필드와 문장 구성은 위와 같습니다.
POST/v2/sazu/compatibility— 관계 궁합예제 보기
관계 해석의 재료입니다. 두 사람 사이의 합·형·충·파·해 매칭(crossRelations — 문장 요약 prose 포함)과 서로의 결핍 오행을 채워 주는지(elementComplement)가 상대별로 실립니다. 상대는 partners 배열로 1~3명, 인원수와 무관하게 호출 1건입니다.
포함 모듈: fourPillars · wongukInteraction · elements · gyeokguk · yongsin · decadeFortune · sinsal · evaluation
import { SazuClient } from '@sazuapp/client'
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
const result = await sazu.readings.compatibility({
"birthYear": 1998,
"birthMonth": 5,
"birthDay": 19,
"birthHour": 10,
"birthMinute": 0,
"isFemale": false,
"isLunar": false,
"birthCity": "서울",
"partners": [
{
"birthYear": 1993,
"birthMonth": 11,
"birthDay": 19,
"birthHour": 10,
"birthMinute": 0,
"isFemale": true,
"isLunar": false,
"birthCity": "서울",
"label": "A"
}
]
})
// result.modules 가 계산 결과, result.guide 가 활용 안내입니다.이 요청의 실제 응답 보기
위 요청(샘플 프로필 「신강 · 남 · 합충 풍부」)을 그대로 호출한 응답입니다. 모듈 8종과 함께 guide(활용 안내)·glossary(용어 뜻)가 응답 안에 담겨 옵니다. 긴 배열은 예시 길이로 줄이고 남은 건수를 적어 두었습니다.
받은 값을 문장에 넣기
말단 값을 변수로 꺼내 문장 안에서는 짧게 참조합니다. 이 facts 를 guide.howToUse 와 함께 프롬프트에 실으시면 됩니다.
const { fourPillars, wongukInteraction, elements, gyeokguk } = modules
const { yongsin, decadeFortune, sinsal, evaluation } = modules
const yearPillar = fourPillars.year.full
const monthPillar = fourPillars.month.full
const dayPillar = fourPillars.day.full
const hourPillar = fourPillars.hour.full
const gyeokgukName = gyeokguk.name
const yongsinElement = yongsin.yongsin.ko
const huisinElement = yongsin.huisin.ko
const gisinElement = yongsin.gisin.ko
const yongsinBasis = yongsin.reasoning
const phaseTheme = evaluation.lifePhase.current.theme
const phaseSummary = evaluation.lifePhase.current.summary
const keywords = evaluation.personality.keywords.join('·')
// elements 는 오행 다섯 키를 가진 객체입니다 — 값만 훑습니다.
const elementLine = Object.values(elements)
.map(({ name, total: { count } }) => `${name} ${count}개`)
.join(' · ')
const natalRelations = wongukInteraction.relations
.map(({ type, meaning }) => `${type}: ${meaning}`)
// 대운은 시작 나이 오름차순입니다 — 나이로 현재 대운을 고르시면 됩니다.
const decadeFlow = decadeFortune.list
.map(({ startAge, full }) => `${startAge}세 ${full}`)
.join(' → ')
// 길신 목록 — 흉신은 sinsal.devils 에 같은 모양으로 옵니다.
const sinsalNames = sinsal.angels
.map(({ name }) => `${name}`)
.join(', ')
// 주의점은 evaluation.personality.cautions 에 같은 모양으로 옵니다.
const traitLines = evaluation.personality.strengths
.map(({ trait, basis }) => `${trait} (근거: ${basis})`)
const facts = [
`년주는 ${yearPillar}, 월주는 ${monthPillar} 입니다.`,
`일주는 ${dayPillar}, 시주는 ${hourPillar} 입니다.`,
`격국은 ${gyeokgukName}, 오행 분포는 ${elementLine} 입니다.`,
...natalRelations,
`도움이 되는 기운은 ${yongsinElement}·${huisinElement} 입니다.`,
`피할 기운은 ${gisinElement} 입니다.`,
`용신 판정 근거: ${yongsinBasis}`,
`대운 흐름: ${decadeFlow}`,
`신살은 ${sinsalNames} 입니다.`,
`지금 국면은 ${phaseTheme} — ${phaseSummary}`,
`성향 키워드: ${keywords}`,
...traitLines,
]
// 상대별 값은 partners[] 로 옵니다.
const partnerFacts = partners.flatMap((partner) => {
const partnerLabel = partner.label
const crossProse = partner.crossRelations.prose
const lackingSelf = partner.elementComplement.lackingSelf.join('·')
const lackingPartner = partner.elementComplement.lackingPartner.join('·')
const coveredCount = partner.elementComplement.coveredCount
return [
`${partnerLabel} 와의 관계: ${crossProse}`,
`내게 부족한 기운은 ${lackingSelf}, 상대는 ${lackingPartner} 입니다.`,
`서로 채워 주는 기운은 ${coveredCount}가지입니다.`,
]
})
// guide 와 함께 프롬프트에 싣습니다.
const prompt = [
guide.purpose,
...guide.howToUse,
...facts, ...partnerFacts,
].join('\n')Java · Go 는 응답을 먼저 record · struct 로 매핑한 뒤 같은 순서로 문장을 조립하시면 됩니다 — 꺼내는 필드와 문장 구성은 위와 같습니다.
POST/v2/sazu/love— 연애 운예제 보기
연애 흐름의 재료입니다. 상대는 선택입니다 — 보내지 않으면 본인 연애 흐름만 담기고(data.partners 는 빈 배열), 담기는 모듈은 그대로입니다. 배우자궁(일지) 작용은 원국 상호작용(wongukInteraction)에서 읽고, 월운·세운이 "지금 어느 흐름인가"를 답합니다. 상대를 1~3명 보내면 교차 합형충파해 매칭과 오행 상보가 상대별로 더해집니다.
포함 모듈: fourPillars · wongukInteraction · weolun · seun · elements · gyeokguk · yongsin · decadeFortune · sinsal · evaluation
import { SazuClient } from '@sazuapp/client'
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
const result = await sazu.readings.love({
"birthYear": 1998,
"birthMonth": 5,
"birthDay": 19,
"birthHour": 10,
"birthMinute": 0,
"isFemale": false,
"isLunar": false,
"birthCity": "서울",
"partners": [
{
"birthYear": 1993,
"birthMonth": 11,
"birthDay": 19,
"birthHour": 10,
"birthMinute": 0,
"isFemale": true,
"isLunar": false,
"birthCity": "서울",
"label": "A"
}
]
})
// result.modules 가 계산 결과, result.guide 가 활용 안내입니다.이 요청의 실제 응답 보기
위 요청(샘플 프로필 「신강 · 남 · 합충 풍부」)을 그대로 호출한 응답입니다. 모듈 10종과 함께 guide(활용 안내)·glossary(용어 뜻)가 응답 안에 담겨 옵니다. 긴 배열은 예시 길이로 줄이고 남은 건수를 적어 두었습니다.
받은 값을 문장에 넣기
말단 값을 변수로 꺼내 문장 안에서는 짧게 참조합니다. 이 facts 를 guide.howToUse 와 함께 프롬프트에 실으시면 됩니다.
const { fourPillars, wongukInteraction, weolun, seun, elements } = modules
const { gyeokguk, yongsin, decadeFortune, sinsal, evaluation } = modules
const yearPillar = fourPillars.year.full
const monthPillar = fourPillars.month.full
const dayPillar = fourPillars.day.full
const hourPillar = fourPillars.hour.full
const monthLabel = weolun.currentWeolun.monthLabel
const monthGanji = weolun.currentWeolun.ganji
const seunYear = seun.currentSeun.year
const seunGanji = seun.currentSeun.ganji
const gyeokgukName = gyeokguk.name
const yongsinElement = yongsin.yongsin.ko
const huisinElement = yongsin.huisin.ko
const gisinElement = yongsin.gisin.ko
const yongsinBasis = yongsin.reasoning
const phaseTheme = evaluation.lifePhase.current.theme
const phaseSummary = evaluation.lifePhase.current.summary
const keywords = evaluation.personality.keywords.join('·')
// elements 는 오행 다섯 키를 가진 객체입니다 — 값만 훑습니다.
const elementLine = Object.values(elements)
.map(({ name, total: { count } }) => `${name} ${count}개`)
.join(' · ')
const natalRelations = wongukInteraction.relations
.map(({ type, meaning }) => `${type}: ${meaning}`)
// 대운은 시작 나이 오름차순입니다 — 나이로 현재 대운을 고르시면 됩니다.
const decadeFlow = decadeFortune.list
.map(({ startAge, full }) => `${startAge}세 ${full}`)
.join(' → ')
// 길신 목록 — 흉신은 sinsal.devils 에 같은 모양으로 옵니다.
const sinsalNames = sinsal.angels
.map(({ name }) => `${name}`)
.join(', ')
// 주의점은 evaluation.personality.cautions 에 같은 모양으로 옵니다.
const traitLines = evaluation.personality.strengths
.map(({ trait, basis }) => `${trait} (근거: ${basis})`)
const facts = [
`년주는 ${yearPillar}, 월주는 ${monthPillar} 입니다.`,
`일주는 ${dayPillar}, 시주는 ${hourPillar} 입니다.`,
`격국은 ${gyeokgukName}, 오행 분포는 ${elementLine} 입니다.`,
...natalRelations,
`${seunYear}년 세운 ${seunGanji}, ${monthLabel} 월운 ${monthGanji} 입니다.`,
`대운 흐름: ${decadeFlow}`,
`도움이 되는 기운은 ${yongsinElement}·${huisinElement} 입니다.`,
`피할 기운은 ${gisinElement} 입니다.`,
`용신 판정 근거: ${yongsinBasis}`,
`신살은 ${sinsalNames} 입니다.`,
`지금 국면은 ${phaseTheme} — ${phaseSummary}`,
`성향 키워드: ${keywords}`,
...traitLines,
]
// 상대별 값은 partners[] 로 옵니다.
const partnerFacts = partners.flatMap((partner) => {
const partnerLabel = partner.label
const crossProse = partner.crossRelations.prose
return [
`${partnerLabel} 와의 관계: ${crossProse}`,
]
})
// guide 와 함께 프롬프트에 싣습니다.
const prompt = [
guide.purpose,
...guide.howToUse,
...facts, ...partnerFacts,
].join('\n')Java · Go 는 응답을 먼저 record · struct 로 매핑한 뒤 같은 순서로 문장을 조립하시면 됩니다 — 꺼내는 필드와 문장 구성은 위와 같습니다.
POST/v2/sazu/money— 금전운예제 보기
축은 wealth 모듈입니다 — 원국의 재성 구조와 대운>세운>월운>일운 우선순위(priority 1~4)의 계층별 재물 기운 판정이, 결론 문장(prose·note·basis)과 함께 담깁니다. 판정 근거가 문장으로 실려 있어 그대로 풀이 재료로 쓰면 됩니다.
포함 모듈: fourPillars · wealth · sinStrength · yongsin · seun · decadeFortune · sinsal
date: 분석 기준 날짜 (양력 "YYYY-MM-DD"). 대운·세운·월운·일운 계층이 이 날짜 기준으로 정렬됩니다. 생략 시 서버 현재.
import { SazuClient } from '@sazuapp/client'
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
const result = await sazu.readings.money({
"birthYear": 1998,
"birthMonth": 5,
"birthDay": 19,
"birthHour": 10,
"birthMinute": 0,
"isFemale": false,
"isLunar": false,
"birthCity": "서울",
"date": "2026-08-29"
})
// result.modules 가 계산 결과, result.guide 가 활용 안내입니다.이 요청의 실제 응답 보기
위 요청(샘플 프로필 「신강 · 남 · 합충 풍부」)을 그대로 호출한 응답입니다. 모듈 7종과 함께 guide(활용 안내)·glossary(용어 뜻)가 응답 안에 담겨 옵니다. 긴 배열은 예시 길이로 줄이고 남은 건수를 적어 두었습니다.
받은 값을 문장에 넣기
말단 값을 변수로 꺼내 문장 안에서는 짧게 참조합니다. 이 facts 를 guide.howToUse 와 함께 프롬프트에 실으시면 됩니다.
const { fourPillars, wealth, sinStrength, yongsin } = modules
const { seun, decadeFortune, sinsal } = modules
const yearPillar = fourPillars.year.full
const monthPillar = fourPillars.month.full
const dayPillar = fourPillars.day.full
const hourPillar = fourPillars.hour.full
const wealthElement = wealth.wealthElement
const wealthStorage = wealth.wealthStorage.branch
const canCarry = wealth.carryCapacity.canCarry
const wealthBasis = wealth.wealthElementRole.basis
const strength = sinStrength.strength
const strengthAnalysis = sinStrength.analysis
const yongsinElement = yongsin.yongsin.ko
const huisinElement = yongsin.huisin.ko
const gisinElement = yongsin.gisin.ko
const yongsinBasis = yongsin.reasoning
const seunYear = seun.currentSeun.year
const seunGanji = seun.currentSeun.ganji
const wealthStars = wealth.natalWealth.stars
.map(({ position, char, sipsin }) => `${position} ${char}(${sipsin})`)
.join(', ')
// priority 1~4 순서로 읽으시면 가까운 시기부터 옵니다.
const wealthTiming = wealth.fortuneLayers
.map(({ label, ganji, note }) => `${label}(${ganji}): ${note}`)
// 대운은 시작 나이 오름차순입니다 — 나이로 현재 대운을 고르시면 됩니다.
const decadeFlow = decadeFortune.list
.map(({ startAge, full }) => `${startAge}세 ${full}`)
.join(' → ')
// 길신 목록 — 흉신은 sinsal.devils 에 같은 모양으로 옵니다.
const sinsalNames = sinsal.angels
.map(({ name }) => `${name}`)
.join(', ')
const facts = [
`년주는 ${yearPillar}, 월주는 ${monthPillar} 입니다.`,
`일주는 ${dayPillar}, 시주는 ${hourPillar} 입니다.`,
`재성 오행은 ${wealthElement}, 재고는 ${wealthStorage} 입니다.`,
`원국 재성: ${wealthStars}`,
`신강약은 ${strength} — ${strengthAnalysis}`,
`재를 감당하는지: ${canCarry}`,
`재성 판정 근거: ${wealthBasis}`,
...wealthTiming,
`${seunYear}년 세운 ${seunGanji} · 대운 흐름: ${decadeFlow}`,
`도움이 되는 기운은 ${yongsinElement}·${huisinElement} 입니다.`,
`피할 기운은 ${gisinElement} 입니다.`,
`용신 판정 근거: ${yongsinBasis}`,
`신살은 ${sinsalNames} 입니다.`,
]
// guide 와 함께 프롬프트에 싣습니다.
const prompt = [
guide.purpose,
...guide.howToUse,
...facts,
].join('\n')Java · Go 는 응답을 먼저 record · struct 로 매핑한 뒤 같은 순서로 문장을 조립하시면 됩니다 — 꺼내는 필드와 문장 구성은 위와 같습니다.
POST/v2/sazu/health— 건강운예제 보기
축은 healthBalance 모듈입니다 — 일간 기반 진단(dayMasterFoundation), 오행별 장부·계통 상태(organs), 유의 구조(vulnerabilities), 계층별 운 작용 신호(fortuneInteractions, 대운>세운>월운>일운)가 각각 결론 문장(note·prose)과 함께 담깁니다. 응답에 "의료 조언이 아님" 면책이 항상 실립니다.
포함 모듈: fourPillars · elements · healthBalance · sinStrength · yongsin · seun · sinsal
import { SazuClient } from '@sazuapp/client'
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
const result = await sazu.readings.health({
"birthYear": 1998,
"birthMonth": 5,
"birthDay": 19,
"birthHour": 10,
"birthMinute": 0,
"isFemale": false,
"isLunar": false,
"birthCity": "서울"
})
// result.modules 가 계산 결과, result.guide 가 활용 안내입니다.이 요청의 실제 응답 보기
위 요청(샘플 프로필 「신강 · 남 · 합충 풍부」)을 그대로 호출한 응답입니다. 모듈 7종과 함께 guide(활용 안내)·glossary(용어 뜻)가 응답 안에 담겨 옵니다. 긴 배열은 예시 길이로 줄이고 남은 건수를 적어 두었습니다.
받은 값을 문장에 넣기
말단 값을 변수로 꺼내 문장 안에서는 짧게 참조합니다. 이 facts 를 guide.howToUse 와 함께 프롬프트에 실으시면 됩니다.
const { fourPillars, elements, healthBalance, sinStrength } = modules
const { yongsin, seun, sinsal } = modules
const strength = sinStrength.strength
const strengthAnalysis = sinStrength.analysis
const yearPillar = fourPillars.year.full
const monthPillar = fourPillars.month.full
const dayPillar = fourPillars.day.full
const hourPillar = fourPillars.hour.full
const balanceStatus = healthBalance.balance.status
const dominantElements = healthBalance.balance.dominant.join('·')
const missingElements = healthBalance.balance.missing.join('·')
const balanceNote = healthBalance.balance.note
const disclaimer = healthBalance.disclaimer
const yongsinElement = yongsin.yongsin.ko
const huisinElement = yongsin.huisin.ko
const gisinElement = yongsin.gisin.ko
const yongsinBasis = yongsin.reasoning
const seunYear = seun.currentSeun.year
const seunGanji = seun.currentSeun.ganji
// elements 는 오행 다섯 키를 가진 객체입니다 — 값만 훑습니다.
const elementLine = Object.values(elements)
.map(({ name, total: { count } }) => `${name} ${count}개`)
.join(' · ')
const organLines = healthBalance.organs
.map(({ element, yinOrgan, status }) => `${element}(${yinOrgan}): ${status}`)
const riskLines = healthBalance.vulnerabilities
.map(({ victimElement, victimOrgans }) => `${victimElement} 주의: ${victimOrgans}`)
// 길신 목록 — 흉신은 sinsal.devils 에 같은 모양으로 옵니다.
const sinsalNames = sinsal.angels
.map(({ name }) => `${name}`)
.join(', ')
const facts = [
`년주는 ${yearPillar}, 월주는 ${monthPillar} 입니다.`,
`일주는 ${dayPillar}, 시주는 ${hourPillar} 입니다.`,
`오행 분포는 ${elementLine} 입니다.`,
`오행 균형은 ${balanceStatus} 입니다.`,
`강한 기운은 ${dominantElements}, 없는 기운은 ${missingElements} 입니다.`,
`${balanceNote}`,
...organLines,
...riskLines,
`도움이 되는 기운은 ${yongsinElement}·${huisinElement} 입니다.`,
`피할 기운은 ${gisinElement} 입니다.`,
`용신 판정 근거: ${yongsinBasis}`,
`${seunYear}년 세운 ${seunGanji} 기준으로 올 한 해를 봅니다.`,
`신살은 ${sinsalNames} 입니다.`,
`${disclaimer}`,
]
// guide 와 함께 프롬프트에 싣습니다.
const prompt = [
guide.purpose,
...guide.howToUse,
...facts,
].join('\n')Java · Go 는 응답을 먼저 record · struct 로 매핑한 뒤 같은 순서로 문장을 조립하시면 됩니다 — 꺼내는 필드와 문장 구성은 위와 같습니다.
POST/v2/sazu/food— 식단예제 보기
축은 foodBalance 모듈입니다 — 그날 그 사람의 장바구니가 자리별로(곡류·국·반찬·차·간식·단백) 담기고, 재료마다 왜 골랐는지가 문장으로 함께 옵니다. "덜 쓸 것"은 오행 이름이 아니라 재료 이름으로 나가고, 알레르기·임신·복약 주의가 상에 오른 재료에 대해서만 실립니다. foodPlan 을 주면 닷새·서른날 기간 식단과 장보기 목록까지 한 번에 옵니다. 응답에 "의료 조언이 아님" 면책이 항상 실립니다.
포함 모듈: fourPillars · elements · foodBalance · sinStrength · gyeokguk · yongsin · decadeFortune · seun · weolun · dailyInteraction · sinsal · evaluation
date: 분석 기준 날짜 (양력 "YYYY-MM-DD"). 이 날짜의 일진·절기로 상차림이 정해집니다. 생략 시 서버 현재.
import { SazuClient } from '@sazuapp/client'
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
const result = await sazu.readings.food({
"birthYear": 1998,
"birthMonth": 5,
"birthDay": 19,
"birthHour": 10,
"birthMinute": 0,
"isFemale": false,
"isLunar": false,
"birthCity": "서울",
"date": "2026-09-23",
"foodRotation": "daily",
"foodPlan": "weekly"
})
// result.modules 가 계산 결과, result.guide 가 활용 안내입니다.이 요청의 실제 응답 보기
위 요청(샘플 프로필 「신강 · 남 · 합충 풍부」)을 그대로 호출한 응답입니다. 모듈 12종과 함께 guide(활용 안내)·glossary(용어 뜻)가 응답 안에 담겨 옵니다. 긴 배열은 예시 길이로 줄이고 남은 건수를 적어 두었습니다.
받은 값을 문장에 넣기
말단 값을 변수로 꺼내 문장 안에서는 짧게 참조합니다. 이 facts 를 guide.howToUse 와 함께 프롬프트에 실으시면 됩니다.
const { fourPillars, elements, foodBalance, sinStrength, gyeokguk, yongsin } = modules
const { decadeFortune, seun, weolun, dailyInteraction, sinsal, evaluation } = modules
const yearPillar = fourPillars.year.full
const monthPillar = fourPillars.month.full
const dayPillar = fourPillars.day.full
const hourPillar = fourPillars.hour.full
const strength = sinStrength.strength
const gyeokgukName = gyeokguk.name
const iljin = dailyInteraction.ilju.ganji
const staple = foodBalance.basket.grains.staple.name
const foodWhy = foodBalance.why.join('·')
const cookingHint = foodBalance.cookingHint
const rotationNote = foodBalance.rotation.note
const foodCautions = foodBalance.cautions.join('·')
const disclaimer = foodBalance.disclaimer
const yongsinElement = yongsin.yongsin.ko
const huisinElement = yongsin.huisin.ko
const gisinElement = yongsin.gisin.ko
const yongsinBasis = yongsin.reasoning
const seunYear = seun.currentSeun.year
const seunGanji = seun.currentSeun.ganji
const monthLabel = weolun.currentWeolun.monthLabel
const monthGanji = weolun.currentWeolun.ganji
const phaseTheme = evaluation.lifePhase.current.theme
const phaseSummary = evaluation.lifePhase.current.summary
const keywords = evaluation.personality.keywords.join('·')
// elements 는 오행 다섯 키를 가진 객체입니다 — 값만 훑습니다.
const elementLine = Object.values(elements)
.map(({ name, total: { count } }) => `${name} ${count}개`)
.join(' · ')
// 밥은 바탕(staple)에 이것들을 섞는 모양입니다 — 분량은 담기지 않습니다.
const grainMix = foodBalance.basket.grains.mix
.map(({ name }) => `${name}`)
.join('·')
// 반찬·차·간식·단백은 basket.sides·drinks·snack·protein 에 같은 모양으로 옵니다.
const soupLines = foodBalance.basket.soup
.map(({ name, reason }) => `${name} — ${reason}`)
const sideLines = foodBalance.basket.sides
.map(({ name, reason }) => `${name} — ${reason}`)
// 덜 써도 되는 것 — 오행 이름이 아니라 재료 이름으로 옵니다.
const avoidNames = foodBalance.avoid
.map(({ name }) => `${name}`)
.join(', ')
// 대운은 시작 나이 오름차순입니다 — 나이로 현재 대운을 고르시면 됩니다.
const decadeFlow = decadeFortune.list
.map(({ startAge, full }) => `${startAge}세 ${full}`)
.join(' → ')
// 길신 목록 — 흉신은 sinsal.devils 에 같은 모양으로 옵니다.
const sinsalNames = sinsal.angels
.map(({ name }) => `${name}`)
.join(', ')
// 주의점은 evaluation.personality.cautions 에 같은 모양으로 옵니다.
const traitLines = evaluation.personality.strengths
.map(({ trait, basis }) => `${trait} (근거: ${basis})`)
const facts = [
`년주는 ${yearPillar}, 월주는 ${monthPillar} 입니다.`,
`일주는 ${dayPillar}, 시주는 ${hourPillar} 입니다.`,
`일간은 ${strength}, 격국은 ${gyeokgukName} 입니다.`,
`오행 분포는 ${elementLine} 입니다.`,
`도움이 되는 기운은 ${yongsinElement}·${huisinElement} 입니다.`,
`피할 기운은 ${gisinElement} 입니다.`,
`용신 판정 근거: ${yongsinBasis}`,
`오늘 일진은 ${iljin} 입니다.`,
`${foodWhy}`,
`밥은 ${staple}에 ${grainMix}를 섞습니다.`,
...soupLines,
...sideLines,
`조리 방향: ${cookingHint}`,
`덜 써도 되는 것: ${avoidNames}`,
`주의: ${foodCautions}`,
`${rotationNote}`,
`맥락: ${seunYear}년 세운 ${seunGanji}, ${monthLabel} 월운 ${monthGanji}.`,
`대운 흐름: ${decadeFlow}`,
`신살은 ${sinsalNames} 입니다.`,
`지금 국면은 ${phaseTheme} — ${phaseSummary}`,
`성향 키워드: ${keywords}`,
...traitLines,
`${disclaimer}`,
]
// guide 와 함께 프롬프트에 싣습니다.
const prompt = [
guide.purpose,
...guide.howToUse,
...facts,
].join('\n')Java · Go 는 응답을 먼저 record · struct 로 매핑한 뒤 같은 순서로 문장을 조립하시면 됩니다 — 꺼내는 필드와 문장 구성은 위와 같습니다.
배치 — 여러 토픽을 한 요청으로
항목마다 topic 을 지정하므로 서로 다른 운세를 한 요청에 섞어 담을 수 있고, 같은 토픽만 담으면 그 토픽의 대량 처리가 됩니다 — 이용자마다 다른 운세를 주문하는 흩어진 트래픽과, 한 운세에 몰리는 트래픽을 같은 경로로 처리합니다.
- 분당 요청 한도는 요청 1건으로 계산됩니다 — 여러 건을 묶어 보내면 같은 플랜에서 처리량이 그만큼 늘어납니다.
- 한 요청에 담을 수 있는 건수는 플랜별 상한을 따릅니다(아래 표). 넘기면
BATCH_TOO_MANY_ITEMS로 요청 전체가 거절되며, 오류의maxItems에 그 키의 상한이 담깁니다. - 월간 호출 한도는 성공한 건수만큼 차감되고, 실패한 항목은 차감되지 않습니다.
- 남은 포함량보다 항목이 많으면 넘는 건수만큼 선결제 호출을 한꺼번에 먼저 잡아 두고, 실패한 항목 몫은 되돌립니다. 선결제 호출이 그만큼 남아 있지 않으면 일부만 처리하지 않고
402 QUOTA_EXHAUSTED로 요청 전체가 거절됩니다. - 다인 토픽(compatibility · love)은 상대가 몇 명이든 항목 1건으로 계산됩니다.
love는 상대가 선택이라 혼자서도 부를 수 있습니다. - 항목마다 단건 토픽과 같은 전달 범위가 적용되어, 그 토픽이 실제로 쓰는 범위만 담깁니다.
| 플랜 | 한 요청 최대 건수 | 분당 요청 | 실질 처리량 (분당) |
|---|---|---|---|
| Starter | 50건 | 30회 | 1,500건 |
| Medium | 100건 | 45회 | 4,500건 |
| Standard | 150건 | 60회 | 9,000건 |
| Premium | 200건 | 90회 | 18,000건 |
| Business | 300건 | 120회 | 36,000건 |
실질 처리량은 이론상 최대치입니다. 월 포함량이 먼저 소진되면 그 시점에 멈추고, 무거운 토픽은 건수보다 응답 크기에서 먼저 걸립니다.
/v2/sazu/batch리딩 배치 (여러 토픽 혼합) — 한 요청 건수는 플랜별 상한을 따름
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| items | object[] | 필수 | 계산할 항목 목록. 한 요청에 담을 수 있는 건수는 플랜에 따라 다릅니다(위 표 참고). 넘기면 BATCH_TOO_MANY_ITEMS(400)로 요청 전체가 거절되며, 오류의 maxItems 에 그 키의 상한이 담깁니다. 각 항목은 topic 과 출생 정보를 담으며, 나머지 필드는 해당 토픽의 단건 엔드포인트와 같습니다. 무거운 토픽은 건수보다 응답 크기에서 먼저 걸리며, 계산하지 못한 항목은 BATCH_RESPONSE_TOO_LARGE 로 표시되고 과금되지 않습니다. |
| items[].topic | string | 필수 | 이 항목을 계산할 리딩 토픽 (manse · today · daily · monthly · yearly · decade · life · consult · compatibility · love · money · health · food). |
| items[].partners | object[] | 선택 | 다인 토픽 전용. 상대 1~3명이며 인원수와 무관하게 항목 1건으로 과금됩니다. compatibility 는 필수, love 는 선택입니다(생략하면 본인 연애 흐름만). |
요청 예시
- 항목마다 topic 을 지정하므로 서로 다른 운세를 한 요청에 섞어 담을 수 있습니다.
- 같은 토픽만 담으면 그 토픽의 대량 처리가 됩니다 — 몰림과 흩어짐을 한 경로로 처리합니다.
- 분당 요청 한도는 요청 1건으로 계산되고, 월간 호출 한도는 성공한 건수만큼 차감됩니다.
- 항목마다 단건 토픽과 같은 전달 범위가 적용되어, 응답에는 그 토픽이 실제로 쓰는 범위만 담깁니다.
- 유료 플랜 전용입니다.
import { SazuClient } from '@sazuapp/client'
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
const result = await sazu.readings.batch({
"items": [
{
"topic": "manse",
"birthYear": 1988,
"birthMonth": 5,
"birthDay": 14,
"birthHour": 9
},
{
"topic": "yearly",
"birthYear": 1990,
"birthMonth": 3,
"birthDay": 15,
"year": 2027
}
]
})응답 활용 가이드
응답의 어느 필드를 어떻게 쓰면 되는지 정리했습니다. 판정의 결론과 근거 문장은 응답 안에 (prose·note) 담겨 오고, 활용법은 data.guide 가 응답 안에서 다시 안내합니다 — 이 페이지는 그 지도를 한눈에 보는 자리입니다.
전체 흐름 — 호출부터 완성된 풀이까지
guide 를 통째로 프롬프트에 실으면 지침을 따로 쓰지 않아도 됩니다. 토픽만 바꾸면 목적이 바뀌고, 응답 구조는 같습니다.
// SAZU API v2 리딩 — 서버 라우트 예시 (TypeScript)
import { SazuClient } from '@sazuapp/client'
// 키는 서버 환경변수에만 둡니다 — 브라우저로 내려보내지 않습니다.
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
export async function POST(request: Request) {
// ① 고객이 폼에 입력한 값
const form = await request.json()
// ② v2 리딩 호출 (토픽만 바꾸면 목적이 바뀝니다)
const result = await sazu.readings.money({
birthYear: form.birthYear,
birthMonth: form.birthMonth,
birthDay: form.birthDay,
birthHour: form.birthHour,
birthMinute: form.birthMinute,
isFemale: form.isFemale,
isLunar: form.isLunar,
birthCity: form.birthCity,
})
// ③ 응답이 곧 안내서입니다 — guide 를 그대로 프롬프트에 싣습니다.
const { guide, modules } = result
const prompt = [
guide.purpose, // 이 토픽이 답하는 질문
...guide.howToUse, // 응답 활용 지침 (문장 목록)
'위 지침대로 아래 분석을 풀어 주세요. 존댓말, 6문장 이내.',
JSON.stringify(modules),
].join('\n')
const reading = await ai.complete(prompt)
// ④ 완성된 풀이를 화면으로
return Response.json({ reading })
}필드를 문장에 넣는 법
문체·분량·구성을 직접 정하실 때 씁니다. 값은 그대로 부르고, 판정 근거는 이미 문장으로 담겨 오는 basis·note 를 인용하세요.
// modules 의 값을 문장에 직접 넣는 방법 (money 토픽)
const { summary, fourPillars, wealth } = modules
// 말단 값을 먼저 변수로 꺼냅니다 — 문장 안에서는 짧게 참조합니다.
const { char: dayMaster, element: dayElement } = summary.dayMaster
const { dominant: strongElement, lacking: weakElement } = summary.elementBalance
const ilju = fourPillars.day.full
const { wealthElement } = wealth
const { basis: wealthBasis } = wealth.wealthElementRole
// 시기별 결론 — priority 순서(1이 가장 가까운 층)로 읽습니다.
const timing = [...wealth.fortuneLayers]
.sort((a, b) => a.priority - b.priority)
.map(({ label, ganji, note }) => `${label}(${ganji}): ${note}`)
const facts = [
`일간은 ${dayMaster}(${dayElement}) 입니다.`,
`일주는 ${ilju} 입니다.`,
`오행은 ${strongElement} 가 강하고 ${weakElement} 가 약합니다.`,
`재성 오행은 ${wealthElement} 입니다.`,
// 판정 근거는 이미 문장으로 옵니다 — 그대로 인용하거나 요약하세요.
`재성 판정 근거: ${wealthBasis}`,
...timing,
].join('\n')
const prompt = [
guide.purpose,
...guide.howToUse,
'아래 사실만 근거로 쓰고, 없는 사실은 지어내지 마세요.',
facts,
'어투는 존댓말, 6문장 이내, 마지막 문장은 실천 제안으로 끝내 주세요.',
].join('\n')응답의 공통 구조
모든 v2 리딩은 같은 봉투로 옵니다. 토픽이 달라져도 위치가 바뀌지 않으므로, 파싱 코드는 하나면 됩니다.
| 필드 | 설명 |
|---|---|
| data.topic | 토픽 id — 요청한 엔드포인트 경로 조각과 동일 |
| data.guide | AI 참조 안내 — 이 응답을 어떻게 쓰면 되는지(purpose·howToUse)를 응답 스스로 설명합니다. LLM 프롬프트에 그대로 넣을 수 있습니다 |
| data.reference | 해석된 기준 시점 에코 (기준 시점을 받는 토픽만). 생략한 입력도 서버가 실제로 쓴 값으로 되돌려 줍니다 |
| data.input · data.timezone | 정규화된 출생 입력과 시간대·경도 보정 정보 |
| data.glossary | 용어집 — 이 응답에 실제로 나온 명리 용어의 뜻만 골라 { 용어: 뜻 } 로 담습니다(만세력 하나 기준 40개 안팎). 프롬프트에 함께 넣으면 풀이가 용어를 임의로 정의하지 않습니다. v2 전용입니다 |
| data.modules | 계산 결과 본체. 키·필드명은 v1 과 동일하고, 토픽이 실제로 쓰는 범위로 좁혀 옵니다. 키 순서 = 해석 순서 |
| meta | responseMs·topic·modules(실린 키 목록)·cached·tier. Free 샌드박스 응답에는 sample·sampleProfile·sampleNotice·upgrade 가, 다인 토픽에는 partnerCount 가 더 실립니다. 응답 필드는 추가만 됩니다(additive) — 있던 필드가 사라지지 않습니다 |
data.guide — 응답이 곧 안내서입니다
모든 v2 응답에는 AI 참조 안내가 함께 실립니다. 문서를 열지 않아도, 응답을 받은 AI 코딩 도구·LLM 이 무엇을 어떻게 쓰면 되는지 즉시 압니다 — v2 개발이 쉬워지는 핵심 장치입니다.
guide.purpose는 이 토픽이 답하는 질문입니다 — 풀이의 주제를 잡는 데 쓰세요.guide.howToUse는 활용 지침 문장 목록입니다 — LLM 프롬프트에 그대로 붙여 넣으면 응답 데이터를 올바르게 쓰는 풀이가 나옵니다.- 자동화 파이프라인이라면 응답 전체(
data)를 LLM 에 넘기기만 하면 됩니다 — guide 가 함께 들어가므로 별도의 시스템 프롬프트 없이도 활용법이 전달됩니다.
data.glossary — 용어의 뜻을 응답이 함께 알려 줍니다
풀이가 정확해질수록 읽히지 않는 역설이 있습니다. 「재고는 축으로 보지만 원국에는 없습니다」 는 명리를 아는 사람에게는 정확하지만, 그 서비스를 읽는 일반 독자에게는 통째로 지나가는 줄이 됩니다. 그렇다고 호출자 LLM 이 용어를 스스로 풀게 두면 유파마다 뜻이 갈리는 말을 임의로 정의하고, 같은 말이 호출마다 다르게 풀립니다. 그래서 뜻은 저희가 정해 응답에 실어 보냅니다.
glossary를 프롬프트에 함께 넣고 "이 뜻을 기준으로 삼고 다르게 정의하지 마세요" 한 줄을 더하세요 — 용어가 호출마다 흔들리지 않습니다.- 독자가 모를 만한 말을 쓸 때는 그 자리에서 한 번 풀어 주도록 지시하세요. 뜻풀이 문장은 그대로 읽히도록 한 줄로 짧게 써 두었습니다.
- 그 응답에 실제로 등장한 말만 담깁니다 — 쓰지도 않을 뜻풀이로 프롬프트가 불어나지 않습니다.
- 길흉은 적혀 있지 않습니다. 도화살은 사람을 끌어당기는 힘이고 역마살은 움직임이지 그 자체로 나쁜 것이 아닙니다 — 좋고 나쁨은 사주 전체를 보는 자리에서 정해야 합니다.
| 필드 | 설명 |
|---|---|
| data.glossary | { 용어: 뜻 } 한 겹 객체. 예: { "일간": "사주 여덟 글자 가운데 본인을 나타내는 글자…" } |
숫자를 그대로 옮기지 마세요 — 말로 옮긴 값이 함께 옵니다
내부 값이 그대로 문장에 옮겨 적히는 일이 실제로 있었습니다 — 「원국의 12운성 중 가장 높은 구간은 일주의 제왕 12점」, 「충돌 점수는 S」. 둘 다 저희가 준 값이지만, level 은 12단계 안의 순번이지 점수가 아니고 등급 문자는 최종 독자에게 뜻이 서지 않습니다. 그래서 말로 옮긴 값을 항상 함께 싣습니다. 숫자는 분기·정렬에 쓰시고, 문장에는 말을 쓰세요.
twelveFortune.level(숫자) 대신 `season`(봄·여름·가을·겨울)과 `phase` 를 문장에 쓰세요.scorecard의grade(S·A·B·C·D) 대신 각 항목의 `label` 을 쓰세요 — 지표마다 말이 다릅니다(고름·보통·치우침 / 높음·중간·낮음 / 적음·보통·많음).- 등급을 재계산하거나 100점 만점 점수로 환산하지 마세요. 등급은 문장의 확신 수위를 조절하는 용도입니다.
money — wealth 모듈 활용법
금전운의 축입니다. 판정의 결론과 근거 문장이 응답 안에 담겨 오므로, 필드 위치만 알면 됩니다 — 같은 입력이면 항상 같은 결과가 나옵니다.
- 풀이 문장이 필요하면
prose를 그대로 쓰거나 요약하세요 — 판정 전체가 사람 문장으로 정리되어 있습니다. - 시기별 서술은
fortuneLayers[]를priority(1~4) 순서로 읽으세요 — 각 계층의note가 한 줄 결론입니다. - 득실 판정의 근거 문장은
wealthElementRole.basis한 곳에 실립니다.
| 필드 | 설명 |
|---|---|
| wealthElement | 재성 오행 (한글) |
| wealthElementRole | 재성의 역할 구분(role)과 득실 판정 근거 문장(basis) |
| natalWealth | 원국 재성 분포 — 드러난 자리(stars)·지장간 암장(hiddenStars)·구조 신호(sikSangSaengJae·talJaeRisk) |
| wealthStorage | 재고(財庫) 지지·한자·원국 위치(natalPositions). 비어 있으면 운 도래 시기로 봅니다 |
| carryCapacity | 신강약(strength)과 감당 여부(canCarry) |
| fortuneLayers[] | 계층별 판정 — priority(1~4)·ganji·재성 유입(wealthStarArrives)·재고 도래(storageArrives)·득실(favorable)·한 줄 결론(note) |
| prose | 위 전부를 사람 문장으로 엮은 것 — LLM 에 그대로 넣는 재료 |
health — healthBalance 모듈 활용법
건강운의 축입니다. 응답 블록이 해석 순서대로 오고, 각 블록의 note 와 마지막 prose 에 판정 결론이 담겨 있습니다 — 블록 순서대로 읽어 내려가면 됩니다.
disclaimer는 반드시 화면·문장에 함께 표기하세요 — 전통 명리 관점의 참고 정보이며 의료 조언이 아닙니다.- 풀이 문장이 필요하면
prose를 그대로 쓰거나 요약하세요. - 시기별 유의점은
fortuneInteractions[]를 순서대로 읽으세요 — 각 이벤트의effect(긍정/부정/중립)와note가 결론입니다.
| 필드 | 설명 |
|---|---|
| disclaimer | 항상 실립니다 — 전통 명리 관점의 참고 정보이며 의료 조언이 아닙니다. 화면에 함께 표기해 주세요 |
| dayMasterFoundation | 판정 기반 — 신강약(strength)과 읽는 강도 안내(note) |
| balance | 균형 진단 — status·강한 오행(dominant)·비어 있는 오행(missing) |
| organs[] | 오행 5행 각각의 장부(yinOrgan·yangOrgan)·계통(systems)·자리 수·상태. 신호가 있을 때만 signalNote 가 옵니다 |
| vulnerabilities[] | 유의 구조 — 설명(mechanism)·원국 존재(natalPresence)·계층별 발현 시기(fortuneTriggers, priority 순) |
| fortuneInteractions[] | 계층별 작용 이벤트 — 종류(kind)·긍정/부정/중립(effect)·부재 오행 발현(awakensAbsentElement)·결론 문장(note) |
| prose | 전체 판정을 순서대로 엮은 사람 문장 — LLM 재료 |
food — foodBalance 모듈 활용법
식단의 축입니다. 그날 그 사람의 장바구니가 자리별로 오고, 재료마다 왜 골랐는지(reason)가 함께 담깁니다. 재료 표 자체는 응답에 실리지 않습니다 — 나가는 것은 그 사람·그 시점의 결과 한 건입니다.
disclaimer는 반드시 화면·문장에 함께 표기하세요 — 전통 명리·한의학의 분류에 따른 참고 정보이며 의료 조언이 아닙니다.- 밥은 고르는 것이 아니라 섞는 것입니다 —
basket.grains.staple(바탕)에basket.grains.mix[](섞을 것)를 더해 한 문장으로 쓰세요. 분량은 담기지 않습니다. avoid[]는 오행 이름이 아니라 재료 이름입니다 — 「화 기운을 줄이세요」로 바꾸어 쓰지 마세요. 실천할 수 없는 말이 됩니다.rotation.note는 「이 재료만 먹으라는 말인가」에 대한 답입니다 — 장바구니를 보여 줄 때 함께 실으세요.cautions[]는 알레르기·임신·복약 주의입니다. 상에 오른 재료의 것만 담기며, 빠짐없이 그대로 보여 주세요.- 기간 식단이 필요하면 요청에
foodPlan(weekly=닷새 / monthly=서른날)을 주세요. 주지 않으면plan은null입니다. - 프롬프트를 처음 쓰신다면
foodPromptGuide: true를 주세요 — 이 응답을 문장으로 옮기는 프롬프트가promptGuide에 담겨 옵니다. 그대로 붙여 쓰시면 됩니다.
| 필드 | 설명 |
|---|---|
| disclaimer | 항상 실립니다 — 전통 명리·한의학의 분류에 따른 참고 정보이며 의료 조언이 아닙니다. 화면에 함께 표기해 주세요 |
| basket.grains | 밥 — 바탕(staple)과 섞을 것(mix[]). 분량은 담기지 않습니다 |
| basket.soup / sides / drinks / snack / protein | 국·반찬·차·간식·단백. 각 항목은 id·name·고른 이유(reason) |
| avoid[] | 덜 써도 되는 것 — 재료 이름으로 옵니다. 없으면 빈 배열이며, 「없다」는 것도 읽을 값입니다 |
| why[] | 무엇을 채우고 무엇을 덜 쓰는지의 근거 문장 — 그대로 쓰거나 요약하세요 |
| rotation | 이 장바구니가 얼마나 자주 바뀌는가 — mode·label·설명 문장(note) |
| cookingHint | 조후에서 나온 조리 방향 한 줄 (굽기·삶기 등) |
| seasonal | 절기 맥락 — 절기 이름(jeolgi)과 그 절기의 음식(foods) |
| cautions[] | 상에 오른 재료의 알레르기·임신·복약 주의. 접지 말고 전부 보여 주세요 |
| avoidRequest | 가려 달라 하신 것을 어떻게 읽었는지 — 요청에 foodAvoid 를 줬을 때만. 읽은 문장(text), 걸린 군(groups), 뺀 재료 이름(names), 개수(count). 걸린 재료는 이미 빠진 채로 옵니다 |
| plan | 기간 식단 — 요청에 foodPlan 을 줬을 때만. 주별 요약(grains·soup·protein), 날마다의 상(days[] — 밥·국·단백·반찬·마실 것·간식이 한 줄에, 요일 weekday 와 주 번호 week 포함), 장보기 목록(shoppingList[] — 자리의 우리말 이름 slotLabel 포함, 일수로 묶은 shoppingByDays[]) |
| promptGuide | 붙여 쓸 수 있는 가이드 프롬프트 — 요청에 foodPromptGuide: true 를 줬을 때만. 주지 않으면 null 입니다 |
compatibility·love — 다인 응답 활용법
본인 봉투(data.modules)에 상대별 블록(data.partners[])이 더해집니다. 상대는 1~3명, 인원수와 무관하게 호출 1건입니다. `love` 는 상대가 선택입니다 — 보내지 않으면 data.partners 가 빈 배열로 오고 본인 연애 흐름만 담깁니다. compatibility 는 두 사람 사이를 보는 토픽이라 상대가 필요합니다.
- 상대 없이
love를 부르셨다면 배우자궁(일지) 작용·신살·월운/세운을 근거로 쓰고, 특정 상대와의 궁합을 말하지 마세요 — 없는 상대를 지어내게 됩니다. - 관계 풀이 문장은
partners[].crossRelations.prose를 그대로 쓰거나 요약하세요 — 매칭 결과가 사람 문장으로 정리되어 있습니다. metrics: true옵트인 시 상대별 등급이 옵니다 — 값은 상/중/하와 흐름 상태뿐, 숫자는 싣지 않습니다. 등급은 문장 표현의 강도 조절용이고 사실 근거는modules·crossRelations입니다.
| 필드 | 설명 |
|---|---|
| partners[].label | 요청에서 준 이름, 생략 시 A·B·C |
| partners[].modules | 상대의 계산 모듈 — 본인과 같은 세트 |
| partners[].crossRelations | 두 사람 사이의 합형충파해 — 건별 매칭(matches)·타입별 집계(summary)·LLM 투입용 요약(prose) |
| partners[].elementComplement | 오행 상보 — 서로의 결핍 오행을 채워 주는지 (사실만: lackingSelf·lackingPartner·coveredCount) |
| partners[].metrics | 옵트인 — 관계 조화·오행 상보·시기 흐름·종합 등급(상/중/하)과 두 사람의 대운 흐름 상태 |
LLM 연동 레시피
응답을 그대로 LLM 에 넣어 풀이 문장을 만들 때, 재료의 역할을 나누면 품질이 안정됩니다. 가장 간단한 방법은 data 전체를 넘기는 것 — guide 가 함께 들어가 활용법이 저절로 전달됩니다.
- guide = 사용 설명서.
howToUse를 시스템 프롬프트에 그대로 넣으세요 — 아래 원칙이 전부 담겨 있습니다. - modules = 사실 근거. 간지·십성·12운성 같은 계산값입니다 — "이 데이터에 없는 사실을 만들지 마세요" 와 함께 주세요.
- prose (wealth·healthBalance·crossRelations) = 문장 재료. 판정 결론이 정리된 한국어 문장이라, 요약·톤 변환만 시키면 됩니다.
- metrics = 표현 강도. 등급(상/중/하)에 따라 문장의 확신 수위를 조절하는 용도입니다 — 등급 자체를 재계산하거나 숫자로 환산하도록 시키지 마세요.
- 기준 시점(
data.reference)을 문장에 명시하게 하세요 — "2026년 기준" 이 빠지면 언제의 풀이인지 흐려집니다.
판정 규칙
합·형 판정과 나이·월 표기는 아래 규칙을 따릅니다. 같은 입력이면 언제나 같은 결과가 나옵니다.
형(刑) — 자형과 삼형의 조건이 다릅니다
- · 자형(自刑) — 진·오·유·해. 같은 글자가 겹칠 때만 성립합니다.
- · 삼형(三刑) — 인사신, 축술미. 서로 다른 글자끼리 성립합니다.
- · 상형(相刑) — 자묘.
진·오처럼 자형 목록 안의 서로 다른 글자는 형이 아니며, 사·사처럼 삼형 그룹의 같은 글자도 형이 아닙니다.
부분합 — 왕지(旺支)가 있어야 성립합니다
두 지지만 만나는 자리(세운↔원국, 일진↔원국, 기둥↔기둥)에서는 완성 삼합·방합이 나올 수 없으므로 언제나 부분합입니다. 부분합은 각 국의 중심인 사왕지(자·오·묘·유)가 포함될 때만 성립합니다 — 인·술처럼 생지와 고지만 만나면 기운을 모을 중심이 없어 합을 이루지 못합니다.
세부 갈래는 subType 으로 구분합니다.
- ·
생지반합— 왕지 + 생지 (예: 인·오) - ·
고지반합— 왕지 + 고지 (예: 오·술) - ·
반방합— 방합 그룹의 왕지 + 다른 한 글자 (예: 오·미)
type 은 삼합 · 방합 으로 유지됩니다. 세기를 구분해 가중하시려면 subType 을 보시면 됩니다.
세운의 나이
age 는 세는나이입니다 (해당 연도 − 출생 연도 + 1). 명리 상담에서 "몇 살 운"을 말할 때 쓰는 관습 기준이라 이 값을 기본으로 둡니다. 만 나이는 internationalAge 로 함께 반환하며, 기준은 ageType 에 명시됩니다.
요청의 isInternationalAge 는 대운수(대운 시작 나이) 산출에만 관여하며 세운 age 와는 무관합니다.
월운의 월 표기
사주의 월운은 절기 기준 월건(月建)으로 산출합니다. monthBranchLabel 이 그 값이며 (예: 신월(申月)), 구간 경계는 termInfo · nextTermTransition 이 알려줍니다.
절기월과 음력월은 경계가 달라 서로 대응하지 않습니다. lunarMonthLabel 은 하위 호환용으로 남겨 두었으나 값은 monthBranchLabel 과 같으며, 신규 연동에서는 사용하지 마십시오.
엔드포인트
모든 경로는 https://api.sazu.app 아래에 있고, 인증 헤더는 공통입니다. 운세 재료는 토픽 엔드포인트가, 계정 확인과 보조 기능은 아래 엔드포인트가 맡습니다.
| 엔드포인트 | 용도 |
|---|---|
| POST /v2/sazu/<topic> | 목적별 리딩 13종 — |
| POST /v2/sazu/batch | 여러 토픽을 한 요청으로 (유료 플랜) — |
| GET /v2/sazu/topics | 토픽 카탈로그를 코드가 읽는 형태로 |
| GET /v2/sazu/samples | Free 키로 시험할 샘플 입력 목록 |
| GET /v2/sazu/modules | v2 토픽으로 받을 수 있는 분석 모듈 목록 (15종) |
| POST /v2/calendar/convert | 음양력 변환 |
| GET /v2/me | 현재 키의 요금 등급 · 분당/월간 한도 · 이번 주기 사용량 · 초기화 시각 · 일시 중지 상태 · 선결제 잔여 호출 수를 돌려줍니다. 응답: data: { tier, keyPrefix, rateLimitPerMinute, monthlyQuota, used, remaining, quotaCycleStart, quotaResetAt, banned, bannedUntil, prepaid, plan, cycle, included, overage, rateLimit }. 하위 구조: plan: { tier, kind }, cycle: { startAt, resetAt }, included: { quota, used, remaining }, overage: { policy, perCallKrw, usedThisCycle }, rateLimit: { perMinute }. prepaid 는 선결제 대상 플랜에서 { callsRemaining, overageCallsRemaining, overagePerCallKrw } 이며 그 밖의 플랜에서는 null 입니다 |
| GET /v2/me/errors | 본인 키로 발생한 최근 4xx/5xx 오류 이력 (15일 retention) |
토픽 공통 요청 필드
모든 토픽과 배치 항목이 같은 출생 입력을 받습니다. 토픽마다 기준 시점 필드(year·month·date)와 다인 토픽의 partners 가 더해지며, 토픽 카탈로그의 각 토픽에 적어 두었습니다.
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| birthYear | number | 필수 | 출생년도 (1900~2100). 정수 문자열("1990") 도 허용. |
| birthMonth | number | 필수 | 출생월 (1~12). 정수 문자열("3") 도 허용. JavaScript Date.getMonth() 의 0~11 그대로 전송하면 거부됩니다. |
| birthDay | number | 필수 | 출생일 (1~31). 정수 문자열도 허용. |
| birthHour | number | null | 선택 | 출생시 (0~23), 모르면 null. 정수 문자열도 허용. |
| birthMinute | number | 선택 | 출생분 (0~59), 기본값 0. 정수 문자열도 허용. |
| isFemale | boolean | 선택 | 여성 여부. 누락 시 기본값 false(남성)로 처리되며 응답 헤더 X-Input-Coerced 와 meta.warnings 로 통지합니다. 성별은 사주 결과(대운 진행 방향·해석)에 큰 영향을 주므로 명시 권장. |
| isLunar | boolean | 선택 | 음력 여부, 기본값 false. 음력으로 보내실 때는 윤달 여부(isLeapMonth)를 함께 확인하세요 — 아래 항목 참조. |
| isLeapMonth | boolean | 선택 | 음력 입력이 윤달인지 여부, 기본값 false. isLunar: true 일 때만 사용합니다. 윤달이 드는 해에는 같은 달이 두 번 오므로 연·월·일만으로는 날짜가 하나로 정해지지 않습니다. 예를 들어 1998년에는 5월이 두 번(평5월·윤5월) 있어 음력 1998-05-15 는 양력 6월 9일과 7월 8일 두 가지가 되고, 29일 차이라 월주·일주·시주가 모두 달라집니다. 윤달 출생이면 true 를 보내주세요. [2026-08-22 반영] |
| birthCity | string | 선택 | 출생 도시, 기본값 "서울" |
| locale | "ko" | "han" | 선택 | 한글 또는 한자, 기본값 "ko" |
| decadeCount | number | 선택 | 대운 개수 (11~20, 기본 13) |
| trueSolarTime | boolean | 선택 | 진태양시(경도차 + 균시차) 적용 여부, 기본 false. false = 한국 관습(자시 23:30, 경도차만). true = 공인 방식 진태양시(자시 23:00, 균시차 포함). [2026-07-01 반영] 자세한 차이는 §birthCity 참조. |
| detail | "minimal" | "standard" | "full" | 선택 | 응답 상세 수준. minimal(값만), standard(핵심해석, 기본), full(전체) |
/v2/sazu/samplesFree 키로 시험할 샘플 입력 목록. 응답: data: { samples, total, referenceDate, howToUse }. samples 의 각 항목은 id · label · axis · input 이며, input 을 토픽 요청의 출생 입력으로 그대로 보내시면 Free 키로도 유료 토픽의 샘플 응답을 받으실 수 있습니다. 이 조회는 월 포함량과 선결제 호출을 소모하지 않습니다(분당 한도는 적용).
요청 예시
curl https://api.sazu.app/v2/sazu/samples \
-H "x-api-key: YOUR_API_KEY"/v2/sazu/modulesv2 토픽으로 받을 수 있는 분석 모듈 목록 (15종). 모듈마다 그 모듈이 담기는 토픽 id 목록(topics)이 함께 옵니다 — 어떤 토픽을 불러야 원하는 모듈이 오는지 코드에서 바로 찾으실 수 있습니다. 이 조회는 월 포함량과 선결제 호출을 소모하지 않습니다(분당 한도는 적용).
/v2/calendar/convert음양력 변환
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| year | number | 필수 | 년도. (토픽 요청의 birthYear 와 다른 필드명이니 주의) |
| month | number | 필수 | 월 |
| day | number | 필수 | 일 |
| direction | "toSolar" | "toLunar" | 필수 | 변환 방향. toSolar = 음력→양력, toLunar = 양력→음력 |
| isLeapMonth | boolean | 선택 | 윤달 여부, 기본값 false. direction: "toSolar"(음력→양력) 일 때만 사용합니다. 윤달이 드는 해에는 같은 달이 두 번 오므로, 음력 1998-05-15 는 isLeapMonth 값에 따라 양력 6월 9일(평5월) 또는 7월 8일(윤5월)이 됩니다. 반대 방향(toLunar)은 입력 날짜가 하나로 정해지므로 보내실 필요가 없고, 결과의 isLeap 로 윤달 여부를 알려드립니다. [2026-08-22 반영] |
요청 예시
- 음양력 변환은 year / month / day (접두사 없음) 를 씁니다.
- 토픽 요청(/v2/sazu/<topic>)의 birthYear / birthMonth / birthDay 와 다릅니다.
curl -X POST https://api.sazu.app/v2/calendar/convert \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"year": 1990,
"month": 3,
"day": 15,
"direction": "toLunar"
}'# 음력→양력에서 윤달이면 isLeapMonth 를 함께 보냅니다.
# 1998년 음력 5월은 평5월(→ 6/9)과 윤5월(→ 7/8) 두 가지입니다.
curl -X POST https://api.sazu.app/v2/calendar/convert \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"year": 1998,
"month": 5,
"day": 15,
"direction": "toSolar",
"isLeapMonth": true
}'/v2/me현재 키의 요금 등급 · 분당/월간 한도 · 이번 주기 사용량 · 초기화 시각 · 일시 중지 상태 · 선결제 잔여 호출 수를 돌려줍니다.
응답: data: { tier, keyPrefix, rateLimitPerMinute, monthlyQuota, used, remaining, quotaCycleStart, quotaResetAt, banned, bannedUntil, prepaid, plan, cycle, included, overage, rateLimit }.
하위 구조: plan: { tier, kind }, cycle: { startAt, resetAt }, included: { quota, used, remaining }, overage: { policy, perCallKrw, usedThisCycle }, rateLimit: { perMinute }.
prepaid 는 선결제 대상 플랜에서 { callsRemaining, overageCallsRemaining, overagePerCallKrw } 이며 그 밖의 플랜에서는 null 입니다. callsRemaining 은 충전 시점 플랜 단가로 적립된 남은 호출 수이며, 플랜을 바꿔도 줄거나 늘지 않습니다. overagePerCallKrw 는 지금 플랜의 초과 호출 단가(안내용)입니다.
이 조회는 월 포함량과 선결제 호출을 소모하지 않으며, 포함량을 모두 쓴 뒤에도 호출할 수 있습니다(분당 한도는 적용).
요청 예시
curl https://api.sazu.app/v2/me \
-H "x-api-key: YOUR_API_KEY"/v2/me/errors본인 키로 발생한 최근 4xx/5xx 오류 이력 (15일 retention). 이 조회는 월 포함량과 선결제 호출을 소모하지 않습니다(분당 한도는 적용).
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| limit | number | 선택 | 반환 개수 (1~100, 기본 20) |
| offset | number | 선택 | 페이징 (기본 0) |
| status | "all" | "4xx" | "5xx" | "400" | "500" | 선택 | status 필터 (기본 all) |
| endpoint | string | 선택 | 엔드포인트 정확 일치 필터 (예: /v2/sazu/yearly) |
| since | ISO 8601 string | 선택 | 조회 시작 시각, 기본 24시간 전, 최대 15일 (DB retention) |
v1 에서 v2 로 옮기기
v1 으로 연동해 두신 서비스를 v2 로 옮기실 때 확인하실 내용입니다.
경로의 v1 을 v2 로만 바꾸면 되는 엔드포인트
요청과 응답이 같습니다. /v2/sazu/modules 는 모듈마다 그 모듈이 담기는 토픽 목록(topics)이 더해지고, v2 토픽으로 받으실 수 있는 모듈만 담깁니다.
| v1 | v2 |
|---|---|
| GET /v1/sazu/modules | GET /v2/sazu/modules |
| GET /v1/me | GET /v2/me |
| GET /v1/me/errors | GET /v2/me/errors |
| POST /v1/calendar/convert | POST /v2/calendar/convert |
/v1/sazu/calculate 는 목적별 토픽으로
v2 에는 calculate 가 없습니다. 만들려는 화면에 맞는 토픽(POST /v2/sazu/yearly 등) 하나를 호출하시면, 그 목적에 필요한 모듈이 해석 순서대로 담겨 옵니다. 출생 입력 필드는 같고 modules 만 받지 않습니다. 지금 쓰시는 모듈 조합에 대응하는 토픽은 시나리오 가이드 표에서, 토픽별 요청·응답은 토픽 카탈로그에서 확인하실 수 있습니다.
v2 토픽에 이름 그대로 담기지 않는 모듈
아래 모듈은 v2 토픽에 이름 그대로 담기지 않습니다. 같은 판정이 다른 모듈에 이미 담겨 있어 중복을 정리한 것과, 해석의 정확성을 위해 토픽 응답에서 뺀 것이 있습니다. 모듈마다 v2 에서 받으실 곳을 함께 적었습니다. v1 은 지원 종료일까지 이 모듈들을 지금처럼 응답합니다.
summary분석 요약다른 모듈에 포함summary는 여러 모듈의 결과를 짧게 모은 요약본입니다. v2 에서는 요약에 쓰이던 판정을 원래 모듈에서 더 자세히 받습니다 — 오행 균형·조화·충돌의 점수와 등급은evaluation의scorecard, 일간은fourPillars, 길신·흉살은sinsal, 현재·다음 대운은decadeFortune에 담겨 옵니다. 요약본과 점수의 방향이나 필드 이름이 다른 항목이 있으니 응답 활용 가이드에서 확인해 주십시오.relationships합형충파해다른 모듈에 포함relationships의 원국 합·형·충·파·해(original)는 v2 에서wongukInteraction이 담당합니다. 같은 글자 사이의 관계와 뜻풀이가 기둥 위치·인접 여부와 함께 담겨 옵니다. 허자를 넣어 다시 계산한 결과(withGhost)는 아래 허자 분석과 같은 이유로 토픽에 담지 않습니다.ghostElements허자 분석토픽에 담지 않음- 허자는 원국 8글자에 없는 글자를 합·충 관계로 끌어와 보는 보조 해석입니다. 운세 문장의 재료로 쓰면 없는 글자가 실제로 있는 것처럼 서술되기 쉬워, v2 토픽은 원국에 실제로 있는 글자 사이의 관계만 담습니다. 원국 글자 사이의 합·충은
wongukInteraction에서 받으실 수 있습니다.
Free 키로 시험할 때
v2 의 유료 토픽은 Free 키로 호출하면 키 발급일과 관계없이 샘플 입력에만 응답합니다. 샘플 입력은 GET /v2/sazu/samples 로 받으실 수 있습니다 — Free 키로 시험하기
엔드포인트
/v1/sazu/calculate사주 분석 (핵심)
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| birthYear | number | 필수 | 출생년도 (1900~2100). 정수 문자열("1990") 도 허용. |
| birthMonth | number | 필수 | 출생월 (1~12). 정수 문자열("3") 도 허용. JavaScript Date.getMonth() 의 0~11 그대로 전송하면 거부됩니다. |
| birthDay | number | 필수 | 출생일 (1~31). 정수 문자열도 허용. |
| birthHour | number | null | 선택 | 출생시 (0~23), 모르면 null. 정수 문자열도 허용. |
| birthMinute | number | 선택 | 출생분 (0~59), 기본값 0. 정수 문자열도 허용. |
| isFemale | boolean | 선택 | 여성 여부. 누락 시 기본값 false(남성)로 처리되며 응답 헤더 X-Input-Coerced 와 meta.warnings 로 통지합니다. 성별은 사주 결과(대운 진행 방향·해석)에 큰 영향을 주므로 명시 권장. |
| isLunar | boolean | 선택 | 음력 여부, 기본값 false. 음력으로 보내실 때는 윤달 여부(isLeapMonth)를 함께 확인하세요 — 아래 항목 참조. |
| isLeapMonth | boolean | 선택 | 음력 입력이 윤달인지 여부, 기본값 false. isLunar: true 일 때만 사용합니다. 윤달이 드는 해에는 같은 달이 두 번 오므로 연·월·일만으로는 날짜가 하나로 정해지지 않습니다. 예를 들어 1998년에는 5월이 두 번(평5월·윤5월) 있어 음력 1998-05-15 는 양력 6월 9일과 7월 8일 두 가지가 되고, 29일 차이라 월주·일주·시주가 모두 달라집니다. 윤달 출생이면 true 를 보내주세요. [2026-08-22 반영] |
| birthCity | string | 선택 | 출생 도시, 기본값 "서울" |
| locale | "ko" | "han" | 선택 | 한글 또는 한자, 기본값 "ko" |
| modules | string[] | 선택 | 포함할 모듈 ID 목록. 생략 시 플랜별 기본 모듈 |
| decadeCount | number | 선택 | 대운 개수 (11~20, 기본 13) |
| trueSolarTime | boolean | 선택 | 진태양시(경도차 + 균시차) 적용 여부, 기본 false. false = 한국 관습(자시 23:30, 경도차만). true = 공인 방식 진태양시(자시 23:00, 균시차 포함). [2026-07-01 반영] 자세한 차이는 §birthCity 참조. |
| detail | "minimal" | "standard" | "full" | 선택 | 응답 상세 수준. minimal(값만), standard(핵심해석, 기본), full(전체) |
요청 예시
- 필수 필드는 birthYear / birthMonth / birthDay (camelCase, "birth" 접두사) 입니다.
- 주의: year / month / day (접두사 없음) 는 음양력 변환(/v1/calendar/convert) 전용입니다.
- Free(샌드박스) 키는 문서의 샘플 프로필 입력과 일치할 때만 응답합니다 — 아래 "Free 샌드박스" 참고.
import { SazuClient } from '@sazuapp/client'
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
const result = await sazu.calculate({
"birthYear": 1990,
"birthMonth": 3,
"birthDay": 15,
"birthHour": 14,
"birthMinute": 30,
"isFemale": false,
"isLunar": false
})/v1/sazu/modules사용 가능한 모듈 목록. 이 조회는 월 포함량과 선결제 호출을 소모하지 않습니다(분당 한도는 적용).
/v1/me현재 키의 tier · 분당/월간 한도 · 사용량 · 재설정 시각 · ban 상태 · 선결제 잔여 호출 수. 응답: data: { tier, rateLimitPerMinute, monthlyQuota, used, remaining, quotaCycleStart, quotaResetAt, banned, bannedUntil, prepaid }. prepaid 는 유료 플랜에서 { overagePerCallKrw, overageCallsRemaining } 이며, 초과 과금 대상이 아닌 플랜에서는 null 입니다. overageCallsRemaining 은 충전 시점 플랜 단가로 적립된 남은 호출 수입니다. 이 조회는 월 포함량과 선결제 호출을 소모하지 않습니다(분당 한도는 적용).
/v1/me/errors본인 키로 발생한 최근 4xx/5xx 오류 이력 (15일 retention). 이 조회는 월 포함량과 선결제 호출을 소모하지 않습니다(분당 한도는 적용).
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| limit | number | 선택 | 반환 개수 (1~100, 기본 20) |
| offset | number | 선택 | 페이징 (기본 0) |
| status | "all" | "4xx" | "5xx" | "400" | "500" | 선택 | status 필터 (기본 all) |
| endpoint | string | 선택 | 엔드포인트 정확 일치 필터 (예: /v1/sazu/calculate) |
| since | ISO 8601 string | 선택 | 조회 시작 시각, 기본 24시간 전, 최대 15일 (DB retention) |
/v1/calendar/convert음양력 변환
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| year | number | 필수 | 년도. (사주 분석 /v1/sazu/calculate 의 birthYear 와 다른 필드명이니 주의) |
| month | number | 필수 | 월 |
| day | number | 필수 | 일 |
| direction | "toSolar" | "toLunar" | 필수 | 변환 방향. toSolar = 음력→양력, toLunar = 양력→음력 |
| isLeapMonth | boolean | 선택 | 윤달 여부, 기본값 false. direction: "toSolar"(음력→양력) 일 때만 사용합니다. 윤달이 드는 해에는 같은 달이 두 번 오므로, 음력 1998-05-15 는 isLeapMonth 값에 따라 양력 6월 9일(평5월) 또는 7월 8일(윤5월)이 됩니다. 반대 방향(toLunar)은 입력 날짜가 하나로 정해지므로 보내실 필요가 없고, 결과의 isLeap 로 윤달 여부를 알려드립니다. [2026-08-22 반영] |
요청 예시
- 음양력 변환은 year / month / day (접두사 없음) 를 씁니다.
- 사주 분석(/v1/sazu/calculate)의 birthYear / birthMonth / birthDay 와 다릅니다.
import { SazuClient } from '@sazuapp/client'
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY! })
const result = await sazu.calendar.convert({
"year": 1990,
"month": 3,
"day": 15,
"direction": "toLunar"
})모듈 (17개)
modules 파라미터로 원하는 모듈만 선택할 수 있습니다. 생략 시 플랜별 기본 모듈이 포함됩니다.
아래 FREE · PRO 표시는 실제 생년월일 계산 기준입니다. Free 샌드박스는 어느 쪽이든 17개 전체를 고정 샘플로 반환합니다 — 아래 Free 샌드박스 참고.
fourPillarsFREE사주 원국
천간·지지·십성·12운성·12신살·납음·지장간 포함
응답 예시 보기
샘플 프로필 「신강 · 남 · 합충 풍부」로 실제 호출한 응답입니다.
decadeFortuneFREE대운
10년 단위 대운 흐름, 순행/역행, 시작 나이
응답 예시 보기
샘플 프로필 「신약 · 여 · 대운 역행」로 실제 호출한 응답입니다.
elementsFREE오행 분포
목화토금수 분포, 천간/지지 별도 집계
응답 예시 보기
샘플 프로필 「출생시간 미상 (시주 없음)」로 실제 호출한 응답입니다.
summaryFREE분석 요약
오행 균형, 조화/갈등, 대운을 점수·등급으로 요약
응답 예시 보기
샘플 프로필 「신살 풍부 · 여」로 실제 호출한 응답입니다.
sinStrengthFREE신강/신약
득령·득지·득세 3원칙 + 점수(0-100) + 상세 분석
응답 예시 보기
샘플 프로필 「신강 · 남 · 합충 풍부」로 실제 호출한 응답입니다.
sinsalPRO신살
귀인 21종, 살 17종, 12신살 — 기둥별 상세 + 해석
💡 천을귀인·양인살·도화살 같은 운명적 표식이 없으면 사주의 개성·특기 진단 불가
응답 예시 보기
샘플 프로필 「신살 풍부 · 여」로 실제 호출한 응답입니다.
relationshipsPRO합형충파해
원국(허자 미적용) + 허자 포함 이중 분석. 삼합/반합 자동 분류
💡 글자 간 작용 없이는 인간관계·시기 판별 모두 표면 수준에 머무름
응답 예시 보기
샘플 프로필 「신강 · 남 · 합충 풍부」로 실제 호출한 응답입니다.
ghostElementsPRO허자 분석
삼합공협·도충 허자의 출투, 진허/가허, 순수성, 강도
💡 보이지 않는 오행을 끌어오는 능력 — 합·충 분석의 깊이를 결정
응답 예시 보기
샘플 프로필 「신강 · 남 · 합충 풍부」로 실제 호출한 응답입니다.
gyeokgukPRO격국 분석
정격 8격 + 외격(종격) + 건록/양인격, 신강/신약 점수
💡 사주의 골격(격) 판별이 없으면 직업·재능·인간관계 핵심을 추출 불가
응답 예시 보기
샘플 프로필 「신약 · 여 · 대운 역행」로 실제 호출한 응답입니다.
yongsinPRO용신 분석
억부용신 + 조후용신(궁통보감) + 5신(용희기구한) 파생
💡 용신을 모르면 운의 흐름·개운 방향·길흉 판별이 모두 불가능
응답 예시 보기
샘플 프로필 「신강 · 남 · 합충 풍부」로 실제 호출한 응답입니다.
weolunPRO월률분야
절기 기반 지장간 사령(司令) 추출 — 격국·용신 판별의 결정적 기초 데이터. 단순 월 운세가 아닌 명리학 정통 분석
💡 월령의 사령 천간 없이는 격국 결정 자체가 성립하지 않음
응답 예시 보기
샘플 프로필 「중화 · 관계 희소」로 실제 호출한 응답입니다.
seunPRO세운
과거/현재/미래 년운 + 합형충파해 관계 + 12운성
💡 12운성 12단계로 인생 에너지 곡선 정량화 — "올해 어떨까" 질문의 정확한 답
응답 예시 보기
샘플 프로필 「신약 · 여 · 대운 역행」로 실제 호출한 응답입니다.
wongukInteractionPRO원국 상호작용
4기둥 간 합형충파해 + 인접/격각 구분
💡 원국 8글자 내 합·형·충·파·해 자동 감지 — 사주 풀이 정밀도를 결정
응답 예시 보기
샘플 프로필 「신강 · 남 · 합충 풍부」로 실제 호출한 응답입니다.
dailyInteractionPRO일진 상호작용
특정 날짜 일진이 원국에 미치는 작용 — 일진 신살, 4기둥과의 합형충파해, 오행 변화
💡 오늘의 운세를 원국 기반으로 산출 — 날짜별 재호출 없이 하루 1회로 개인화
응답 예시 보기
샘플 프로필 「출생시간 미상 (시주 없음)」로 실제 호출한 응답입니다.
wealthPRO재물운 분석
재성 분포(암장 포함)·재고(財庫)귀인·감당력(신강약+용신 대비) — 대운>세운>월운>일운 계층별 재물 기운 판정
💡 재물이 "언제·어떤 구조로" 들어오는지 — 금전운 풀이의 축
응답 예시 보기
샘플 프로필 「신약 · 여 · 대운 역행」로 실제 호출한 응답입니다.
healthBalancePRO건강 균형 분석
신강신약과 오행 과다·극·충을 바탕으로 한 건강 변화 신호 + 운 작용 진단 — 의료 조언 아님
💡 전통 명리 관점에서 유의할 기운·장부 계통을 짚는 건강운 풀이의 축
응답 예시 보기
샘플 프로필 「신강 · 남 · 합충 풍부」로 실제 호출한 응답입니다.
evaluationPRO종합 사주 평가
스코어카드·성격·인생흐름·년운·용신가이드 — 전체 모듈 교차 종합
💡 AI 가 작성하는 풀이 대신, 명리학 표준 진단 결과 그 자체
응답 예시 보기
샘플 프로필 「신살 풍부 · 여」로 실제 호출한 응답입니다.
Free 샌드박스
2026년 8월 25일 이후 발급된 Free 키는 샌드박스로 동작합니다. 그 전에 발급된 Free 키는 v1 에서 무료 모듈 범위를 실제로 계산해 응답합니다. v2 의 유료 토픽은 이와 달리 키 발급일과 관계없이 샘플 입력에만 응답합니다. 샌드박스로 동작하는 키는 아래 샘플 프로필 5종의 입력값과 정확히 일치할 때만 응답하며, 그 응답은 유료 플랜과 동일한 17개 모듈 구조를 고정 데이터로 담습니다. 응답시간도 유료 플랜 실측만큼 지연되므로 로딩 UX 까지 그대로 검증하실 수 있습니다.
| sampleProfile | 특성 | 입력값 | 확인 용도 |
|---|---|---|---|
| strong-male | 신강 · 남 · 합충 풍부 | 1998-05-19 10:00 · 남 · 서울 | 관계 목록이 길 때의 레이아웃·줄바꿈 |
| weak-female | 신약 · 여 · 대운 역행 | 1970-05-05 10:00 · 여 · 서울 | 대운이 역순일 때의 정렬·나이 표기 |
| unknown-hour | 출생시간 미상 (시주 없음) | 1985-08-12 · 시각 null · 남 · 서울 | 기둥 하나가 비는 화면·null 처리 |
| balanced | 중화 · 관계 희소 | 1972-05-19 10:00 · 남 · 서울 | 합충이 거의 없을 때의 빈 상태 |
| rich-sinsal | 신살 풍부 · 여 | 1993-11-19 10:00 · 여 · 서울 | 뱃지가 많을 때의 넘침·접힘 |
일치하지 않는 생년월일은 400 SAMPLE_PROFILE_REQUIRED 로 응답하며, error.details.sampleProfiles 에 위 목록이 그대로 포함됩니다. 성공 응답에는 meta.sample · meta.sampleProfile 이 붙어 샘플 여부를 코드에서 구분하실 수 있습니다. v2 에서 시험하시는 법은 Free 키로 시험하기에 있습니다.
합·형 판정과 나이·월 표기 규칙은 두 버전에 같게 적용되며, 응답 활용 가이드의 판정 규칙에 정리했습니다.
시나리오별 사용 가이드
아래 조합은 SAZU 가 자체 운세 상품에 실제로 쓰는 구성입니다. 같은 조합이 v2 에서는 엔드포인트 하나입니다 — v1 으로 직접 조합할 때는 modules 에 아래 목록을 그대로 넣으세요.
| 만들려는 것 | v2 — 1회 호출 | v1 로 직접 조합하면 (modules) |
|---|---|---|
| 만세력 (명식 조회) | POST /v2/sazu/manse | ["fourPillars","elements","sinStrength","sinsal","decadeFortune"] |
| 오늘의 운세 | POST /v2/sazu/today | ["fourPillars","dailyInteraction","sinsal","weolun","seun"] |
| 일일 운세 | POST /v2/sazu/daily | ["fourPillars","dailyInteraction","sinsal","weolun","seun","decadeFortune"] |
| 월 운세 | POST /v2/sazu/monthly | ["fourPillars","weolun","seun","sinStrength","yongsin","sinsal"] |
| 연간 운세 | POST /v2/sazu/yearly | ["fourPillars","seun","weolun","decadeFortune","gyeokguk","yongsin","sinsal","evaluation"] |
| 대운 10년 | POST /v2/sazu/decade | ["fourPillars","decadeFortune","seun","sinStrength","yongsin","sinsal"] |
| 평생 흐름 | POST /v2/sazu/life | ["fourPillars","wongukInteraction","gyeokguk","yongsin","decadeFortune","sinsal","evaluation"] |
| 고민 상담 | POST /v2/sazu/consult | ["fourPillars","weolun","seun","yongsin","gyeokguk","decadeFortune","sinsal","evaluation"] |
| 관계 궁합 | POST /v2/sazu/compatibility | ["fourPillars","wongukInteraction","elements","gyeokguk","yongsin","decadeFortune","sinsal","evaluation"] |
| 연애 운 | POST /v2/sazu/love | ["fourPillars","wongukInteraction","weolun","seun","elements","gyeokguk","yongsin","decadeFortune","sinsal","evaluation"] |
| 금전운 | POST /v2/sazu/money | ["fourPillars","wealth","sinStrength","yongsin","seun","decadeFortune","sinsal"] |
| 건강운 | POST /v2/sazu/health | ["fourPillars","elements","healthBalance","sinStrength","yongsin","seun","sinsal"] |
| 식단 | POST /v2/sazu/food | ["fourPillars","elements","foodBalance","sinStrength","gyeokguk","yongsin","decadeFortune","seun","weolun","dailyInteraction","sinsal","evaluation"] |
v1 직접 조합은 세운 16개년이 모두 담겨 오고 모듈 순서도 계산 순서 그대로입니다 — v2 토픽은 토픽이 쓰는 범위만, 해석 순서대로 담습니다.
핵심: 한 사용자 = 최소 1회 호출
modules와 detail은 응답 크기 최적화용이며, 추가 호출을 유발하지 않습니다. evaluation 모듈만 요청해도 내부적으로 모든 의존 모듈을 계산하여 종합 결과를 생성합니다.
detail — 응답 크기 제어
목적에 맞게 응답 상세 수준을 조절하여 네트워크 비용과 파싱 시간을 절약하세요.
| 레벨 | 포함 | 제거 | 크기 |
|---|---|---|---|
| minimal | 값, 점수, 등급 | 모든 해석 텍스트, 12운성 해석, 십성 해석 | ~19KB |
| standard | 핵심 해석, description | 중복 해석, 세운 합충 3개 제한 | ~35KB |
| full | 전체 (interpretation, modernMeaning 등) | 없음 | ~46KB |
진태양시 / 출생지 보정
birthCity 는 시각 보정에 사용되는 출생 도시 식별자이며, 모든 토픽 엔드포인트가 같은 필드를 받습니다 — 사용자 사주 입력 폼에 출생지 선택과 진태양시 체크박스를 두면 어느 토픽에서든 그대로 쓸 수 있습니다. 한글/영문 모두 인식되며, 미매칭 시 자동으로 서울 (UTC+09:00) 으로 폴백됩니다. 기본은 한국 관습(자시 23:30, 경도차 보정),trueSolarTime: true 로 진태양시(경도차 + 균시차)도 선택할 수 있습니다.
입력 규칙
- 대소문자 무관 · 영문은 소문자로 정규화 (예:
SEOUL,Seoul,seoul동일). - 한글/영문 양쪽 인식 (예:
서울=seoul). - 부분 매칭 fallback — 정확 일치 실패 시 substring 검사 (예:
서울특별시→서울). - 미지원 도시 입력 시 자동
서울 (UTC+09:00)폴백 — 응답meta.warnings에 통지.
진태양시 옵션 — trueSolarTime
2026-07-01 반영시각 보정 방식을 두 가지로 제공합니다. 기본값은 한국 만세력 관습이며, 필요 시 공인 방식의 정밀 진태양시를 선택할 수 있습니다.
@sazuapp/client ≥ 0.3.0, MCP 서버 @sazuapp/mcp-server ≥ 0.2.0 에서 파라미터를 지원합니다. API 직접 호출은 별도 업데이트 없이 trueSolarTime 필드만 추가하면 됩니다.| 값 | 방식 | 자시 기준 | 보정 |
|---|---|---|---|
| false (기본) | 한국 관습 | 23:30 | 도시 경도차 |
| true | 진태양시 (공인) | 23:00 | 경도차 + 균시차 |
- 기본(false) — 자시를 23:30 으로 보는 한국 만세력 관습(동경 127.5° 기준)에 출생 도시 경도차를 반영. 익숙한 결과를 원하는 대부분의 서비스에 적합합니다.
- 진태양시(true) — 동경 135° 표준자오선 기준 경도차에 균시차(날짜별 태양 위치 오차, −14 ~ +16분)까지 더한 실제 진태양시. 자시 경계를 표준 23:00 으로 판정합니다. 천문학적으로 정밀한 결과를 원할 때 사용합니다.
- 같은 생년월일·시각이라도 두 방식의 시주(時柱)가 시(時) 경계 부근에서 달라질 수 있습니다. 응답
timezone.mode·longitude·equationOfTimeMinutes로 적용 내역을 확인할 수 있습니다.
폼 체크박스 예시
<!-- 사주 입력 폼에 진태양시 옵션 체크박스 -->
<label>
<input type="checkbox" name="trueSolarTime" value="true" />
진태양시로 계산 (경도 + 균시차 반영, 정밀)
</label>
<!-- 제출 시 -->
fetch('https://api.sazu.app/v2/sazu/manse', {
method: 'POST',
headers: { 'x-api-key': API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({
birthYear, birthMonth, birthDay, birthHour, birthMinute,
birthCity, // 도시 경도 보정
trueSolarTime: checkbox.checked, // 체크 시 진태양시
}),
})AI 프롬프트 예문
사주 입력 폼에 "진태양시" 체크박스를 추가해줘.
- 체크박스 라벨: "진태양시로 계산 (더 정밀)"
- 체크되면 SAZU API 호출 body 에 trueSolarTime: true 를 넣고, 아니면 false(또는 생략)
- 기본은 체크 해제 (한국 관습 방식)
- 체크박스 옆에 작은 도움말: "체크 시 출생지 경도와 균시차까지 반영한 진태양시로 계산합니다."지원 도시 전체 (71개)클릭하여 펼치기▾
UTC offset 은 표준시 기준 (서머타임 미반영 — 출생 일자별 일광절약은 서버가 자동 처리).
한국
| 한글 | 영문 | UTC offset |
|---|---|---|
| 서울 | seoul | UTC+09:00 |
| 인천 | incheon | UTC+09:00 |
| 부산 | busan | UTC+09:00 |
| 대구 | daegu | UTC+09:00 |
| 대전 | daejeon | UTC+09:00 |
| 광주 | gwangju | UTC+09:00 |
일본
| 한글 | 영문 | UTC offset |
|---|---|---|
| 도쿄 | tokyo | UTC+09:00 |
| 오사카 | osaka | UTC+09:00 |
중국
| 한글 | 영문 | UTC offset |
|---|---|---|
| 베이징 | beijing· 北京 | UTC+08:00 |
| 상하이 | shanghai | UTC+08:00 |
동남아
| 한글 | 영문 | UTC offset |
|---|---|---|
| 홍콩 | hong kong· hongkong | UTC+08:00 |
| 싱가포르 | singapore | UTC+08:00 |
| 타이베이 | taipei | UTC+08:00 |
| 방콕 | bangkok | UTC+07:00 |
| 자카르타 | jakarta | UTC+07:00 |
| 하노이 | hanoi | UTC+07:00 |
남아시아
| 한글 | 영문 | UTC offset |
|---|---|---|
| 뭄바이 | mumbai | UTC+05:30 |
| 콜카타 | kolkata | UTC+05:30 |
| 뉴델리 | new delhi | UTC+05:30 |
중동
| 한글 | 영문 | UTC offset |
|---|---|---|
| 두바이 | dubai | UTC+04:00 |
| 리야드 | riyadh | UTC+03:00 |
유럽
| 한글 | 영문 | UTC offset |
|---|---|---|
| 모스크바 | moscow | UTC+03:00 |
| 이스탄불 | istanbul | UTC+03:00 |
| 헬싱키 | helsinki | UTC+02:00 |
| 아테네 | athens | UTC+02:00 |
| 파리 | paris | UTC+01:00 |
| 베를린 | berlin | UTC+01:00 |
| 로마 | rome | UTC+01:00 |
| 마드리드 | madrid | UTC+01:00 |
| 암스테르담 | amsterdam | UTC+01:00 |
| 브뤼셀 | brussels | UTC+01:00 |
| 비엔나 | vienna | UTC+01:00 |
| 취리히 | zurich | UTC+01:00 |
| 프라하 | prague | UTC+01:00 |
| 바르샤바 | warsaw | UTC+01:00 |
| 스톡홀름 | stockholm | UTC+01:00 |
| 오슬로 | oslo | UTC+01:00 |
| 코펜하겐 | copenhagen | UTC+01:00 |
| 런던 | london | UTC+00:00 |
| 리스본 | lisbon | UTC+00:00 |
| 더블린 | dublin | UTC+00:00 |
| 레이캬비크 | reykjavik | UTC+00:00 |
북미
| 한글 | 영문 | UTC offset |
|---|---|---|
| 뉴욕 | new york | UTC-05:00 |
| 토론토 | toronto | UTC-05:00 |
| 워싱턴 | washington | UTC-05:00 |
| 마이애미 | miami | UTC-05:00 |
| 보스턴 | boston | UTC-05:00 |
| 애틀랜타 | atlanta | UTC-05:00 |
| 시카고 | chicago | UTC-06:00 |
| 휴스턴 | houston | UTC-06:00 |
| 달라스 | dallas | UTC-06:00 |
| 덴버 | denver | UTC-07:00 |
| 피닉스 | phoenix | UTC-07:00 |
| 로스앤젤레스 | los angeles | UTC-08:00 |
| 샌프란시스코 | san francisco | UTC-08:00 |
| 시애틀 | seattle | UTC-08:00 |
| 밴쿠버 | vancouver | UTC-08:00 |
| 앵커리지 | anchorage | UTC-09:00 |
| 호놀룰루 | honolulu | UTC-10:00 |
남미
| 한글 | 영문 | UTC offset |
|---|---|---|
| 리우데자네이루 | rio de janeiro | UTC-03:00 |
| 상파울루 | sao paulo | UTC-03:00 |
| 부에노스아이레스 | buenos aires | UTC-03:00 |
| 산티아고 | santiago | UTC-04:00 |
| 리마 | lima | UTC-05:00 |
| 보고타 | bogota | UTC-05:00 |
대서양
| 한글 | 영문 | UTC offset |
|---|---|---|
| 아조레스 | azores | UTC-01:00 |
오세아니아
| 한글 | 영문 | UTC offset |
|---|---|---|
| 오클랜드 | auckland | UTC+12:00 |
| 시드니 | sydney | UTC+10:00 |
| 멜버른 | melbourne | UTC+10:00 |
| 브리즈번 | brisbane | UTC+10:00 |
| 퍼스 | perth | UTC+08:00 |
폼 드롭다운용 도시 목록 (JSON)
출생도시 선택 드롭다운을 바로 만들 수 있는 간결 목록입니다. 지역별로 묶여 있고, 도시마다 ko(한글)·en(영문)·aliases 를 제공합니다. 아래 블록을 복사하거나 파일로 내려받아 쓰세요.
전체 도시 JSON 보기 (71개 · 클릭하여 펼치기)▾
{
"description": "SAZU API 출생도시(birthCity) 지원 목록 — 운세 서비스 폼의 출생도시 드롭다운 구성용. birthCity 값으로 한글(ko) 또는 영문(en) 어느 것을 보내도 됩니다. 목록에 없는 도시는 서울(한국 표준시)로 처리됩니다.",
"reference": "https://www.sazu.app/manse-api/docs#birth-city",
"count": 71,
"regions": [
{
"region": "한국",
"cities": [
{
"ko": "서울",
"en": "seoul",
"aliases": [
"서울",
"seoul"
]
},
{
"ko": "인천",
"en": "incheon",
"aliases": [
"인천",
"incheon"
]
},
{
"ko": "부산",
"en": "busan",
"aliases": [
"부산",
"busan"
]
},
{
"ko": "대구",
"en": "daegu",
"aliases": [
"대구",
"daegu"
]
},
{
"ko": "대전",
"en": "daejeon",
"aliases": [
"대전",
"daejeon"
]
},
{
"ko": "광주",
"en": "gwangju",
"aliases": [
"광주",
"gwangju"
]
}
]
},
{
"region": "일본",
"cities": [
{
"ko": "도쿄",
"en": "tokyo",
"aliases": [
"도쿄",
"tokyo"
]
},
{
"ko": "오사카",
"en": "osaka",
"aliases": [
"오사카",
"osaka"
]
}
]
},
{
"region": "중국",
"cities": [
{
"ko": "베이징",
"en": "beijing",
"aliases": [
"베이징",
"beijing",
"北京"
]
},
{
"ko": "상하이",
"en": "shanghai",
"aliases": [
"상하이",
"shanghai"
]
}
]
},
{
"region": "동남아",
"cities": [
{
"ko": "홍콩",
"en": "hong kong",
"aliases": [
"홍콩",
"hong kong",
"hongkong"
]
},
{
"ko": "싱가포르",
"en": "singapore",
"aliases": [
"싱가포르",
"singapore"
]
},
{
"ko": "타이베이",
"en": "taipei",
"aliases": [
"타이베이",
"taipei"
]
},
{
"ko": "방콕",
"en": "bangkok",
"aliases": [
"방콕",
"bangkok"
]
},
{
"ko": "자카르타",
"en": "jakarta",
"aliases": [
"자카르타",
"jakarta"
]
},
{
"ko": "하노이",
"en": "hanoi",
"aliases": [
"하노이",
"hanoi"
]
}
]
},
{
"region": "남아시아",
"cities": [
{
"ko": "뭄바이",
"en": "mumbai",
"aliases": [
"뭄바이",
"mumbai"
]
},
{
"ko": "콜카타",
"en": "kolkata",
"aliases": [
"콜카타",
"kolkata"
]
},
{
"ko": "뉴델리",
"en": "new delhi",
"aliases": [
"뉴델리",
"new delhi"
]
}
]
},
{
"region": "중동",
"cities": [
{
"ko": "두바이",
"en": "dubai",
"aliases": [
"두바이",
"dubai"
]
},
{
"ko": "리야드",
"en": "riyadh",
"aliases": [
"리야드",
"riyadh"
]
}
]
},
{
"region": "유럽",
"cities": [
{
"ko": "모스크바",
"en": "moscow",
"aliases": [
"모스크바",
"moscow"
]
},
{
"ko": "이스탄불",
"en": "istanbul",
"aliases": [
"이스탄불",
"istanbul"
]
},
{
"ko": "헬싱키",
"en": "helsinki",
"aliases": [
"헬싱키",
"helsinki"
]
},
{
"ko": "아테네",
"en": "athens",
"aliases": [
"아테네",
"athens"
]
},
{
"ko": "파리",
"en": "paris",
"aliases": [
"파리",
"paris"
]
},
{
"ko": "베를린",
"en": "berlin",
"aliases": [
"베를린",
"berlin"
]
},
{
"ko": "로마",
"en": "rome",
"aliases": [
"로마",
"rome"
]
},
{
"ko": "마드리드",
"en": "madrid",
"aliases": [
"마드리드",
"madrid"
]
},
{
"ko": "암스테르담",
"en": "amsterdam",
"aliases": [
"암스테르담",
"amsterdam"
]
},
{
"ko": "브뤼셀",
"en": "brussels",
"aliases": [
"브뤼셀",
"brussels"
]
},
{
"ko": "비엔나",
"en": "vienna",
"aliases": [
"비엔나",
"vienna"
]
},
{
"ko": "취리히",
"en": "zurich",
"aliases": [
"취리히",
"zurich"
]
},
{
"ko": "프라하",
"en": "prague",
"aliases": [
"프라하",
"prague"
]
},
{
"ko": "바르샤바",
"en": "warsaw",
"aliases": [
"바르샤바",
"warsaw"
]
},
{
"ko": "스톡홀름",
"en": "stockholm",
"aliases": [
"스톡홀름",
"stockholm"
]
},
{
"ko": "오슬로",
"en": "oslo",
"aliases": [
"오슬로",
"oslo"
]
},
{
"ko": "코펜하겐",
"en": "copenhagen",
"aliases": [
"코펜하겐",
"copenhagen"
]
},
{
"ko": "런던",
"en": "london",
"aliases": [
"런던",
"london"
]
},
{
"ko": "리스본",
"en": "lisbon",
"aliases": [
"리스본",
"lisbon"
]
},
{
"ko": "더블린",
"en": "dublin",
"aliases": [
"더블린",
"dublin"
]
},
{
"ko": "레이캬비크",
"en": "reykjavik",
"aliases": [
"레이캬비크",
"reykjavik"
]
}
]
},
{
"region": "북미",
"cities": [
{
"ko": "뉴욕",
"en": "new york",
"aliases": [
"뉴욕",
"new york"
]
},
{
"ko": "토론토",
"en": "toronto",
"aliases": [
"토론토",
"toronto"
]
},
{
"ko": "워싱턴",
"en": "washington",
"aliases": [
"워싱턴",
"washington"
]
},
{
"ko": "마이애미",
"en": "miami",
"aliases": [
"마이애미",
"miami"
]
},
{
"ko": "보스턴",
"en": "boston",
"aliases": [
"보스턴",
"boston"
]
},
{
"ko": "애틀랜타",
"en": "atlanta",
"aliases": [
"애틀랜타",
"atlanta"
]
},
{
"ko": "시카고",
"en": "chicago",
"aliases": [
"시카고",
"chicago"
]
},
{
"ko": "휴스턴",
"en": "houston",
"aliases": [
"휴스턴",
"houston"
]
},
{
"ko": "달라스",
"en": "dallas",
"aliases": [
"달라스",
"dallas"
]
},
{
"ko": "덴버",
"en": "denver",
"aliases": [
"덴버",
"denver"
]
},
{
"ko": "피닉스",
"en": "phoenix",
"aliases": [
"피닉스",
"phoenix"
]
},
{
"ko": "로스앤젤레스",
"en": "los angeles",
"aliases": [
"로스앤젤레스",
"los angeles"
]
},
{
"ko": "샌프란시스코",
"en": "san francisco",
"aliases": [
"샌프란시스코",
"san francisco"
]
},
{
"ko": "시애틀",
"en": "seattle",
"aliases": [
"시애틀",
"seattle"
]
},
{
"ko": "밴쿠버",
"en": "vancouver",
"aliases": [
"밴쿠버",
"vancouver"
]
},
{
"ko": "앵커리지",
"en": "anchorage",
"aliases": [
"앵커리지",
"anchorage"
]
},
{
"ko": "호놀룰루",
"en": "honolulu",
"aliases": [
"호놀룰루",
"honolulu"
]
}
]
},
{
"region": "남미",
"cities": [
{
"ko": "리우데자네이루",
"en": "rio de janeiro",
"aliases": [
"리우데자네이루",
"rio de janeiro"
]
},
{
"ko": "상파울루",
"en": "sao paulo",
"aliases": [
"상파울루",
"sao paulo"
]
},
{
"ko": "부에노스아이레스",
"en": "buenos aires",
"aliases": [
"부에노스아이레스",
"buenos aires"
]
},
{
"ko": "산티아고",
"en": "santiago",
"aliases": [
"산티아고",
"santiago"
]
},
{
"ko": "리마",
"en": "lima",
"aliases": [
"리마",
"lima"
]
},
{
"ko": "보고타",
"en": "bogota",
"aliases": [
"보고타",
"bogota"
]
}
]
},
{
"region": "대서양",
"cities": [
{
"ko": "아조레스",
"en": "azores",
"aliases": [
"아조레스",
"azores"
]
}
]
},
{
"region": "오세아니아",
"cities": [
{
"ko": "오클랜드",
"en": "auckland",
"aliases": [
"오클랜드",
"auckland"
]
},
{
"ko": "시드니",
"en": "sydney",
"aliases": [
"시드니",
"sydney"
]
},
{
"ko": "멜버른",
"en": "melbourne",
"aliases": [
"멜버른",
"melbourne"
]
},
{
"ko": "브리즈번",
"en": "brisbane",
"aliases": [
"브리즈번",
"brisbane"
]
},
{
"ko": "퍼스",
"en": "perth",
"aliases": [
"퍼스",
"perth"
]
}
]
}
]
}드롭다운 구성: region 을<optgroup> 라벨로, 각 도시의ko 를 화면 표시·전송 값으로 쓰면 됩니다. API 호출 시 한글·영문 어느 쪽을 보내도 동일하게 인식됩니다.
바이브 코딩 가이드 — AI 프롬프트 예문
Claude · Cursor 같은 AI 코딩 도구를 쓰신다면, 위 JSON 을 내려받아 아래 프롬프트와 함께 붙여넣으세요. 직접 코드를 작성하지 않아도 폼·드롭다운·API 연동까지 만들 수 있습니다. (각 블록 우상단 복사 버튼)
① 출생도시 드롭다운 만들기
아래 JSON 으로 출생도시 선택 드롭다운(select)을 만들어줘.
- region 을 <optgroup> 라벨로 묶고, 각 도시의 ko 를 화면 표시값이자 전송값(value)으로 사용
- 기본 선택값은 "서울"
- 모바일에서도 보기 좋게 스타일 적용
[여기에 sazu-birth-cities.json 내용을 붙여넣기]② 입력 폼 + API 호출까지
SAZU API 로 사주를 조회하는 입력 폼을 만들어줘.
- 입력: 생년월일, 태어난 시각(모름 옵션 포함), 성별, 양력/음력, 출생도시(드롭다운)
- 출생도시 드롭다운은 첨부한 sazu-birth-cities.json 의 도시 목록으로 구성(region 을 optgroup 으로)
- 제출하면 POST https://api.sazu.app/v2/sazu/manse 로 birthYear, birthMonth, birthDay,
birthHour, isLunar, isFemale, birthCity 를 보내고 응답의 data.modules 를 화면에 표시
- API 키는 환경변수로 분리하고, 호출은 서버 사이드(라우트 핸들러)에서 처리해 키가 노출되지 않게 해줘
- 400 SAMPLE_PROFILE_REQUIRED 는 코드 오류가 아니라 Free 키의 샘플 제한이다.
GET https://api.sazu.app/v2/sazu/samples 의 input 으로 먼저 화면을 검증해줘
[여기에 sazu-birth-cities.json 내용을 붙여넣기]③ 출생도시 자동 기본값(선택)
방금 만든 출생도시 드롭다운에 자동 기본값을 추가해줘.
- 브라우저의 IANA timezone(Intl.DateTimeFormat().resolvedOptions().timeZone)을 읽어
가장 가까운 도시를 기본 선택값으로 설정
- 단, "현재 위치 ≠ 출생지" 이므로 어디까지나 기본값일 뿐 사용자가 바꿀 수 있게 두고,
매칭 실패 시 "서울" 로 폴백팁 — “[여기에 …붙여넣기]” 자리에는 위에서 복사한 도시 JSON 을 그대로 넣으시면 됩니다. API 키는 반드시 환경변수로 분리하고 서버 사이드에서 호출하도록 요청하세요(키 노출 방지).
birthCity 자동 추론 — 폼 기본값 가이드
사용자가 매번 도시명을 타이핑하지 않도록, 브라우저의 IANA timezone (Asia/Seoul 등) 을 birthCity 로 변환해 폼 기본값으로 채워주세요.
서울 인데 자동 추론은 미국 timezone 으로 잡힐 수 있습니다.// 브라우저 → IANA timezone → birthCity 자동 추론
// 사용자에게 confirm 후 사용. 출생지(historical) 와 현재 위치(present) 가
// 다를 수 있으므로 자동 추론은 "현재 위치 기본값" 으로만 사용 권장.
const TZ_TO_CITY: Record<string, string> = {
'Asia/Seoul': '서울',
'Asia/Tokyo': '도쿄',
'Asia/Shanghai': '상하이',
'Asia/Hong_Kong': '홍콩',
'Asia/Singapore': '싱가포르',
'Asia/Taipei': '타이베이',
'Asia/Bangkok': '방콕',
'Asia/Jakarta': '자카르타',
'Asia/Kolkata': '콜카타',
'Asia/Dubai': '두바이',
'Europe/Moscow': '모스크바',
'Europe/Istanbul': '이스탄불',
'Europe/Paris': '파리',
'Europe/Berlin': '베를린',
'Europe/London': '런던',
'America/New_York': '뉴욕',
'America/Chicago': '시카고',
'America/Denver': '덴버',
'America/Los_Angeles': '로스앤젤레스',
'America/Vancouver': '밴쿠버',
'America/Sao_Paulo': '상파울루',
'Pacific/Auckland': '오클랜드',
'Australia/Sydney': '시드니',
'Pacific/Honolulu': '호놀룰루',
// ... 필요 시 확장
}
export function detectBirthCity(fallback = '서울'): string {
if (typeof Intl === 'undefined') return fallback
try {
const tz = Intl.DateTimeFormat().resolvedOptions().timeZone
return TZ_TO_CITY[tz] ?? fallback
} catch {
return fallback
}
}
// React 폼 — 자동 추론 + 사용자 수정 가능
function BirthForm() {
const [city, setCity] = useState(detectBirthCity())
return (
<input
value={city}
onChange={(e) => setCity(e.target.value)}
placeholder="출생 도시"
/>
)
}# Python 서버 — request 의 Accept-Language 또는 IP geoIP 활용
# (서버에서 사용자 출생지를 추측하는 것은 부정확. 클라이언트 자동 추론이 표준.)
from datetime import datetime, timezone
import requests
# 클라이언트가 보낸 timezone 헤더로부터 매핑
TZ_TO_CITY = {
"Asia/Seoul": "서울",
"Asia/Tokyo": "도쿄",
# ...
}
def to_birth_city(client_tz: str, fallback: str = "서울") -> str:
return TZ_TO_CITY.get(client_tz, fallback)목록에 없는 도시
신규 도시 추가 요청은 contact@sazu.app 으로 도시명·UTC offset·예시 출생 일자와 함께 보내주세요. 평균 1~3 영업일 내 반영됩니다.
Rate Limit
응답 헤더에서 남은 요청 수를 확인할 수 있습니다. 분당·월 잔여량이 매 응답에 함께 실리므로, 남은 호출 수를 알기 위해 별도 조회를 보내실 필요가 없습니다.
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1712678400
X-Monthly-Quota: 10000
X-Monthly-Used: 412
X-Monthly-Remaining: 9588
X-Monthly-Reset: 2026-09-01T00:00:00.000Z| 플랜 | 분당 | 월 포함 | 포함량 초과 |
|---|---|---|---|
| Free | 10 | 500 | 제공하지 않습니다 |
| Starter | 30 | 500 | 건당 150원 (충전 시 이 단가로 호출 수 적립) |
| Medium | 45 | 1,000 | 건당 120원 (충전 시 이 단가로 호출 수 적립) |
| Standard | 60 | 2,000 | 건당 90원 (충전 시 이 단가로 호출 수 적립) |
| Premium | 90 | 3,000 | 건당 80원 (충전 시 이 단가로 호출 수 적립) |
| Business | 120 | 4,000 | 건당 70원 (충전 시 이 단가로 호출 수 적립) |
| Custom | 협의 | 협의 | 계약 조건에 따릅니다 |
월 포함량을 다 쓰면 미리 충전해 둔 선결제 호출에서 1건씩 차감되며, 남은 호출이 없으면 402 QUOTA_EXHAUSTED 로 중단됩니다. 충전하시면 즉시 재개됩니다. 충전액은 충전 시점 플랜의 위 단가로 나눈 호출 수(1건 미만은 올림)로 적립되며, 플랜을 바꿔도 줄지 않습니다. 남은 호출 수는 GET /v2/me 의 prepaid.callsRemaining 에서 확인하실 수 있고, 소진이 가까워지면 안내 메일을 보내 드립니다. 키·한도 조회(/v2/me)와 토픽·모듈·샘플 목록 조회는 월 포함량과 선결제 호출을 소모하지 않습니다.
에러 코드
모든 에러 응답은 동일한 구조로 반환됩니다.
{
"success": false,
"error": {
"code": "KEY_REVOKED",
"message": "This API key has been revoked. Generate a new key at https://www.sazu.app/manse-api/dashboard/keys"
}
}| HTTP | code | 설명 및 조치 |
|---|---|---|
| 400 | VALIDATION_ERROR | 요청 바디의 파라미터가 잘못되었습니다. error.details 에서 누락·타입 오류 필드를 확인하세요. |
| 400 | INVALID_DATE | 달력에 실재하지 않는 날짜입니다(예: 평년 2월 30일, 30일이 없는 음력 달). 생년월일 입력을 확인하세요. 존재하지 않는 윤달은 LEAP_MONTH_NOT_FOUND 로 따로 안내합니다. |
| 400 | LEAP_MONTH_NOT_FOUND | isLeapMonth: true 로 요청했으나 그 해 그 달에는 윤달이 없습니다. 평달로 다시 요청하세요. |
| 400 | INVALID_JSON | 요청 바디가 올바른 JSON 이 아닙니다. Content-Type: application/json 과 바디 직렬화를 확인하세요. |
| 400 | SAMPLE_FIXTURE_UNAVAILABLE | 샌드박스 샘플 데이터를 일시적으로 불러오지 못했습니다. 잠시 후 재시도하세요. |
| 400 | SAMPLE_PROFILE_REQUIRED | Free 키로 샘플 입력과 다른 생년월일을 요청했습니다. 코드 오류가 아니라 Free 키의 정상 동작이며, 샘플 프로필 5종의 입력값과 정확히 일치해야 응답합니다. error.details.nearestSample 에 가장 가까운 샘플(어긋난 필드 mismatchedFields, 그대로 보낼 input)이, error.details.samplesEndpoint 에 샘플 목록을 받을 주소가 담깁니다 — 목록은 GET /v2/sazu/samples 로 받으실 수 있습니다. 실제 생년월일 계산은 유료 플랜에서 제공됩니다. |
| 401 | MISSING_API_KEY | 인증 헤더가 누락되었습니다. x-api-key 또는 Authorization: Bearer <키> 헤더 중 하나를 포함해야 합니다. 헤더 이름의 대소문자는 무관하지만 철자는 정확히 일치해야 합니다. |
| 401 | INVALID_API_KEY | API 키가 존재하지 않습니다. 헤더 값(x-api-key 또는 Authorization: Bearer)이 대시보드의 키와 일치하는지 확인하세요. |
| 401 | KEY_REVOKED | 키가 폐기(revoke)되었습니다. 대시보드에서 새 키를 발급한 뒤 코드에 반영하세요. API 키 관리 → |
| 401 | KEY_EXPIRED | 키의 만료일이 지났습니다. 대시보드에서 만료일을 갱신하거나 새 키를 발급하세요. |
| 401 | SUBSCRIPTION_REQUIRED | 키에 연결된 유료 구독이 없거나 만료되었습니다. 대시보드에서 구독 상태를 확인하세요. 결제 · 구독 → |
| 401 | LEGACY_TIER_RETIRED | 종료된 구 플랜의 키입니다. 대시보드에서 현행 플랜으로 전환한 뒤 새 키를 사용하세요. 결제 · 구독 → |
| 403 | BATCH_PAID_ONLY | 배치(다건) 요청은 유료 플랜 전용입니다. Free 키는 단건으로 호출하세요. |
| 403 | ORIGIN_NOT_ALLOWED | 요청 Origin 헤더가 키의 허용 도메인에 등록되지 않았습니다. 유료 플랜 키는 대시보드 → API 키 → "도메인" 버튼에서 호출할 도메인을 등록하세요. 서버 사이드(Origin 헤더 없음) 호출은 등록 여부와 무관하게 통과합니다. |
| 403 | V1_NOT_AVAILABLE | v1 은 레거시로 전환되어 새로 가입하신 계정에서는 호출할 수 없습니다. error.hint.replacement 에 대신 호출할 v2 경로가 담깁니다. v1 에서 v2 로 옮기기 → |
| 410 | V1_RETIRED | v1 지원이 2027년 9월 30일로 종료되었습니다. error.hint.replacement 에 대신 호출할 v2 경로가 담깁니다. v1 에서 v2 로 옮기기 → |
| 429 | RATE_LIMIT_EXCEEDED | 분당 요청 한도를 초과했습니다. X-RateLimit-Reset 헤더의 Unix 타임스탬프 이후 재시도하세요. |
| 402 | QUOTA_EXHAUSTED | 이번 청구 주기 포함량과 선결제 호출을 모두 사용했습니다. 유료 플랜은 결제 관리에서 선결제 호출을 충전하시면 즉시 재개되고, Free 플랜은 다음 주기에 초기화되거나 유료 플랜으로 전환하시면 재개됩니다. error.resetAt 에 다음 초기화 시각이 담깁니다. 결제 · 구독 → |
| 402 | QUOTA_EXCEEDED_BANNED | Free 키가 이번 주기 포함량을 넘겨 키 사용이 일시 중지되었습니다. error.resetAt 시각 이후 자동 재개되며, 그 사이에도 키 상태 조회(/v2/me)는 됩니다. |
| 429 | MONTHLY_QUOTA_EXCEEDED | 월 호출 한도를 초과했습니다. 다음 주기에 자동 초기화됩니다. (선결제 초과 처리를 일시 중단한 비상 상황에서만 응답합니다. 평소에는 402 QUOTA_EXHAUSTED 입니다.) 요금제 → |
| 404 | NOT_FOUND | 존재하지 않는 엔드포인트입니다. 경로와 HTTP 메서드를 확인하세요. |
| 404 | WRONG_ENDPOINT | 흔한 오타를 감지했습니다(예: saju ↔ sazu). error 에 올바른 경로가 함께 담기므로 그대로 바꿔 호출하시면 됩니다. |
| 503 | AUTH_UNAVAILABLE | 인증 서비스에 일시적 장애가 발생했습니다. 잠시 후 재시도하세요. 반복될 경우 문의해 주세요. contact@sazu.app |
| 503 | QUOTA_UNAVAILABLE | 사용량 집계 서비스에 일시적 장애가 발생했습니다. 잠시 후 재시도하세요. |
| 500 | INTERNAL_ERROR | 서버 내부 오류입니다. 동일한 요청이 반복 실패하면 문의해 주세요. contact@sazu.app |
KEY_REVOKED 가 반환된다면?
대시보드에서 '키 재발급'을 누르면 기존 키는 즉시 폐기됩니다. 코드의 환경변수나 설정 파일에서 새 키로 교체하지 않으면 이 오류가 계속 발생합니다.
- 대시보드 → API 키 관리에서 새 키 복사
- 환경변수(
SAZU_API_KEY등) 업데이트 - 서버/앱 재시작 후 요청 재시도
자주 묻는 질문
연동 중 가장 자주 받는 질문입니다. 답변은 이 문서의 다른 절과 같은 원본에서 생성되므로 서로 어긋나지 않습니다.
SAZU 사주 API 는 무엇을 반환하나요?
생년월일·출생시간·성별을 보내면 사주 원국(연·월·일·시주), 대운, 오행 분포, 신강/신약, 신살, 합형충파해, 격국, 용신, 세운 등 17개 분석 모듈을 JSON 으로 돌려줍니다. 목적별 토픽 엔드포인트 POST https://api.sazu.app/v2/sazu/<topic>(yearly·monthly·manse 등 13종)가 그 목적에 필요한 모듈만 해석 순서대로 담아 주므로, 모듈을 직접 선택하실 필요가 없습니다.
API 키는 어떻게 발급하나요?
이메일로 회원가입한 뒤 대시보드(https://www.sazu.app/manse-api/dashboard/keys)에서 발급합니다. 신용카드는 필요하지 않습니다. 전체 키 값은 발급 직후 한 번만 표시되므로 즉시 서버 환경변수나 비밀 저장소에 보관하세요. 발급 시 만료 기간도 함께 정합니다.
무료로 쓸 수 있나요? Free 플랜의 제한은 무엇인가요?
Free 플랜은 월 500회·분당 10회까지 무료이며 신용카드가 필요 없습니다. 유료 토픽을 Free 키로 호출하면 키 발급일과 관계없이 샘플 프로필 5종의 입력에만 응답하고, 응답은 유료 플랜과 같은 구조의 고정 데이터입니다. 샘플 입력은 GET https://api.sazu.app/v2/sazu/samples 로 받으실 수 있습니다. 무료 토픽 /v2/sazu/manse 는 발급일에 따라 다릅니다 — 2026년 8월 25일 이후 발급된 Free 키는 샌드박스로 동작합니다. 그 전에 발급된 Free 키는 무료 모듈 범위를 실제로 계산해 응답합니다. 응답 구조·모듈 17종·응답시간은 유료 플랜과 같으므로 연동과 화면 검증은 그대로 하실 수 있고, 임의의 생년월일을 계산하려면 유료 플랜으로 전환합니다.
400 SAMPLE_PROFILE_REQUIRED 오류는 왜 나오나요?
Free 키로 샘플 프로필에 없는 생년월일을 요청했기 때문입니다. 코드 오류가 아니라 Free 플랜의 정상 동작입니다. 샘플 프로필 5종 중 하나와 입력값이 정확히 일치해야 응답하며(예: 1998-05-19 10:00 · 남 · 서울), 오류의 error.details.nearestSample 에 가장 가까운 샘플과 어긋난 필드(mismatchedFields)가, error.details.samplesEndpoint 에 샘플 목록을 받을 주소가 담깁니다. nearestSample.input 을 그대로 보내시거나 GET /v2/sazu/samples 의 input 을 쓰시면 됩니다. 임의의 생년월일을 계산하려면 유료 플랜이 필요합니다.
403 ORIGIN_NOT_ALLOWED 는 어떻게 해결하나요?
키에 허용 도메인이 등록되어 있는데 요청 Origin 이 그 목록에 없을 때 나옵니다. 대시보드 → API 키 → "도메인" 에서 호출할 주소를 등록하세요(프로토콜과 호스트까지, 경로는 제외). 허용 도메인 등록은 유료 플랜 키 전용이며, 서버 사이드 호출은 Origin 헤더가 없으므로 등록 여부와 무관하게 통과합니다.
브라우저에서 API 를 직접 호출해도 되나요?
권장하지 않습니다. 브라우저에서 호출하면 API 키가 화면 소스에 그대로 노출되어 누구나 복사해 사용량을 소진할 수 있습니다. 자체 백엔드에서 호출하고 결과만 화면으로 내려보내는 구조가 안전합니다. 정적 사이트처럼 백엔드를 둘 수 없다면 유료 플랜 키에 허용 도메인을 등록해 도용 범위를 제한하세요.
음력 생일은 어떻게 보내나요?
isLunar: true 로 보내면 음력으로 해석합니다. 윤달 출생이면 isLeapMonth: true 를 함께 보내야 합니다 — 윤달이 드는 해에는 같은 달이 두 번 오므로 연·월·일만으로는 양력 하루가 정해지지 않고, 평달과 윤달은 약 29일 차이라 월주·일주·시주가 모두 달라집니다.
출생 시간을 모르면 어떻게 하나요?
birthHour 를 null 로 보내면 시주 없이 계산합니다. 응답의 시주 자리는 null 로 내려오므로 화면에서 빈 기둥을 처리하면 됩니다. 시주가 빠지면 신강·신약 판정과 신살 일부가 달라질 수 있습니다.
진태양시(眞太陽時)는 어떻게 적용하나요?
trueSolarTime: true 를 보내면 출생지 경도와 균시차를 반영해 시각을 보정합니다. birthCity 로 도시를 지정하면 그 도시의 경도가 쓰이며, 생략하면 서울 기준입니다. 경계 시각(예: 자시·오시 근처) 출생이면 이 옵션 하나로 시주가 바뀔 수 있습니다.
요청 한도를 넘기면 어떻게 되나요?
분당 한도를 넘기면 429 RATE_LIMIT_EXCEEDED 가 반환됩니다. 응답 헤더 X-RateLimit-Reset 의 Unix 타임스탬프 이후 재시도하면 되고, X-RateLimit-Remaining 으로 남은 횟수를 미리 확인할 수 있습니다. 월 포함량을 모두 쓰면 유료 플랜은 미리 충전한 선결제 호출에서 1건씩 차감되고, 남은 호출이 없으면 402 QUOTA_EXHAUSTED 로 중단됩니다 — 충전하시면 즉시 재개되며 후불 청구는 없습니다. Free 플랜은 다음 주기까지 중단됩니다. 키 상태·오류 이력·토픽·모듈·샘플 목록 조회는 포함량과 선결제 호출을 소모하지 않습니다.
Claude Code·Cursor 같은 AI 에이전트에서 바로 쓸 수 있나요?
MCP 서버 @sazuapp/mcp-server 를 등록하면 AI 에이전트가 자연어로 사주 분석을 호출합니다(유료 전용). 서버 코드에서 쓸 때는 공식 TypeScript SDK @sazuapp/client 를 npm install 해 세 줄이면 연동됩니다(전 플랜 사용 가능).
연간 운세·월 운세를 만들려면 어떤 모듈을 켜야 하나요?
직접 선택하지 않으셔도 됩니다 — 토픽 엔드포인트가 목적별 구성을 정해 줍니다. 연간 운세는 POST /v2/sazu/yearly, 월 운세는 POST /v2/sazu/monthly, 만세력 표는 POST /v2/sazu/manse 하나면 되고, SAZU 가 자체 운세 상품에 쓰는 모듈 구성이 그대로 담겨 옵니다. 토픽마다 담기는 모듈은 GET /v2/sazu/modules 의 topics 로도 확인하실 수 있습니다.
궁합 API 로 여러 명을 한 번에 분석하면 호출 횟수는 어떻게 계산되나요?
POST /v2/sazu/compatibility 와 /v2/sazu/love 는 partners 배열로 상대를 1~3명까지 받고, 인원수와 무관하게 호출 1건으로 계산됩니다. 응답에는 본인과 상대 각각의 계산 모듈에 더해, 두 사람 사이의 합·형·충·파·해 매칭(crossRelations — 문장 요약 prose 포함)과 오행 상보(elementComplement)가 상대별로 담깁니다.
리딩 응답의 세운(seun)에 recentSeuns 배열이 없는데 왜 그런가요?
의도된 동작입니다. 토픽이 실제로 쓰는 범위로 세운을 서버에서 미리 좁혀 보냅니다 — yearly 는 previousSeun·currentSeun·nextSeun 3개년, 나머지 토픽은 currentSeun 하나입니다. 다른 해의 흐름이 필요하시면 yearly 의 year 를 그 해로 바꿔 호출하시면 그 해를 가운데 둔 3개년이 옵니다.
v1 은 계속 쓸 수 있나요?
v1 은 2026년 9월 16일부터 레거시 버전이며 2027년 9월 30일까지 지원합니다. 새로 가입하시는 계정에서는 v1 을 이용하실 수 없습니다. 새 연동은 v2 로 작성해 주십시오. 2027년 10월 1일부터 v1 호출은 모든 계정에서 410 으로 응답합니다. v1 응답에는 성공·오류 모두 폐기 예고 헤더 Deprecation(RFC 9745) · Sunset(RFC 8594, 종료 시각) · Link: <…>; rel="deprecation" 이 실리므로, 연동 코드에서 이 헤더를 감지해 전환 시점을 알릴 수 있습니다. 경로만 v2 로 바꾸면 되는 엔드포인트와 calculate 를 목적별 토픽으로 옮기는 법은 문서의 「v1 (레거시) — v2 로 옮기기」에 정리했습니다.
이 문서의 마크다운 사본은 /manse-api/docs.md 에, 공개 엔드포인트만 담은 OpenAPI 3.1 스펙은 /manse-api/openapi.json 에 있습니다. 도구·에이전트가 문서를 읽거나 클라이언트를 생성할 때 그쪽을 쓰시면 됩니다.