API 문서

사주 API

생년월일을 보내면 명리 판정을 계산해 돌려줍니다. 엔드포인트는 질문 단위로 12종이고, 응답에는 판정 근거 문장과 용어집이 함께 실립니다. 모든 경로는 https://api.supasaju.com 아래입니다.

인증

x-api-key 헤더에 키를 담습니다. Authorization: Bearer 도 받습니다.

curl https://api.supasaju.com/v2/me -H "x-api-key: $SAJU_API_KEY"

키는 대시보드에서 발급합니다. 발급 직후 한 번만 보여 주고 저장하지 않으므로, 그 자리에서 안전한 곳에 옮겨 두십시오. 키는 브라우저에 두지 마십시오 — 서버에서만 부르십시오.

5분 시작하기

1. 키를 발급합니다. 2. 아래를 그대로 실행합니다. 3. 받은 JSON 을 LLM 에 넘깁니다.

curl -X POST https://api.supasaju.com/v2/saju/manse \
  -H "x-api-key: $SAJU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "birthYear": 1988,
  "birthMonth": 3,
  "birthDay": 14,
  "birthHour": 9,
  "birthMinute": 20,
  "isFemale": false,
  "isLunar": false,
  "birthCity": "서울"
}'

const res = await fetch('https://api.supasaju.com/v2/saju/manse', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.SAJU_API_KEY!,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    "birthYear": 1988,
    "birthMonth": 3,
    "birthDay": 14,
    "birthHour": 9,
    "birthMinute": 20,
    "isFemale": false,
    "isLunar": false,
    "birthCity": "서울"
  }),
})

const { data } = await res.json()

// 판정 근거 문장만 모읍니다 — 이게 풀이의 재료입니다.
const facts: string[] = []
const walk = (v: unknown, path = ''): void => {
  if (Array.isArray(v)) return v.forEach((x, i) => walk(x, `${path}[${i}]`))
  if (v === null || typeof v !== 'object') return
  for (const [k, x] of Object.entries(v)) {
    if (typeof x === 'string' && ['reasoning', 'basis', 'meaning'].includes(k)) facts.push(x)
    else walk(x, path ? `${path}.${k}` : k)
  }
}
walk(data.modules)

// guide 와 glossary 를 함께 실어 넘깁니다.
const prompt = [
  data.guide.purpose,
  ...data.guide.howToUse,
  '',
  '용어의 뜻:',
  ...Object.entries(data.glossary).map(([t, d]) => `- ${t}: ${d}`),
  '',
  '계산된 사실:',
  ...facts.map((f) => `- ${f}`),
  '',
  '위 사실만으로 존댓말 6문장으로 풀어 주세요.',
].join('\n')

import os, json, requests

res = requests.post(
    "https://api.supasaju.com/v2/saju/manse",
    headers={"x-api-key": os.environ["SAJU_API_KEY"]},
    json={
        "birthYear": 1988,
        "birthMonth": 3,
        "birthDay": 14,
        "birthHour": 9,
        "birthMinute": 20,
        "isFemale": False,
        "isLunar": False,
        "birthCity": "서울"
    },
)
data = res.json()["data"]

# 판정 근거 문장만 모읍니다 — 이게 풀이의 재료입니다.
FACT_KEYS = {"reasoning", "basis", "meaning"}
facts = []

def walk(v):
    if isinstance(v, list):
        for x in v:
            walk(x)
    elif isinstance(v, dict):
        for k, x in v.items():
            if isinstance(x, str) and k in FACT_KEYS:
                facts.append(x)
            else:
                walk(x)

walk(data["modules"])

# guide 와 glossary 를 함께 실어 넘깁니다.
prompt = "\n".join([
    data["guide"]["purpose"],
    *data["guide"]["howToUse"],
    "",
    "용어의 뜻:",
    *[f"- {t}: {d}" for t, d in data["glossary"].items()],
    "",
    "계산된 사실:",
    *[f"- {f}" for f in facts],
    "",
    "위 사실만으로 존댓말 6문장으로 풀어 주세요.",
])

공통 요청 필드

문자열로 된 정수("1988")도 받습니다. 강제 변환이 일어나면 meta.warnings 와 X-Input-Coerced 헤더로 알려 드립니다 — 조용히 고치지 않습니다.

응답 구조

{
  "success": true,
  "data": {
    "topic": "manse",
    "guide": {
      "purpose": "…",
      "howToUse": [
        "…"
      ]
    },
    "glossary": {
      "원국": {
        "definition": "…",
        "en": "Natal Chart"
      }
    },
    "reference": null,
    "input": {
      "…": "정규화된 입력"
    },
    "timezone": {
      "…": "적용된 시각 보정"
    },
    "modules": {
      "fourPillars": "…"
    },
    "diagnostics": [],
    "ruleset": {
      "version": "0.2.1",
      "profile": "ko-standard"
    }
  },
  "meta": {
    "topic": "manse",
    "modules": [
      "…"
    ],
    "tier": "pro",
    "responseMs": 8,
    "cached": false
  }
}

