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

1. 가입 → 브랜드 이름 입력 (예: 우아한 사주운세)
2. 프롬프트 작성 — 마이페이지 › 빌더에서 운세 종류 선택 후 톤·형식 입력
3. 저장 후 검토 — 보안·품질 자동 검토 → approved 되면 호출 가능
4. API 키 발급 — 마이페이지 › API 키 › 새 키 발급
5. 호출 — POST /api/v1/render 로 생년월일 보내면 완성된 풀이 반환

💡 코드를 모르면 1~3 단계만으로도 풀이 품질을 미리 확인할 수 있습니다.

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

빌더는 위에서 아래로 내려오며 라디오를 선택하면 레시피가 완성됩니다. 마지막 변경사항 검토 버튼으로 마무리합니다.

• 사주 데이터 — 생년월일시로 SAZU 엔진이 자동 계산해 풀이에 주입 (입력 불필요)
• ① 운세 종류 · 분석 방법 — 작성할 운세를 고르고, 시스템 기본 분석 또는 직접 지정 선택
• ② 페르소나 — 풀이 어조 9종 중 선택
• ③ 작성 방식 — 화자 역할 · 화법 · 분량 · 독자 호칭 (각 항목 직접 입력 가능 — 예: 호칭을 “고객님”·“○○님”으로)
• ④ 출력 형식 — 형식(줄글·불릿·번호 섹션·표 혼합) · 배치(총평→세부 등) · 직접 지정 문장(홍보 문구·링크)
• ⑤ 변경사항 검토 — 자동 검토 통과 시 approved → API 호출 반영

대부분 라디오 선택만으로 완성됩니다. 더 세밀하게 조정하려면 ①의 직접 지정 이나 ③·④의 직접 입력 칸에 일반인이 이해할 말로 적으면 됩니다 — 실제 사주 계산 결과는 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 (예: today)
• 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 · 선택

응답 (200)

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

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

연동 예제

# Cursor·Claude 등 AI 코딩 도구에 그대로 붙여넣으세요 👇

SAZU Studio API 로 "오늘의 운세"를 받아 화면에 보여주는 기능을 만들어줘.
사용자로 부터 생년월일·시·양/음력·성별을 입력받는 폼을 만들고, 입력 값의 타입검사를 통과하면 아래 API 로 호출해서 결과를 받고 운세 풀이를 표시한다.
개발중에는 console.log 를 사용해서 간단하게 오류를 확인할 수 있도록 해주고, 프로덕션에서는 console.log 를 삭제해.

- 호출은 반드시 내 서버(백엔드)에서 한다. API 키는 브라우저에 노출하지 않는다.
- 엔드포인트: POST https://studio.sazu.app/api/v1/render
- 헤더: X-API-Key: <내 API 키>, Content-Type: application/json
- 본문: { "service": "today",
          "birth": { "birthYear", "birthMonth", "birthDay", "birthHour", "isFemale" } }
- 응답의 data.text 가 완성된 풀이 텍스트다. 그대로 화면 컴포넌트에 보여주되 페이지 스타일을 적용해서 알맞게 보여준다.

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

호출 1회 = 크레딧 차감 (슬림 1 · 스탠다드 2 · 딥 3). 플랜의 포함 크레딧을 쓰고, 초과분만 종량 과금됩니다.

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

모든 에러 응답 형태: { "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 에 붙여넣으면 원인을 거의 즉답으로 찾아 줍니다. 코드별 의미는 에러 코드 표를 참고하세요.