개발자 시작 가이드

HRUM(흐름) 사주 API를 처음 연동하는 순서입니다. 가입부터 첫 호출, 과금, 에러 처리까지 이 페이지만 따라 하면 됩니다. 엔드포인트별 전체 파라미터는 API 문서에 있습니다.

가입 전에 결과부터 보고 싶다면 플레이그라운드에서 키 없이 월 5회까지 무료로 시험해 볼 수 있습니다.

콘솔 로그인 화면에서 회원가입 탭을 고르고 이메일과 비밀번호를 입력합니다.
받은 편지함의 "이메일 인증" 메일에서 인증 버튼을 누른 뒤 다시 로그인합니다.
가입하면 무료 크레딧 ₩1,000이 지급됩니다(부정 가입 방지 조건에 걸리면 지급이 보류될 수 있습니다).

2. API 키 발급

콘솔의 API 키 화면에서 키 제목(예: 프로덕션 서버)을 적고 발급을 누릅니다.
새 키는 발급 직후 한 번만 보입니다. 바로 복사해 서버의 환경변수 등 안전한 곳에 보관하세요. 잃어버리면 새로 발급합니다.
키는 서버에서만 쓰세요. 브라우저나 앱 코드에 넣으면 누구나 꺼내 쓸 수 있습니다.

같은 화면의 요청 제한에서 초당·일일 요청 수를 정해 두면 키가 새거나 코드가 무한 반복해도 잔액을 지킬 수 있습니다.

3. 첫 호출 — 만세력

모든 요청은 https://api.hrum.ai/api/v1/partners/v1/ 아래 경로로, 키는 X-Partner-Api-Key 헤더에 담아 보냅니다. 아래는 생년월일시로 사주 원국을 계산하는 만세력 호출입니다.

curl

export HRUM_API_KEY="발급받은 키"

curl -X POST https://api.hrum.ai/api/v1/partners/v1/manseryeok \
  -H "X-Partner-Api-Key: $HRUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":1990,"month":5,"day":15,"hour":12,"minute":0,"timezone":"Asia/Seoul","gender":"male"}'

Python (requests)

import os
import requests

res = requests.post(
    "https://api.hrum.ai/api/v1/partners/v1/manseryeok",
    headers={"X-Partner-Api-Key": os.environ["HRUM_API_KEY"]},
    json={"year": 1990, "month": 5, "day": 15, "hour": 12, "minute": 0,
          "timezone": "Asia/Seoul", "gender": "male"},
    timeout=30,
)
body = res.json()
if not body.get("success"):
    raise RuntimeError(f'{body.get("statusCode")} {body.get("code")}')
print(body["data"]["wonkuk"]["day"])

Python 표준 라이브러리 urllib의 기본 User-Agent는 보안 규칙에 걸려 403이 돌아옵니다. requests를 쓰거나, urllib을 쓴다면 User-Agent: <앱이름>/<버전> 헤더를 직접 넣으세요.

JavaScript (Node 18 이상, 서버에서)

const res = await fetch('https://api.hrum.ai/api/v1/partners/v1/manseryeok', {
  method: 'POST',
  headers: {
    'X-Partner-Api-Key': process.env.HRUM_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ year: 1990, month: 5, day: 15, hour: 12, minute: 0, timezone: 'Asia/Seoul', gender: 'male' }),
});
const body = await res.json();
if (!body.success) throw new Error(`${body.statusCode} ${body.code ?? ''}`);
console.log(body.data.wonkuk.day);

4. 응답 읽기

성공하면 {"success": true, "data": { … }} 형태로 돌아옵니다. 만세력은 data 안에 원국 4주(wonkuk), 오행 분포(ohaengBalance), 용신(yongshin), 격국, 대운·세운 등이 들어 있습니다. 필드 전체 목록은 만세력 API 문서를 보세요.

만세력처럼 같은 입력이면 결과가 같은 계산형 API는 한 번 받은 결과를 DB에 저장해 두고 다시 쓰면 비용이 들지 않습니다.

5. 과금과 크레딧

선불 크레딧에서 호출마다 차감됩니다. 계산형 API는 호출당 정해진 금액, AI 사주 리딩과 LLM은 사용한 토큰만큼 차감됩니다.
표시 금액은 부가세 별도이고, 부가세는 크레딧을 충전할 때 함께 결제합니다.
건별 금액은 콘솔의 사용량 화면에서 확인할 수 있습니다.
잔액이 부족하면 402(INSUFFICIENT_BALANCE)가 돌아옵니다. 콘솔 빌링에서 충전하거나 자동 충전을 켜 두세요.

상품별 단가는 요금표에 있습니다. 주요 계산형 상품 가격(현재 요금표 기준):

계산형 상품 요금표 보기

6. 에러 처리

오류 응답 본문은 {"success": false, "statusCode": 400, "code": "…", "message": "…", "timestamp": "…"} 형식입니다. 분기는 statusCode와 code로 하고, message 문구에는 의존하지 마세요.

코드	뜻	어떻게 처리하나
400	잘못된 요청 파라미터	요청을 고칩니다. 같은 요청을 재시도하지 마세요.
401	API 키가 없거나 유효하지 않음	헤더 이름(`X-Partner-Api-Key`)과 키 값을 확인합니다.
402	크레딧 잔액 부족 (`INSUFFICIENT_BALANCE`)	충전 후 다시 호출합니다.
404	계정에 열리지 않은 기능(`*_not_enabled`) 또는 없는 리소스	과금되지 않습니다. 경로와 기능 사용 여부를 확인합니다.
422	처리할 수 없는 입력 (예: `PROMPT_TOO_LONG`)	입력을 줄이거나 고칩니다.
429	요청 한도 초과	`Retry-After` 헤더가 있으면 그만큼, 없으면 잠시(최대 1분) 기다린 뒤 재시도합니다.
500 · 503 · 504	서버 오류 · 일시적 이용 불가 · 업스트림 시간 초과	간격을 늘려 가며(예: 1초 → 2초 → 4초) 몇 번만 재시도합니다.

서비스 보호를 위해 API 키당 분당 300회 상한이 항상 걸려 있습니다. 자세한 내용은 에러 코드와 Rate Limit 문서를 보세요. 장애 여부는 상태 페이지에서 확인할 수 있습니다.

다음 단계

사주 AI API 소개 — 만세력 말고도 어떤 계산·풀이 API가 있는지
AI 사주 리딩 API — 사주를 계산해 AI가 상담·해석을 써 주는 상품
RIDM Apps 앱 호스팅 — 만든 앱을 GitHub 연결만으로 배포
무료 전자책 — AI 코딩 도구로 사주 앱을 처음부터 만드는 실행형 가이드

문의: [email protected] · 운영: 플로트 주식회사

개발자 시작 가이드

1. 콘솔 가입

2. API 키 발급

3. 첫 호출 — 만세력

curl

Python (requests)

JavaScript (Node 18 이상, 서버에서)

4. 응답 읽기

5. 과금과 크레딧

6. 에러 처리

다음 단계