DESTINYAPI · Developer Portal

사주 API

한국 전통 사주명리학(四柱命理學)을 기반으로 사주팔자를 계산하고 대운, 십성, 오행, 신살 등을 분석하는 API입니다.

기본 사주 계산

POST/v1/saju/basic인증 필요

생년월일시를 기반으로 사주팔자(연·월·일·시주)와 대운을 계산합니다.

요청 파라미터

파라미터

이름타입필수설명
namestring필수

이름

예시: 홍길동

birthdatestring필수

생년월일 (YYYY-MM-DD 형식)

예시: 1990-01-15

is_lunarboolean선택

음력 여부

예시: false

기본값: false

is_leap_monthboolean선택

윤달 여부 (음력인 경우만)

예시: false

기본값: false

birth_timestring선택

태어난 시간 (HH:MM 형식, 24시간제)

예시: 14:30

기본값: null (미입력 시 시주를 제외한 간략 계산)

genderstring필수

성별 (M: 남자, F: 여자)

예시: M

요청 예제

curl -X POST https://api.destinyapi.com/v1/saju/basic \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "홍길동",
  "birthdate": "1990-01-15",
  "birth_time": "14:30",
  "gender": "M",
  "is_lunar": false,
  "is_leap_month": false
}'

성공 응답

200 OK - 사주 계산 성공

응답 상태:200
{
  "saju": {
    "year_stem": "己",
    "year_branch": "巳",
    "month_stem": "丁",
    "month_branch": "丑",
    "day_stem": "庚",
    "day_branch": "辰",
    "hour_stem": "癸",
    "hour_branch": "未"
  },
  "daeun": {
    "years": 6,
    "start_date": "1996-08-29T14:30:00",
    "is_forward": true,
    "daeun_list": [
      {
        "age": 6,
        "pillar": "丙子"
      },
      {
        "age": 16,
        "pillar": "乙亥"
      },
      {
        "age": 26,
        "pillar": "甲戌"
      },
      {
        "age": 36,
        "pillar": "癸酉"
      },
      {
        "age": 46,
        "pillar": "壬申"
      },
      {
        "age": 56,
        "pillar": "辛未"
      },
      {
        "age": 66,
        "pillar": "庚午"
      },
      {
        "age": 76,
        "pillar": "己巳"
      },
      {
        "age": 86,
        "pillar": "戊辰"
      },
      {
        "age": 96,
        "pillar": "丁卯"
      }
    ]
  },
  "ten_gods": {
    "Year_Stem": "정인",
    "Year_Branch": "편관",
    "Month_Stem": "정관",
    "Month_Branch": "정인",
    "Day_Stem": "主",
    "Day_Branch": "편인",
    "Hour_Stem": "상관",
    "Hour_Branch": "정인"
  }
}

응답 구조

  • year_stem, year_branch: 연주(年柱)의 천간과 지지
  • month_stem, month_branch: 월주(月柱)의 천간과 지지
  • day_stem, day_branch: 일주(日柱)의 천간과 지지
  • hour_stem, hour_branch: 시주(時柱)의 천간과 지지
  • daeun: 대운(大運) 정보
    • years: 첫 대운까지의 년수
    • start_date: 대운 시작 일시
    • is_forward: 순행/역행 여부 (true: 순행, false: 역행)
    • daeun_list: 대운 목록 (각 대운의 나이와 간지)

종합 사주 분석

POST/v1/saju/analysis인증 필요

기본 사주 + 십성/오행/신살/네임드 해석을 포함한 전체 리포트를 제공합니다.

요청 파라미터

파라미터

이름타입필수설명
namestring필수

이름

예시: 홍길동

birthdatestring필수

생년월일 (YYYY-MM-DD 형식)

예시: 1990-01-15

is_lunarboolean선택

음력 여부

예시: false

기본값: false

is_leap_monthboolean선택

윤달 여부 (음력인 경우만)

예시: false

기본값: false

birth_timestring선택

태어난 시간 (HH:MM 형식, 24시간제)

예시: 14:30

기본값: null (미입력 시 시주를 제외한 간략 계산)

genderstring필수

성별 (M: 남자, F: 여자)

예시: M

요청 파라미터는 기본 사주 계산과 동일합니다.

요청 예제

curl -X POST https://api.destinyapi.com/v1/saju/analysis \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "홍길동",
  "birthdate": "1990-01-15",
  "birth_time": "14:30",
  "gender": "M",
  "is_lunar": false,
  "is_leap_month": false
}'

