사주·타로 API — 계산 엔진과 고전 근거를 JSON 으로

공개 API · v1

사주 원국과 타로 해석을, 계산된 값으로 받으세요

생년월일시를 넣으면 네 기둥·오행·십신·대운이 JSON 으로 돌아옵니다. 타로는 78장과 스프레드 23종, 그리고 그 해석의 고전 근거까지 같은 계약으로 열려 있습니다. 회원가입도 키 발급도 없이 지금 바로 호출할 수 있습니다.

API 문서 보기 도입 문의

https://api.cynicalkim.com

같은 입력이면 같은 값

계산 경로에 AI 가 없습니다. 순수 함수라 재현되고, 응답의 meta 가 어떤 엔진 버전으로 계산했는지 매번 밝힙니다. 값이 달라졌다면 버전이 달라진 것입니다.

근거를 함께 돌려줍니다

해석만 주고 끝내지 않습니다. 어느 고전의 어느 대목에서 온 것인지, 원문 인용 게이트를 통과한 문장만 근거로 나갑니다. 대조하지 못한 문장은 출처만 남기고 인용을 비웁니다.

계약이 검사로 고정돼 있습니다

문서가 코드보다 정본이 되지 않도록, 공개 계약(OpenAPI 3.1)을 실제 라우트·요청 파서·응답 모양과 기계로 대조합니다. 어긋나면 배포가 아니라 검사가 먼저 실패합니다.

지금 열려 있는 엔드포인트 9개

메서드	경로	하는 일
GET	`/v1/health`	살아 있는지만 답한다. 의존성을 건드리지 않으므로 감시용으로 안전하다.
GET	`/v1/meta`	계약 버전·엔진 버전·데이터 세대를 밝힌다. 클라이언트가 캐시를 무효화할 기준으로 쓴다.
POST	`/v1/saju/calculate`	생년월일시로 사주 원국을 계산한다. 순수 함수라 같은 입력이면 언제나 같은 값이다.
POST	`/v1/saju/evidence`	그 명식이 왜 그렇게 읽히는지의 근거를 고전 출처와 함께 돌려준다.
GET	`/v1/saju/terms/{term}`	명리 용어 한 건의 뜻과 출처. 용어 이름 자체를 URL 인코딩해 넣는다.
GET	`/v1/tarot/cards`	타로 78장 목록. 식별 정보만 담기고 해석은 담기지 않는다.
GET	`/v1/tarot/cards/{slug}`	카드 한 장의 정·역방향 해석.
GET	`/v1/tarot/spreads`	스프레드 23종과 각 자리의 순서·의미. 자리 순서는 계약이다.
GET	`/v1/tarot/evidence/{slug}/{orientation}`	그 카드·방향 해석의 출처. 인용 게이트를 통과한 것만 나간다.

각 엔드포인트의 요청 필드·응답 모양·상태 코드는 API 문서에 있습니다.

60초 예제

키도 헤더도 필요 없습니다. 아래를 그대로 붙여 넣으면 됩니다.

curl -X POST https://api.cynicalkim.com/v1/saju/calculate \
  -H 'content-type: application/json' \
  -d '{"year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "M"}'

실제 응답에서 네 기둥만 추린 모습입니다.

{
  "ok": true,
  "data": {
    "pillars": {
      "year": {
        "stem": "庚",
        "stem_ko": "경",
        "branch": "午",
        "branch_ko": "오",
        "stem_index": 6,
        "branch_index": 6
      },
      "month": {
        "stem": "辛",
        "stem_ko": "신",
        "branch": "巳",
        "branch_ko": "사",
        "stem_index": 7,
        "branch_index": 5
      },
      "day": {
        "stem": "庚",
        "stem_ko": "경",
        "branch": "辰",
        "branch_ko": "진",
        "stem_index": 6,
        "branch_index": 4
      },
      "hour": {
        "stem": "癸",
        "stem_ko": "계",
        "branch": "未",
        "branch_ko": "미",
        "stem_index": 9,
        "branch_index": 7
      }
    }
  },
  "meta": {
    "...": "..."
  }
}

요금

무료

월 1만 건

공개 엔드포인트 9개 전부
키 발급·회원가입 없음
고전 근거 응답 포함

지금 그대로 쓰실 수 있습니다.

그 이상

문의

대량 호출·상업적 사용
전용 빈도 한도
필요한 필드·형식 협의

도입 문의

지금 상태를 그대로 적습니다. 공개 v1 은 무료·무인증이고, 사용량을 계량하거나 키를 발급하는 기능은 아직 없습니다. 그래서 「1만 건」은 청구서가 아니라 기준선입니다 — 그 규모를 넘겨 쓰실 계획이면 한도가 서로에게 문제가 되기 전에 문의로 알려 주세요. 남용을 막는 빈도 제한만 걸려 있고, 그 값과 동작은 문서에 적어 두었습니다.

버전과 호환

공개 v1 은 깨지 않고 더하기만 합니다. 필드가 추가될 수는 있어도 기존 필드가 사라지거나 뜻이 바뀌지 않습니다. 지금 라이브가 밝히는 버전은 이렇습니다.

{
  "api_version": "v1",
  "engine": {
    "saju": {
      "version": "1.0.0",
      "contract": "6c63c2a0"
    },
    "tarot": {
      "version": "1.0.0",
      "contract": "ff8bfcb5"
    }
  },
  "data_version": {
    "bundled": "82b6a80d",
    "tarot_kv": "24b4e6aa",
    "saju_kv": "6e219ce5"
  }
}

data_version 이 바뀌면 해석 데이터가 갱신된 것이고, engine.*.contract 가 바뀌면 계산 계약이 움직인 것입니다. 두 값은 서로 다른 뜻이라 따로 밝힙니다. 언제나 /v1/meta 가 현재 값을 알려 줍니다.

API 문서 보기 도입 문의