복잡한 코딩 없이, 빠르게 운세서비스가 완성 됩니다.

설명서를 정독하지 않아도 됩니다. 가입 → 키 발급 → 빌더에서 바로 만들기 — 이 순서로 곧장 시작하시길 권합니다. 막히는 부분이 생기면 그때 아래 문서를 펼쳐 보세요.

1. 가입 + API 키 발급 — 브랜드 이름(예: 우아한 사주운세) 입력 후, 마이페이지 › API 키 › 새 키 발급
2. 빌더에서 만들기 — 마이페이지 › 빌더에서 운세를 고르고 라디오 몇 번으로 레시피 완성. 무료 샘플 미리보기로 결과를 바로 확인합니다 (코드 불필요, 저장·검토 전에도 가능)
3. 연동 — 저장 시 자동 검토(approved). 빌더 ⑦단계 바이브 코딩 프롬프트를 AI 툴(Claude · Codex · Gemini)에 붙여넣어 화면까지 완성하거나, POST /api/v1/render 로 직접 호출

💡 코드를 몰라도 됩니다 — 빌더 무료 샘플 미리보기로 풀이 품질을 먼저 확인하고, 마음에 들면 ⑦단계 프롬프트를 그대로 붙여넣어 서비스를 완성하세요.

• 운세 종류 — 오늘·일일·월간·연간·고민·관계·연애·대운·인생 (9종)
• 크레딧 — 호출 1회당 차감되는 단위. 운세별 1~3 크레딧 (분량·복잡도 기준, 위 표의 크레딧 차감 열 참조)
• 플랜 — 월 포함 크레딧 수만 다름. 토큰 한도는 플랜과 무관 (운세별 고정)
• 페르소나 — 풀이 어조 프리셋 9종 (따뜻한 · 시크한 · MZ · 전통 · 코믹 · 신비로운 · 시적인 · 차분·이성적 · 단호·직설)
• 레시피 — 빌더에서 위→아래로 라디오를 선택해 운세를 정의 (분석 방법 · 페르소나 · 작성 방식 · 출력 형식). 코드·변수 불필요, 항목마다 직접 입력도 가능
• 검토(approved) — 저장한 레시피는 자동 검토 통과 후에만 API 에 반영
• 환각 방지 8원칙 — 없는 사실 생성·규칙 우회를 막는 빌더 코어. 모든 호출에 불변 적용되며 끄거나 수정할 수 없음

빌더는 위에서 아래로 내려오며 라디오를 선택하면 레시피가 완성됩니다. ⑤ 변경사항 검토로 승인한 뒤, ⑥·⑦에서 연동 방식과 바이브 코딩 프롬프트까지 받아 화면을 완성합니다.

• 사주 데이터 — 생년월일시로 SAZU 엔진이 자동 계산해 풀이에 주입 (입력 불필요)
• ① 운세 종류 · 분석 방법 — 작성할 운세를 고르고, 사주 계산 결과를 어떻게 분석해 화면에 표시할지 시스템 기본 분석 또는 직접지정을 선택
• ② 페르소나(어조) — 풀이 전체 분위기를 9종 중 선택
• ③ 작성 방식 — 화자 역할 · 화법 · 분량 · 독자 호칭 (각 항목 직접 입력 가능 — 예: 호칭을 “고객님”·“○○님”으로)
• ④ 출력 형식 — 형식(줄글·불릿·번호 섹션·표 혼합) · 배치(총평→세부 등) · 직접 지정 문장(홍보 문구·링크)
• ⑤ 변경사항 검토 + 실시간 미리보기 — 자동 검토 통과 시 approved → API 반영. 저장 전에도 무료 샘플 미리보기로, 승인 후에는 실제 미리보기로 결과를 확인
• ⑥ 연동 방식 · 기술 환경 — 기존 프로젝트에 이식 또는 새 프로젝트, 기술 환경(정적 HTML · Next.js/React · Node.js · Python) 선택. 이 선택이 아래 ⑦ 예제에 반영됨
• ⑦ 연동 안내(바이브 코딩 프롬프트) — 완성 레시피 + ⑥ 설정이 녹아든 프롬프트를 AI 툴(Claude · Codex · Gemini)에 붙여넣으면 화면까지 자동 구현. 서버 호출용 코드 예제도 함께 제공

