오늘의 운세 API 예제 — 프롬프트 하나로 만드는 실시간 일진 화면

2026. 9. 3.

오늘의 운세 화면은 만세력 API 의 /v2/sazu/today 하나로 만들 수 있습니다. 이 글의 프롬프트를 복사해 Claude Code · ChatGPT · Cursor 같은 AI 코딩 도구에 붙여넣으시면 index.html 한 파일이 생성됩니다. 빌드 도구도 백엔드도 필요 없습니다.

무료 키 샌드박스 예제와 달리 생년월일을 아무 값이나 넣어도 실시간으로 계산됩니다. 유료 플랜 키가 필요합니다.

API v2 예제입니다

v2 는 하나의 운세 서비스는 하나의 API 엔드포인트로 구성됩니다. 예를 들어 /v2/sazu/today 를 호출하시면 오늘의 운세 서비스 만들기에 필요한 명리 계산이 모두 들어 있습니다. 즉 API 호출을 보내실 때 같이 사주 정보(생년월일시, 성별, 양음력 등)를 함께 보내시면 그 사주에 맞는 오늘의 운세를 받으실 수 있습니다.

호출을 보낸 뒤 받은 응답에는 data.guide 와 data.glossary 가 함께 포함되어 있습니다. 앞의 것은 이 응답을 LLM 에 넘길 때 쓸 지침이고, 뒤의 것은 응답에 나온 명리 용어의 정의입니다. 문장을 만드실 때 프롬프트를 직접 쓰지 않으셔도 기본 운세가 출력되며, 만약 나만의 운세 결과를 원하시는 경우에는 별도의 프롬프트를 작성해서 LLM 에게 보내면 원하는 결과를 얻을 수 있습니다. 하지만 이 경우에는 원하는 운세 결과를 얻기 위한 세밀한 가이드 수정이 요구됩니다.

무엇이 나오는가

오늘의 일진과 한 줄 요약
내 일간과 오늘의 관계 — 십성 · 12운성
오늘의 신살과 그 의미
원국과의 형 · 충 · 합 · 해
오행 변화 (이전 → 오늘)

오늘의 운세 API 예제 화면 — 오늘의 일진 경진과 내 일간과의 십성·12운성 관계 — 완성 화면. 날짜를 보내지 않으면 서버가 당일 일진으로 계산합니다.

날짜는 보내지 않아도 됩니다

date 를 생략하면 서버가 요청 시점의 날짜로 계산합니다. 매일 다른 결과가 나오므로 별도의 스케줄링이 필요 없습니다. 특정 날짜를 보고 싶을 때만 date: "2026-09-03" 형태로 지정하시면 됩니다.

출생시간을 모르는 경우 birthHour 를 null 로 보내면 시주 없이 계산됩니다.

오늘의 신살과 의미, 원국과의 형·충·합·해, 오행 변화 막대 그래프 — 신살·형충회합의 해석 문장과 오행 변화. 모두 응답에 들어 있는 값입니다.

유료 키 — 오늘의 운세 화면

/v2/sazu/today · 유료 키 필요

아래 사양대로 **HTML 파일 하나**를 만들어 주세요. 빌드 도구·프레임워크·백엔드 없이 `index.html` 안에 HTML + CSS + JS 를 모두 담고, 브라우저로 열면 바로 동작해야 합니다.

## 만들 것

생년월일시를 넣으면 **오늘의 운세**가 나오는 한 페이지입니다.

## API

```http
POST https://api.sazu.app/v2/sazu/today
Content-Type: application/json
x-api-key: <내 키>
```

```json
{
  "birthYear": 1990, "birthMonth": 3, "birthDay": 15,
  "birthHour": 9, "birthMinute": 0,
  "isLunar": false, "isFemale": false, "birthCity": "서울"
}
```

- `birthHour` 를 모르면 `null` 입니다 (0 이 아닙니다). 시주가 빠진 채 계산됩니다.
- `date` 를 넣으면 그 날짜로, **생략하면 서버가 오늘 날짜로** 계산합니다. 이 예제에서는 생략합니다.
- 생년월일은 아무 값이나 됩니다 (유료 키).

응답은 `{ success, data: { modules: {...} }, meta: {...} }` 형태입니다.

## 화면 구성

`data.modules.dailyInteraction` 이 주인공입니다.

### ① 오늘의 일진 (가장 크게)