성공 응답

200 OK - 종합 분석 성공

응답 상태:200
{
  "saju": {
    "year_stem": "己",
    "year_branch": "巳",
    "month_stem": "丁",
    "month_branch": "丑",
    "day_stem": "庚",
    "day_branch": "辰",
    "hour_stem": "癸",
    "hour_branch": "未"
  },
  "daeun": {
    "years": 6,
    "start_date": "1996-08-29T14:30:00",
    "is_forward": true,
    "daeun_list": [
      {
        "age": 6,
        "pillar": "丙子"
      },
      {
        "age": 16,
        "pillar": "乙亥"
      },
      {
        "age": 26,
        "pillar": "甲戌"
      },
      {
        "age": 36,
        "pillar": "癸酉"
      },
      {
        "age": 46,
        "pillar": "壬申"
      },
      {
        "age": 56,
        "pillar": "辛未"
      },
      {
        "age": 66,
        "pillar": "庚午"
      },
      {
        "age": 76,
        "pillar": "己巳"
      },
      {
        "age": 86,
        "pillar": "戊辰"
      },
      {
        "age": 96,
        "pillar": "丁卯"
      }
    ]
  },
  "ten_gods": {
    "Year_Stem": "정인",
    "Year_Branch": "편관",
    "Month_Stem": "정관",
    "Month_Branch": "정인",
    "Day_Stem": "主",
    "Day_Branch": "편인",
    "Hour_Stem": "상관",
    "Hour_Branch": "정인"
  },
  "five_elements": {
    "strength": {
      "목": 11.72,
      "화": 25,
      "토": 34.69,
      "금": 15.62,
      "수": 20.62
    },
    "day_element": "금",
    "total_score": 160
  },
  "shinsal": {
    "year_shinsal": [
      {
        "branch": "寅",
        "shinsal": "겁살"
      },
      {
        "branch": "卯",
        "shinsal": "재살"
      },
      {
        "branch": "辰",
        "shinsal": "천살"
      },
      {
        "branch": "巳",
        "shinsal": "지살"
      },
      {
        "branch": "午",
        "shinsal": "년살"
      },
      {
        "branch": "未",
        "shinsal": "월살"
      },
      {
        "branch": "辛",
        "shinsal": "망신살"
      },
      {
        "branch": "酉",
        "shinsal": "장성살"
      },
      {
        "branch": "戌",
        "shinsal": "반안살"
      },
      {
        "branch": "亥",
        "shinsal": "역마살"
      },
      {
        "branch": "子",
        "shinsal": "육해살"
      },
      {
        "branch": "丑",
        "shinsal": "화개살"
      }
    ],
    "day_shinsal": [
      {
        "branch": "巳",
        "shinsal": "겁살"
      },
      {
        "branch": "午",
        "shinsal": "재살"
      },
      {
        "branch": "未",
        "shinsal": "천살"
      },
      {
        "branch": "辛",
        "shinsal": "지살"
      },
      {
        "branch": "酉",
        "shinsal": "년살"
      },
      {
        "branch": "戌",
        "shinsal": "월살"
      },
      {
        "branch": "亥",
        "shinsal": "망신살"
      },
      {
        "branch": "子",
        "shinsal": "장성살"
      },
      {
        "branch": "丑",
        "shinsal": "반안살"
      },
      {
        "branch": "寅",
        "shinsal": "역마살"
      },
      {
        "branch": "卯",
        "shinsal": "육해살"
      },
      {
        "branch": "辰",
        "shinsal": "화개살"
      }
    ]
  },
  "comprehensive_shinsal": {
    "twelve_stages": [
      {
        "pillar": "년주",
        "stem": "경",
        "branch": "사",
        "stage": "장생",
        "energy": "시작"
      },
      {
        "pillar": "월주",
        "stem": "경",
        "branch": "축",
        "stage": "묘",
        "energy": "잠복"
      },
      {
        "pillar": "일주",
        "stem": "경",
        "branch": "진",
        "stage": "양",
        "energy": "준비"
      },
      {
        "pillar": "시주",
        "stem": "경",
        "branch": "미",
        "stage": "관대",
        "energy": "성장"
      }
    ],
    "hidden_stems": {
      "사": [
        {
          "stem": "무",
          "type": "여기",
          "days": 7
        },
        {
          "stem": "경",
          "type": "중기",
          "days": 7
        },
        {
          "stem": "병",
          "type": "정기",
          "days": 16
        }
      ],
      "축": [
        {
          "stem": "계",
          "type": "여기",
          "days": 9
        },
        {
          "stem": "신",
          "type": "중기",
          "days": 3
        },
        {
          "stem": "기",
          "type": "정기",
          "days": 18
        }
      ],
      "진": [
        {
          "stem": "을",
          "type": "여기",
          "days": 9
        },
        {
          "stem": "계",
          "type": "중기",
          "days": 3
        },
        {
          "stem": "무",
          "type": "정기",
          "days": 18
        }
      ],
      "미": [
        {
          "stem": "정",
          "type": "여기",
          "days": 9
        },
        {
          "stem": "을",
          "type": "중기",
          "days": 3
        },
        {
          "stem": "기",
          "type": "정기",
          "days": 18
        }
      ]
    },
    "noble_stars": {
      "천을귀인": [
        {
          "name": "cheon_eul_gwiin",
          "korean_name": "천을귀인",
          "reference": "경",
          "location": [
            "축",
            "미"
          ],
          "meaning": "하늘의 복덕을 주관하는 최고의 귀인",
          "impact": "위급한 상황에서 구제받거나 귀인의 도움"
        }
      ],
      "문곡귀인": [
        {
          "name": "mun_gok_gwiin",
          "korean_name": "문곡귀인",
          "reference": "경",
          "location": [
            "사"
          ],
          "meaning": "응용 학문, 예체능, 언변의 귀인",
          "impact": "말솜씨가 좋고 예술적 재능이 있음"
        }
      ],
      "천덕귀인": [
        {
          "name": "cheon_deok_gwiin",
          "korean_name": "천덕귀인",
          "reference": "축",
          "location": [
            "경(천간)"
          ],
          "meaning": "하늘의 덕으로 재앙을 막아주는 귀인",
          "impact": "성품이 착하고 인자하며 어려움을 기적적으로 해결"
        }
      ],
      "월덕귀인": [
        {
          "name": "weol_deok_gwiin",
          "korean_name": "월덕귀인",
          "reference": "축",
          "location": [
            "경(천간)"
          ],
          "meaning": "달의 덕, 사회적 관계의 귀인",
          "impact": "인덕이 많고 주변의 도움으로 성공"
        }
      ],
      "학당귀인": [
        {
          "name": "hak_dang_gwiin",
          "korean_name": "학당귀인",
          "reference": "경",
          "location": [
            "사"
          ],
          "meaning": "배움의 집, 교육의 귀인",
          "impact": "총명하고 지혜로우며 학문에 재능"
        }
      ],
      "암록": [
        {
          "name": "am_rok",
          "korean_name": "암록",
          "reference": "경",
          "location": [
            "사"
          ],
          "meaning": "보이지 않는 곳의 녹봉",
          "impact": "예상치 못한 재정적 도움"
        }
      ],
      "협록": [
        {
          "name": "hyeop_rok",
          "korean_name": "협록",
          "reference": "경",
          "location": [
            "미"
          ],
          "meaning": "양쪽에서 돕는 녹",
          "impact": "보이지 않는 곳에서 지지와 도움"
        }
      ]
    },
    "evil_stars": {
      "괴강": [
        {
          "name": "gwae_gang",
          "korean_name": "괴강",
          "reference": "경진",
          "location": [
            "경진"
          ],
          "meaning": "우두머리의 기운, 극단적인 성격",
          "warning": "총명하고 카리스마 있지만 인생의 굴곡이 클 수 있음"
        }
      ],
      "백호대살": [
        {
          "name": "baek_ho_dae_sal",
          "korean_name": "백호대살",
          "reference": "간지",
          "location": [
            "정축"
          ],
          "meaning": "강하고 거친 기운, 용맹함",
          "warning": "피를 볼 수 있는 사고나 수술 주의"
        }
      ]
    },
    "naeum_elements": [
      {
        "pillar": "년주",
        "ganzi": "기사",
        "element": "대림목",
        "meaning": "큰 숲의 나무",
        "character": "넓게 뻗어 나가는 기상"
      },
      {
        "pillar": "월주",
        "ganzi": "정축",
        "element": "간하수",
        "meaning": "시냇물",
        "character": "작지만 끊임없이 흐름"
      },
      {
        "pillar": "일주",
        "ganzi": "경진",
        "element": "백랍금",
        "meaning": "백랍의 쇠",
        "character": "부드럽고 유연한 금속"
      },
      {
        "pillar": "시주",
        "ganzi": "계미",
        "element": "양류목",
        "meaning": "버드나무",
        "character": "유연하고 적응력이 뛰어남"
      }
    ],
    "overall_assessment": {
      "귀인_수": 7,
      "신살_수": 2,
      "주요_특징": [
        "귀인의 도움을 받는 복된 사주",
        "학문과 예술에 재능",
        "강한 카리스마와 리더십"
      ],
      "주의사항": [
        "수술이나 사고 주의"
      ],
      "활용방안": [
        "교육이나 학문 분야 추천"
      ]
    }
  }
}

