사주 · 만세력 · 운세 API
코드 한 줄에 담아50ms 응답으로5분이면 연동 끝바이브코딩 하세요Claude Code 에서도건당 10원 이하로코드 한 줄에 담아

1. Authentication — API 키 인증

모든 요청은 인증 헤더 1개가 필요합니다. 권장 x-api-key: sazu_free_xxx... (또는 sazu_pro_xxx...), 대안 Authorization: Bearer {SAZU_API_KEY} (REST 관용). 키는 대시보드 에서 발급·관리합니다.

# fetch (Node 18+)
await fetch('https://api.sazu.app/v1/sazu/calculate', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.SAZU_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    birthYear: 1990, birthMonth: 3, birthDay: 15,
    birthHour: 14, isFemale: false,
  }),
})

2. 공통 응답 형식

모든 응답은 { success, data?, error?, meta? } 구조의 JSON. 성공 시 data 에 결과, 실패 시 error.code · error.message 동봉.meta.responseMs 로 응답 시간 측정 가능.

# 성공 응답 (/v1/sazu/calculate)
{
  "success": true,
  "data": {
    "input": { /* 정규화된 입력값 */ },
    "timezone": { /* 진태양시 보정 정보 */ },
    "modules": {
      "fourPillars": { /* 연·월·일·시주 */ },
      "decadeFortune": { /* 대운 */ },
      "elements": { /* 오행 분포 */ }
      /* ... 요청한 모듈별 결과 */
    }
  },
  "meta": { "responseMs": 38.2, "modules": [...], "cached": false }
}

# 실패 응답
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "요청 바디 검증에 실패했습니다.",
    "details": [{ "field": "birthYear", "message": "..." }]
  }
}

3. Endpoints

현재 SAZU API 가 제공하는 5개 엔드포인트. 풀 파라미터·응답 스키마·코드 샘플은 API 문서 참조.

14개 분석 모듈 (사주원국 · 대운 · 오행 · 신강 · 격국 · 용신 · 신살 · 허자 · 합형충파해 · 원국상호작용 · 세운 · 월률분야 · 종합평가 등) 은 /v1/sazu/calculate 의 modules 파라미터로 선택. Free 5개 / Pro 14개 전체.

4. Error Codes

실패 응답은 항상 { success: false, error: { code, message, details? } } 구조. 클라이언트는 error.code 로 분기하세요.

5. Rate Limit

플랜별 월간·분당 한도. 초과 시 429 RATE_LIMIT_EXCEEDED 응답 + X-RateLimit-Reset 헤더에 재시도 가능 시각 (Unix timestamp).