대부분 라디오 선택만으로 완성됩니다. 더 세밀하게 조정하려면 ①의 직접 지정 이나 ③·④의 직접 입력 칸에 일반인이 이해할 말로 적으면 됩니다 — 실제 사주 계산 결과는 SAZU 가 자동으로 넣어 줍니다.

예시 — ① 직접 지정 (분석 방법)

오늘 하루의 전반 기운을 따뜻하게 풀어 주세요.
- 일 · 애정 · 금전 · 건강 흐름을 각각 2~3문장으로
- 좋은 점은 격려하고, 조심할 점은 부드럽게 짚어 주세요
- 어려운 명리 용어는 쉬운 말로 바꿔서 설명해 주세요

예시 — ④ 직접 지정 (출력 형식)

- 첫 줄에 오늘의 한 줄 요약 (이모지 1개)
- 마지막에 "오늘의 행운 키워드: ○○" 한 줄
- 끝에 "더 자세한 풀이는 OurApp 에서 👉" 안내 추가

💡 저장·검토 전에는 무료 샘플 미리보기로, approved 후에는 실시간 미리보기로 샘플 사주의 실제 풀이를 확인합니다.
(실시간 미리보기는 무료 크레딧부터 차감, 프롬프트로 AI 연산 실행).

⚠️ 작성 시 주의사항

1. 합계 토큰이 운세별 한도를 넘지 않아야 합니다 (빌더에서 실시간 확인).
2. 환각 방지 8원칙과 운세 범위(오늘/이번 달/올해 등)는 빌더 코어로 고정하여 최대한 AI 환각을 예방합니다 — 어조·용어·형식·호칭·맺음말만 자유롭게 설정합니다.
3. 운세 생성 목적 외 다른 의도(시스템 우회·자원 접근 등)는 자동 검토 후 차단되며 모니터링 대상이 될 수 있습니다.

엔드포인트 · POST https://studio.sazu.app/api/v1/render

인증 · 헤더 X-API-Key: 발급받은_키 (server-to-server, 키는 외부 노출 금지)

요청 본문

• service string · 운세 종류 id — 아래 9종 중 하나 (id·이름 대응은 위 운세 종류 표 참조)
• birth.birthYear number · 1900~2100
• birth.birthMonth number · 1~12
• birth.birthDay number · 1~31
• birth.birthHour number|null · 0~23 (모르면 null)
• birth.isFemale boolean
• birth.isLunar boolean · 선택 (음력 여부)
• birth.birthCity string · 선택

service 가능 값 (9종)

["today","daily","monthly","yearly","consult","compatibility","love","decade","life"]

응답 (200)

{
  "success": true,
  "data": {
    "text": "오늘 당신의 기운은 ...",   // 완성된 풀이 (그대로 화면에 출력)
    "service": "today"
  },
  "meta": { "version": 3, "tier": "slim", "inputTokens": 850, "outputTokens": 1100 }
}

✅ data.text 를 받아서 화면에 보여줄 컴포넌트에 적용합니다.

연동 예제

# 현재 사용중인 AI 도구 Claude, Codex, Gemini 등에 그대로 붙여넣으세요 👇

[목표]
이미 운영 중인 내 프로젝트에 '내 서비스'의 "오늘의 운세" 기능을 새 기능으로 추가해줘. 기존 폴더 구조·상태관리·디자인 토큰/컴포넌트 컨벤션을 그대로 따르고, 빌드·패키지 설정 변경은 최소화해서 새 페이지 또는 모달로 붙여줘.
사용자가 생년월일시를 입력하면 완성된 "오늘의 운세" 풀이를 화면에 보여주는 기능이다.

[기술 환경]
기술 환경: Next.js(App Router)·TypeScript. 시스템 구성: app/api/fortune/route.ts 백엔드 라우트에서 API 키를 보관하고 SAZU 를 호출한다. 클라이언트 컴포넌트의 입력 폼이 그 라우트를 부른다.

[보안 — 가장 중요]
- API 키는 코드에 하드코딩하지 말고 서버 환경변수 SAZU_STUDIO_KEY 로만 읽는다. .env.example 에는 빈 자리표시자(SAZU_STUDIO_KEY=)만 두고 실제 값은 넣지 않는다.
- 키는 브라우저·클라이언트 코드·git 저장소에 절대 노출 금지.
- 호출은 반드시 내 백엔드를 경유한다: 프론트 폼 → 내 백엔드 라우트 → SAZU. 프론트에서 SAZU 를 직접 부르지 않는다.