- `.ilju.ganji` 를 큰 글씨로, 그 아래 `.date` 를 표시합니다.
- `.summary` 를 한 줄 요약으로 놓습니다 (예: `지살 / 형 2건, 해 2건`).

### ② 나와 오늘의 관계

`.toDayMaster` 의 `.dayMaster`(내 일간) · `.stemSipseong` · `.branchSipseong` · `.twelveStage` 를 라벨-값 4개로 표시합니다.

### ③ 오늘의 신살

`.sinsal` 배열입니다. 각 항목의 `.name` 을 배지로, `.meaning` 을 그 아래 문장으로, `.basis` 는 작게 표시합니다.

### ④ 원국과의 작용

`.relations` 배열입니다.

- `.type`(형·충·합·해)별로 색을 다르게 한 배지와 `.meaning` 문장을 표시합니다.
- `.sourcePosition` → `.targetPosition` 을 작게 덧붙입니다.
- 배열이 비어 있으면 "오늘은 원국과 부딪히는 작용이 없습니다" 로 대체합니다.

### ⑤ 오행 변화

`.elementShift` 의 `.before` 와 `.after` 를 나란한 막대로 비교하고, `.gained` 원소는 강조합니다. 목=초록, 화=빨강, 토=노랑, 금=회색, 수=파랑으로 합니다.

### ⑥ 맥락 (접이식, 기본 접힘)

- `data.modules.seun.currentSeun.interpretation`
- `data.modules.weolun.currentWeolun.interpretation`

### ⑦ 확장 안내 카드 (반드시 넣어 주세요)

결과가 렌더된 **아래쪽**에 카드를 하나 더 둡니다. 결과가 나왔을 때만 보입니다.

제목은 **여기까지가 AI 없이 만든 화면입니다** 로 합니다.

본문은 아래 문구를 그대로 씁니다.

> 지금 보고 계신 문장은 전부 API 응답에 들어 있던 것입니다. AI 도, 프롬프트도 쓰지 않았습니다.
>
> 여기에 LLM 을 붙이면 같은 데이터로 **훨씬 풍부한 문장의 운세 상품**을 만들 수 있습니다. 그리고 그 방법은 응답이 스스로 알려 줍니다.

그 아래에 접이식(`details`) **"다음 단계 — LLM 붙이기"** 를 둡니다. 펼치면 이 순서로 보이게 합니다.

1. 문장 한 줄 — "응답의 `data.guide` 에 LLM 에게 줄 지침이 이미 들어 있습니다. 프롬프트를 직접 쓰지 않아도 됩니다."
2. 실제 응답에서 읽어온 `data.guide.purpose` 를 한 줄로 표시합니다.
3. `data.guide.howToUse` 배열을 그대로 불릿으로 표시합니다.
4. 아래 코드를 **주석 처리된 예시**로 표시합니다 (실행하지 않습니다).

```js
// 이 응답을 그대로 LLM 에 넘기면 운세 문장이 나옵니다
const res = await fetch('https://api.sazu.app/v2/sazu/today', { /* ... */ })
const { data } = await res.json()

await llm.chat([
  { role: 'system', content: data.guide.howToUse.join('\n') },
  { role: 'user',   content: JSON.stringify(data.modules) },
])
```

5. 마지막 줄 — "`data.glossary` 에 이 응답에 나온 명리 용어의 뜻이 함께 실려 있어, 용어를 풀어 쓰는 것까지 LLM 이 알아서 합니다."

이 카드는 **실제 응답값**(`guide.purpose`, `guide.howToUse`)을 읽어서 채웁니다. 문구를 하드코딩하지 말아 주세요. 응답에 정말로 들어 있다는 것이 요점입니다.

## 중요 — 문장을 창작하지 말아 주세요

응답 안에 이미 한국어 해석(`.meaning` · `.interpretation` · `.summary`)이 들어 있습니다. 그것만 화면에 옮깁니다. 운세 문장을 새로 지어내면 안 됩니다.

## 동작

- 폼 기본값을 채워 둡니다 (1990-03-15 09:00 남 서울). 열자마자 조회할 수 있어야 합니다.
- "출생시간 모름" 체크박스를 두고, 체크하면 `birthHour` 를 `null` 로 보냅니다.
- 조회 중에는 버튼을 비활성으로 두고 "계산 중…" 을 표시합니다.
- 에러가 오면 `error.message` 를 그대로 보여 줍니다.
- 같은 입력으로 다시 조회하면 결과만 갱신합니다 (페이지 리로드 없이).

