운세 서비스에서 어려운 쪽은 문장이 아니라 계산입니다. AI 는 이미 글을 잘 씁니다. 문제는 그 AI 에게 무엇을 근거로 주느냐입니다. 근거가 없으면 AI 는 그럴듯한 말을 지어내고, 사주 서비스에서 그것은 곧 신뢰의 문제가 됩니다.
그래서 역할을 나눕니다. 명리 계산은 API 가, 문장은 AI 가 맡습니다. 이 글은 그 조합으로 운세 서비스를 만드는 네 단계를 코드와 함께 정리합니다. 순서는 이렇습니다.
① 키 발급 ② 고객에게 사주 입력받기 (폼) → 명리 계산 호출 ③ 받은 값을 프롬프트에 넣기 ④ 완성된 운세 확인
각 단계는 짧습니다. 전체 코드는 서버 파일 한 장에 들어갑니다.
1. 키 발급 — 서버 환경변수에만 둡니다
대시보드에서 API 키를 발급하고, 서버 환경변수에만 보관하세요. 브라우저로 내려보낸 키는 누구나 소스에서 복사할 수 있고, 그 순간부터 회원님의 사용량이 남의 것이 됩니다.
키에는 만료 기간이 함께 정해집니다(기본 90일). 지나면 호출이 막히니 대시보드에서 연장하시면 됩니다. 브라우저에서 직접 호출하실 계획이라면 허용 도메인(CORS) 등록이 필요하고, 이 기능은 유료 키 전용입니다.
무료 키는 샌드박스로 동작합니다. 문서에 공개된 샘플 프로필의 입력값과 일치할 때 정상 응답하고, 응답의 구조와 모듈 구성은 유료 플랜과 같습니다. 연동과 화면은 무료 키로 끝까지 완성하실 수 있습니다.
2. 사주 입력 폼 — 받을 값은 다섯 가지뿐
화면에서 받을 것은 생년월일시·성별·음력 여부입니다. 출생지는 선택이며, 넣으면 진태양시로 보정합니다. 폼이 받은 값을 그대로 서버로 보내고, 서버가 API 를 호출하는 구조입니다.
<form onsubmit="send(event)">
<input name="birthYear">
<input name="birthMonth">
<input name="birthDay">
<input name="birthHour">
<select name="isFemale">…</select>
<button>내 운세 보기</button>
</form>
async function send(event) {
event.preventDefault()
const form = Object.fromEntries(new FormData(event.target))
const response = await fetch('/api/reading', {
method: 'POST',
body: JSON.stringify(form),
})
render(await response.json())
}
3. 명리 계산 호출 — 질문 하나에 엔드포인트 하나
v2 리딩 API 는 질문 단위입니다. "연간 운세를 만들려면 어떤 모듈을 켜야 하나"를 고민하는 대신, 목적에 맞는 엔드포인트 하나를 부르면 필요한 분석이 필요한 범위로만 담겨 옵니다. 오늘의 운세는 today, 금전운은 money, 궁합은 compatibility 처럼 이름이 곧 질문입니다.
import { SazuClient } from '@sazuapp/client'
// 키는 서버 환경변수에만 둡니다.
const sazu = new SazuClient({ apiKey: process.env.SAZU_API_KEY })
export async function POST(request) {
const form = await request.json()
// 목적에 맞는 토픽 하나를 부릅니다.
const result = await sazu.readings.today({
birthYear: form.birthYear,
birthMonth: form.birthMonth,
birthDay: form.birthDay,
birthHour: form.birthHour,
birthMinute: form.birthMinute,
isFemale: form.isFemale,
isLunar: form.isLunar,
birthCity: form.birthCity,
})
…
}
응답에는 계산 결과(modules)와 함께 활용 안내(guide)가 실려 옵니다. 이 응답을 어떻게 쓰면 되는지를 응답 스스로 설명하는 필드입니다.
4. 프롬프트에 값 넣기 — 두 가지 방법
가장 짧은 길은 안내를 통째로 싣는 것입니다. 지침을 길게 쓰지 않아도 AI 가 응답을 올바르게 씁니다.
const { guide, modules } = result
const prompt = [
guide.purpose, // 이 토픽이 답하는 질문
...guide.howToUse, // 응답 활용 지침
'위 지침대로 아래 분석을 풀어 주세요. 존댓말, 6문장 이내.',
JSON.stringify(modules),
].join('\n')
const reading = await ai.complete(prompt)
문체·분량·구성을 직접 정하고 싶다면, 필요한 값만 골라 문장에 넣습니다. 이때 말단 값을 먼저 변수로 꺼내면 문장이 짧게 읽힙니다.
const { fourPillars, dailyInteraction } = modules
const dayPillar = fourPillars.day.full
const iljin = dailyInteraction.ilju.ganji
const { stemSipseong, branchSipseong } = dailyInteraction.toDayMaster
const todaySinsal = dailyInteraction.sinsal
.map(({ name, meaning }) => `${name} — ${meaning}`)
const facts = [
`일주는 ${dayPillar} 입니다.`,
`오늘 일진은 ${iljin} 입니다.`,
`일간 기준으로 천간은 ${stemSipseong}, 지지는 ${branchSipseong} 작용입니다.`,
...todaySinsal,
].join('\n')
판정의 근거는 이미 문장으로 담겨 옵니다. 관계·신살의 meaning, 시기 판정의 note, 득실 판정의 basis 같은 필드를 그대로 인용하거나 요약하시면 됩니다. 규칙을 따로 익히실 필요가 없습니다.
5. 운세 결과 확인 — 지어낸 말이 섞이지 않게
완성된 문장을 화면에 그대로 보여주면 끝입니다. 다만 프롬프트에 "아래 사실만 근거로 쓰고, 없는 사실은 지어내지 마세요" 한 줄을 넣어 두시길 권합니다. 계산 결과가 근거로 들어가 있으므로, 그 범위를 벗어나지 않게 묶어 두는 것만으로 결과가 안정됩니다.
같은 입력이면 계산 결과는 항상 같습니다. 문장만 AI 가 바꾸므로, 표시가 이상할 때 계산이 틀린 것인지 문장이 튄 것인지를 바로 가릴 수 있습니다.
6. 목적이 바뀌면 토픽만 바꿉니다
오늘의 운세로 시작해 월간·연간·대운·궁합·연애·금전·건강으로 넓힐 때, 바꾸는 것은 엔드포인트 이름 하나입니다. 응답의 봉투 구조는 토픽이 달라져도 같으므로 파싱 코드는 한 벌이면 됩니다.
토픽마다 어떤 분석이 담기는지, 그 값을 문장에 어떻게 넣는지는 API 문서의 토픽 카탈로그에 토픽별 예제로 정리해 두었습니다. TypeScript · Python · PHP 로 함께 제공합니다.
7. 무료로 시작하기
키 발급에 신용카드가 필요 없습니다. 무료 플랜으로 연동·화면·로딩 흐름을 끝까지 검증하고, 실제 생년월일 계산이 필요해질 때 유료 플랜으로 전환하시면 됩니다.
마치며
운세 서비스의 어려움은 대부분 사주 엔진에 있습니다. 절기 경계, 진태양시, 지장간, 격국과 용신 — 하나라도 어긋나면 결과 전체가 달라지고, 그 검증에만 몇 주가 듭니다.
그 부분을 API 에 맡기면 남는 일은 화면과 문장입니다. 네 단계면 충분합니다.