응답 구조

  • saju: 사주팔자 정보 (기본 사주 계산과 동일)
  • daeun: 대운 정보
  • ten_gods: 십성(十星) 분석
    • 각 천간/지지의 육친 관계 (비견, 겁재, 식신, 상관, 편재, 정재, 편관, 정관, 편인, 정인)
  • five_elements: 오행(五行) 분석
    • strength: 각 오행(목, 화, 토, 금, 수)의 강도 (%)
    • day_element: 일간의 오행
    • total_score: 전체 오행 점수 합계
  • shinsal: 신살(神煞) 정보
    • year_shinsal: 연지 기준 신살 (역마, 화개 등)
    • day_shinsal: 일지 기준 신살 (도화, 겁살 등)
  • comprehensive_shinsal: 종합 신살 분석 (선택적으로 제공)
    • twelve_stages: 12운성 리스트 (각 항목에 pillar, stem, branch, stage, energy 포함)
    • hidden_stems: 지장간 딕셔너리 (지지별 숨은 천간 목록, 예: {"巳": [{"stem": "丙", "type": "...", "days": ...}]})
    • noble_stars: 귀인 딕셔너리 (타입별 귀인 상세 정보, 예: {"천을귀인": [{ name, korean_name, ... }]})
    • evil_stars: 신살 딕셔너리 (타입별 흉신 상세 정보, 예: {"양인": [{ name, warning, ... }]})
    • naeum_elements: 납음오행 리스트 (각 항목에 pillar, ganzi, element, meaning, character 포함)
    • overall_assessment: 종합 평가 정보 (귀인/신살 개수, 주요 특징, 주의사항, 활용방안)