## 스타일

- 다크 배경, 카드형 레이아웃으로 하고, 모바일 375px 에서도 깨지지 않게 합니다.
- 외부 CSS/JS 는 불러오지 않습니다 (CDN 포함). 시스템 폰트만 씁니다.

## 키

`<script>` 맨 위에 아래 한 줄만 둡니다.

```js
const API_KEY = "여기에_키_붙여넣기" // www.sazu.app/manse-api/dashboard/keys 에서 발급
```

키를 코드에 두는 것은 예제이기 때문입니다. 배포 시 처리는 아래 「예제 표시」의 문구로만 남깁니다.

## 예제 표시

이 파일이 예제라는 것이 남아 있도록 두 곳에 표시합니다. 길게 쓰지 않습니다.

파일 맨 위 HTML 주석:

```html
<!-- 만세력 API 연동 예제. 학습·검증용이며 배포용이 아닙니다.
     배포 전 API 키 보호, 호출 제한, 개인정보 처리 절차를 확인하세요. -->
```

화면 맨 아래 한 줄 (작은 글씨, 흐린 색):

> 만세력 API 연동 예제입니다. 배포 전 키 보호와 개인정보 처리를 확인하세요.

## 여는 방법 — 만든 뒤 직접 띄워서 확인해 주세요

파일만 만들고 끝내지 마시고, **로컬 서버를 띄워 브라우저에서 실제로 동작하는지 확인**한 뒤 결과를 알려 주세요.

```bash
python3 -m http.server 8000   # 또는  npx serve .
```

그리고 `http://localhost:8000` 을 여세요.

`file://` 로 직접 여는 방법은 안내하지 마세요. 브라우저가 그 경우 외부 API 호출을 막습니다(origin 이 `null` 이라 차단됩니다). `localhost` 는 API 가 허용합니다.

호출이 네트워크 단계에서 실패하면(TypeError 등) 화면에 아래 안내를 그대로 띄우세요. 나중에 파일을 다시 열었을 때 필요한 사람에게만 보이면 됩니다.

> 호출이 차단되었습니다. `file://` 로 연 페이지는 외부 API 를 호출할 수 없습니다. 파일이 있는 폴더에서 `python3 -m http.server 8000` 을 실행하고 `http://localhost:8000` 으로 여세요.

## 하지 말아야 할 것

- 백엔드·npm·빌드 설정은 만들지 않습니다.
- 파일을 쪼개지 않습니다 (`index.html` 하나).
- 응답에 없는 운세 문장을 창작하지 않습니다.

버튼이 동작하지 않으면 위 상자를 클릭한 뒤 전체 선택(Ctrl/Cmd + A)해 복사하세요.

실행하시려면 본인 API 키가 필요합니다. 무료 키는 신용카드 등록 없이 발급하실 수 있습니다.

무료 키 발급 API 문서

예제의 범위

학습·검증용이며 배포용이 아닙니다. 실제 서비스로 공개하실 때는 아래가 추가로 필요합니다.

API 키 — 예제는 브라우저에 키가 노출됩니다. 서버 경유 호출과 허용 도메인 등록이 필요합니다.
호출 제한 — 예제에는 남용 방지 장치가 없습니다.
개인정보 — 생년월일·성별·출생시간 수집 시 동의와 처리방침이 필요합니다. 응답을 외부 LLM 에 전달하시는 경우 해당 제공사가 처리수탁자가 되며 국외이전에 해당할 수 있습니다.
콘텐츠 고지 — 운세 해석을 의료·법률·재정 판단의 근거로 사용하지 않도록 하는 안내를 권합니다.
장애 처리 — 타임아웃·재시도·실패 안내가 예제에는 없습니다.

일반적인 안내이며 법률 자문은 아닙니다.

무료로 먼저 보시려면

유료 플랜 없이 응답 구조부터 확인하고 싶으시면 무료 키 샌드박스 예제를 보세요. 응답 구조가 같아 화면을 만들어 두고 키만 교체하면 그대로 동작합니다.

문의

막히시는 부분이나 의견은 contact@sazu.app 으로 보내주세요.

SAZU API를 시작해보세요

신용카드 없이, 무료로 시작할 수 있습니다.

무료 시작 API 문서