[API]
- POST https://studio.sazu.app/api/v1/render
- 헤더: X-API-Key: <내 키>, Content-Type: application/json
- 본문: { "service": "today",
          "birth": { "birthYear": 1990, "birthMonth": 5, "birthDay": 15,
                     "birthHour": 10,      // 0~23, 모르면 null
                     "isFemale": false,    // 여성이면 true
                     "isLunar": false } }  // 음력이면 true (기본 false)
- 성공: { "success": true, "data": { "text": "완성된 풀이" } } → data.text 를 화면에 표시
- 실패: { "success": false, "error", "message" } — HTTP 401(키 오류) · 402(크레딧 소진/구독 필요) · 429(과다 요청) · 400(입력 오류)
  각 error 를 사용자에게 친절한 안내로 처리(특히 402 는 "잠시 후 다시" 또는 안내 문구).

[입력 폼 & 검증]
- 연(1900~2100)·월(1~12)·일(1~31) 필수, 시(0~23)는 모르면 비워서 null, 성별, 양/음력 선택.
- 미래 날짜·범위 밖 값은 막고, 검증 통과 시에만 호출.

[결과 표시]
- data.text 는 줄바꿈·마크다운(굵게·목록·표 등)이 포함될 수 있으니 그에 맞게 렌더한다(마크다운 렌더 또는 최소한 줄바꿈 유지).
- '내 서비스' 브랜드·페이지 스타일에 맞게 감싸고, 모바일에서도 잘 보이게 반응형으로.
- 로딩 상태·에러 메시지·빈 결과를 모두 안전하게 처리.

[비용]
- 호출 한 번마다 크레딧이 차감된다. 같은 입력으로 불필요하게 반복 호출하지 말고, 필요하면 결과를 저장/캐시해줘.

[마무리]
- 개발 중에는 console.log 로 오류를 확인하고, 프로덕션에서는 삭제해.
- 폼 제출 → 풀이 표시까지 실제로 동작하는지 확인해줘.

토큰 한도는 운세별로 고정 — 고급 운세일수록 큽니다 (플랜과 무관).

호출 1회당 운세 종류에 따라 1~3 크레딧이 차감됩니다 (위 운세 종류 표의 크레딧 차감 참조). 플랜의 포함 크레딧을 쓰고, 초과분만 종량 과금됩니다.

초과 크레딧당 500원 (전 플랜 동일). 플랜은 마이페이지 › 결제에서 변경.

모든 에러 응답 형태: { "success": false, "error": "코드", "message": "설명" }

• Q. 코딩을 전혀 몰라도 되나요?

  빌더로 프롬프트만 만들면 풀이 품질을 확인할 수 있습니다. 실제 서비스 연동(API 호출)에만 약간의 개발이 필요합니다.

• Q. AI 키나 모델을 따로 준비해야 하나요?

  아니요, AI 모델 구독은 이미 SAZU Studio 서비스에 포함되어 있습니다. 프롬프트만 정의하시면 됩니다.

• Q. 키가 여러 개 필요한가요?

  회전·환경 분리·유출 격리를 위해 최대 3개까지. 모두 같은 빌더·크레딧을 공유합니다.

• Q. 풀이에 우리 브랜드 안내를 넣을 수 있나요?

  네. ④ 출력 형식의 직접 지정 칸에 홍보 문구·링크를 자유롭게 넣으면 풀이 끝에 그대로 반영됩니다(화이트라벨).

• Q. 프롬프트를 저장했는데 호출이 안돼요.

  검토 통과 전이면 NO_APPROVED_PROMPT 가 납니다. 마이페이지에서 상태가 approved 인지 확인하세요.

• Q. 오류 발생 시 어떻게 해야 하나요?

  개발 중인 화면에서 브라우저 개발자 도구(F12) → Network 탭 → 붉은색으로 표시된 요청 클릭 → Headers · Response 화면을 캡처해 사용 중인 AI(Cursor·Claude 등)에 보여주고 수정을 요청하세요.

  📋 더 빠른 방법: Response 의 error 코드와 message 를 그대로 AI 에 붙여넣으면 원인을 거의 즉답으로 찾아 줍니다. 코드별 의미는 에러 코드 표를 참고하세요.