※ comprehensive_shinsal 필드는 /v1/saju/analysis에서만 제공되며 기본/v1/saju/basic 응답에는 포함되지 않습니다.

특별 참고사항

시간 입력

사주에서 시주(時柱)는 2시간 단위로 구분됩니다. birth_time 파라미터는 정확한 출생 시간을 입력하면 자동으로 해당하는 시주로 변환됩니다:

시간 범위시주지지
23:00 - 00:59자시(子時)子
01:00 - 02:59축시(丑時)丑
03:00 - 04:59인시(寅時)寅
05:00 - 06:59묘시(卯時)卯
07:00 - 08:59진시(辰時)辰
09:00 - 10:59사시(巳時)巳
11:00 - 12:59오시(午時)午
13:00 - 14:59미시(未時)未
15:00 - 16:59신시(申時)申
17:00 - 18:59유시(酉時)酉
19:00 - 20:59술시(戌時)戌
21:00 - 22:59해시(亥時)亥

음력/양력 변환

is_lunar 파라미터를 통해 음력 생일을 지원합니다. 음력인 경우 내부적으로 양력으로 변환하여 정확한 사주를 계산합니다. 음력 윤달에 태어난 경우 is_leap_month를 true로 설정하세요.

일반적인 에러

에러 메시지설명해결 방법
음력 변환 실패음력 날짜를 양력으로 변환할 수 없음입력한 음력 날짜가 유효한지 확인 (1900-2100년 범위)
gender must be M or F성별 값이 올바르지 않음M 또는 F로 입력
UNAUTHORIZEDAPI 키가 유효하지 않음API 키 확인 및 재발급
RATE_LIMIT_EXCEEDED요청 제한 초과요청 제한 리셋 시간 대기 또는 플랜 업그레이드

400 Bad Request - 음력 변환 실패

응답 상태:400
{
  "detail": "음력 변환 실패"
}

400 Bad Request - 잘못된 성별 값

응답 상태:400
{
  "detail": "gender must be M or F"
}

다음 단계

자미두수 API

중국 전통 자미두수(紫微斗數) 분석 API

사주 분석 가이드

사주 해석과 활용 방법에 대한 상세 가이드