응답 크기와 LLM 비용

응답을 통째로 LLM 에 넣기 전에 이 절을 읽어 주십시오. 저희 응답은 큽니다. 판정마다 근거 문장을 달고 간지마다 파생 표기를 함께 실어서 그렇습니다. 그게 이 API 의 값어치지만, 그대로 프롬프트에 넣으면 LLM 입력 비용이 저희 호출 요금보다 큽니다.

샘플 프로필 기준입니다. 토큰 수는 한글 기준 어림이며 모델마다 다릅니다.

줄이는 방법

1. 필요한 문장만 뽑으십시오. 응답의 3분의 1이 문장이고 나머지는 구조와 파생 표기입니다. LLM 에게는 문장만 있으면 됩니다. 각 토픽 페이지의 LLM 연동 예시가 그렇게 합니다 — reasoning·basis·meaning 만 걷어 내면 원본의 3분의 1 이하로 줄어듭니다.

2. detail 을 쓰십시오. minimal 은 판정값만 돌려주고 해설을 뺍니다. 문장을 직접 쓰실 거라면 이쪽이 맞습니다. 반대로 근거 문장이 필요하시면 minimal 을 쓰지 마십시오 — reasoning·basis 가 정확히 그것이 지우는 것입니다. 그때는 아래 4·6 번으로 줄이십시오.

full 이 standard 에 더하는 것은 대운 항목의 원국 관계·12신살·공망, 그리고 운 12신살·운 신살의 뜻풀이입니다. 사주 고유의 판정 문장은 이미 standard 에 있습니다. 그래서 오늘의 운세·월 운세·건강운에서는 full 이 standard 와 거의 같습니다 (2~5%) — 대운이 구성에 없거나 비중이 작은 토픽이라 더할 것이 남지 않습니다. 이 세 토픽에서는 full 을 부를 이유가 없습니다.

3. 필요한 토픽만 부르십시오. 토픽마다 모듈 구성이 다릅니다. “연애 운”은 모듈 10종이라 가장 무겁고, “건강운”·“오늘의 운세”는 그 절반입니다.

4. 안 쓰는 모듈을 빼십시오 — exclude. 덩치는 문장이 아니라 구조입니다. 그래서 detail 을 내리는 것보다 모듈 하나를 빼는 편이 대개 더 크게 줄어듭니다. 실측입니다.

토픽의 핵심 모듈은 뺄 수 없습니다 — 빼고 나면 그 토픽이 답하기로 한 질문에 아무 말도 못 하는 응답이 되므로 400 으로 거절하고 어느 모듈인지 알려 드립니다. 모듈 이름은 GET /v2/saju/modules 에 있고, 무엇을 뺐는지는 응답의 meta.excluded 에 담겨 옵니다. 그 토픽에 원래 없는 모듈을 적어도 탈나지 않습니다.

5. 얼마나 되는지는 응답이 알려 줍니다. 모든 응답의 meta.approxTokens 에 이 응답이 LLM 컨텍스트에서 차지할 대략의 토큰 수가 담깁니다. 어림이며 모델마다 다릅니다 — 예산을 재는 용도입니다.

6. 대운을 필요한 만큼만 받으십시오. 대운 한 개가 약 3KB라 가장 큰 지렛대입니다. 두 가지 방법이 있고, 대개는 decadeWindow 쪽이 맞습니다.

둘을 함께 보내면 decadeWindow 가 이깁니다. decadeCount: 3 은 서른여덟 살에게 7·17·27세 대운을 줍니다 — 그때 decadeFortune.current.phase 가 "after" 로 오고 사유가 문장으로 담기므로 조용히 틀리지는 않지만, 원하던 답도 아닐 것입니다. 어느 쪽으로 골랐는지는 decadeFortune.selection 에 담겨 옵니다.

Free 샌드박스

Free 키는 기초 모듈 3종(fourPillars · elements · decadeFortune)을 임의의 생년월일로 계산합니다. 나머지 모듈은 샘플 프로필 입력일 때만 유료와 같은 구성으로 응답합니다.

핵심 모듈이 무료 범위인 토픽은 임의의 생년월일로도 온전히 쓸 수 있습니다 — 만세력 · 대운 10년 · 관계 궁합.

GET /v2/saju/samples 로 입력값을 그대로 받아 쓸 수 있습니다.

요청 한도

한도는 차단입니다. 넘으면 막힐 뿐 초과 요금이 붙지 않습니다.

응답 헤더

CORS

키를 브라우저에 두지 마십시오. 이 API 는 서버에서 부르는 것을 전제합니다. 대시보드에서 도메인을 등록하면 그 출처에 한해 브라우저 호출을 허용하지만, 키 노출 위험은 그대로 남습니다.

엔드포인트 12종 → · 분석 모듈 14종 → · 에러 코드 → · OpenAPI 3.1 →