API 문서

이 API 스택이 실제 서비스에서 어떻게 동작하는지 궁금하다면 — 같은 엔진으로 구동되는 AI 사주 앱 인타(INTA)에서 사주 분석·AI 대화를 직접 체험해 보세요. 인타가 이 API의 살아있는 레퍼런스입니다. 인타의 AI 음성 응답(TTS)도 같은 스택으로 구동됩니다 — 음성 API는 추후 공개 예정입니다.

Quickstart

HRUM(흐름)은 기억하는 AI, 사주 분석, LLM 리셀링을 제공합니다. 다음 3단계를 따르세요:

기본 주소는 https://api.hrum.ai(API)·https://console.hrum.ai(콘솔)입니다. 기존 주소 api.float.do·console.float.do·api.inta.do 도 그대로 동작하니 이미 연동했다면 바꾸지 않아도 됩니다.

1. API 키 발급 - 콘솔에 가입한 뒤 API 키 화면에서 발급받습니다(키는 발급 직후 한 번만 보입니다). 가입부터 에러 처리까지의 순서는 개발자 시작 가이드에 정리되어 있습니다.
2. 요청 보내기 - 아래의 예제를 따라 POST 요청을 보냅니다.
3. 응답 처리 - JSON 응답에서 사주 정보를 추출합니다.

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

User-Agent 주의: Python 표준 라이브러리 urllib의 기본 User-Agent(Python-urllib/3.x)는 보안 규칙에 걸려 403 (error 1010)이 반환됩니다. requests, OpenAI SDK, Node, curl은 정상 동작합니다. urllib이나 자체 HTTP 클라이언트를 쓴다면 User-Agent: <앱이름>/<버전> 헤더를 직접 지정하세요. (실측: python-requests 통과 · OpenAI/Python 통과 · node 통과 · Python-urllib 403)

API Reference

HRUM은 기억하는 AI, 사주 분석, LLM 리셀링을 제공합니다.

RIDM Memory API

엔드유저별 대화 기억을 호스팅하면서 ridm/* 모델에 메모리 레이어를 추가합니다. 메모리는 ridm/* 전용이며, OpenAI/Google 모델은 리셀(원본 그대로) — 같은 모델, 다른 상품입니다. 유튜브 자막 자동 주입 기능도 지원합니다.

세션이 없습니다 — 무한 세션. 같은 user로 호출하면 대화는 끝없이 이어집니다. 매 호출마다 서버가 historyCount개의 최근 대화 턴과 recallCount개의 장기 기억(요약·프로필·기억한 사실·진행 중 고민)을 자동으로 붙여 주므로, 파트너는 새 메시지 하나만 보내면 됩니다. 얼마나 멀리까지 참조할지는 두 숫자로 조절하고, 엔드유저별 저장 메시지 수 상한은 memoryCap으로 정합니다. 히스토리를 직접 관리하고 싶으면 historyCount를 생략하고 OpenAI 방식대로 messages에 이전 대화를 실어 보내면 됩니다.

긴 대화도 비용이 선형으로 늘지 않습니다. 오래된 어시스턴트 턴은 자동으로 압축됩니다 — 최신 2턴은 원문 그대로, 그 이전은 500자 → 200자로 단계적으로 줄여 입력 토큰을 아낍니다(사용자 턴은 그대로). 그리고 "저번에 ~라고 했잖아"처럼 과거 발언을 묻는 질문에는 서버가 저장된 실제 대화를 검색해 날짜·화자와 함께 인용합니다(recalledMemories에 포함) — 기록이 없으면 지어내지 않고 없다고 답합니다.

LLM API (리셀) vs RIDM Memory API — 무엇이 다른가

같은 모델, 다른 상품 — 접두사만 다르고 나머지는 동일합니다. 응답에 recalledMemories·memorySaved가 붙으면 RIDM 경로입니다.

코드 예시 비교

// LLM API (리셀) — 메모리 없음
{
  "model": "openai/gpt-5.6-terra",
  "messages": [{ "role": "user", "content": "..." }]
}

// RIDM Memory API — 기억 엔진 포함
{
  "model": "ridm/gpt-5.6-terra",  // 접두사만 다름
  "user": "user_123",              // 필수 (기억 유지)
  "messages": [{ "role": "user", "content": "..." }]
}

// 응답에서 차이
// 리셀: { "id": "...", "choices": [...], "usage": {...}, "costWon": 1, "costUsd": 0.00045 }
// RIDM: { "id": "...", "choices": [...], "usage": {...}, "costWon": 2, "recalledMemories": [...], "memorySaved": { "id": "turn-...", "keywords": [] } }

POST /api/v1/partners/v1/chat/completions

메모리를 지닌 대화형 LLM 호출. 같은 user/endUserId로 호출하면 과거 맥락이 유지됩니다.

요청 파라미터

요청 예시

curl -X POST https://api.hrum.ai/api/v1/partners/v1/chat/completions \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ridm/gpt-5.6-terra",
    "user": "member-1024",
    "messages": [
      { "role": "user", "content": "지난번에 말한 이직 고민, 이어서 얘기해도 될까?" }
    ]
  }'

응답 예시

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1629292800,
  "model": "ridm/gpt-5.6-terra",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "안녕하세요! 이전 대화를 기억하고 있습니다..."
      },
      "finish_reason": "stop",
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 1250,
    "completion_tokens": 320,
    "prompt_tokens_details": { "cached_tokens": 0 }
  },
  "costWon": 45,
  "recalledMemories": [...],
  "memorySaved": { "id": "turn-1756200000000", "keywords": [] },
  "youtubeUsed": ["abc123def45"]
}

usage에는 total_tokens가 없습니다 — prompt_tokens, completion_tokens, prompt_tokens_details.cached_tokens, 그리고 추론 모델이면 completion_tokens_details.reasoning_tokens(이미 completion_tokens에 포함)가 옵니다. memorySaved는 저장된 턴 정보 객체 또는 null(상한 초과·도구 호출 턴), youtubeUsed는 자막을 주입한 영상 ID 배열입니다(URL 아님).

스트리밍(SSE) 형식

stream: true이면 OpenAI chunk 형식이 아니라 이름 있는 SSE 이벤트로 응답합니다. 따라서 OpenAI SDK의 스트림 파서로는 읽을 수 없습니다 — SSE를 직접 파싱하세요 (비스트리밍 응답은 OpenAI 호환).

event: chunk
data: {"delta":"안녕하세요"}

event: message_done
data: {"finish_reason":"stop","usage":{"prompt_tokens":1250,"completion_tokens":320,"prompt_tokens_details":{"cached_tokens":0}},"costWon":45,"recalledMemories":[],"memorySaved":{"id":"turn-1756200000000","keywords":[]}}

data: [DONE]

에러 코드

공통 에러 외에 이 API에서 나오는 코드입니다. stream: true에서 응답이 시작된 뒤 난 오류는 event: error({message, code, status})로 옵니다. 리셀 모델도 같은 표를 따릅니다.

주의사항

• 유튜브 자막 주입: youtube:true일 때, 마지막 메시지의 유튜브 링크에서 자막을 추출해 입력 토큰에 포함합니다. 자막을 못 얻으면 주입 없이 대화가 그대로 진행되며 응답의 youtubeUsed가 빈 배열로 옵니다 (단독 유튜브 요약 API만 400 무과금).
• 원본 모델 호환: model 값에 openai/* 또는 google/*, anthropic/*를 지정하면 원본 모델이 메모리 기능 없이 그대로 호출됩니다 (원가 × 환율 × 1.10).
• 프롬프트 캐시 할인: OpenAI 계열 모델(openai/*, ridm/gpt-*)은 같은 앞부분(1,024토큰 이상)을 반복해 보내면 업스트림 캐시에 맞은 입력 토큰을 입력가의 30%로 과금합니다. 응답 usage.prompt_tokens_details.cached_tokens와 GET /usage/logs의 cachedTokens로 확인할 수 있고, 캐시 적중 여부는 업스트림 정책에 따라 호출마다 달라질 수 있습니다. Google 모델은 캐시가 없어 전체 입력가가 적용됩니다. Claude 모델도 캐시를 요청하지 않으므로 전체 입력가가 적용됩니다.
• REPORT_ONLY_MODEL 제외: ridm/saju-report는 메모리 없는 원샷 전용이라 이 엔드포인트에서 사용 불가 (400).

커스텀 프로필 (Custom Profile)

ridm/* 모델 전용. 엔드유저별 임의의 필드명-값을 저장하고 관리합니다. 자동으로 추출한 필드 값들을 저장하거나, 파트너가 직접 값을 지정하거나, 이번 턴 프롬프트에 특정 필드를 포함시킬 수 있습니다. 값은 누적되며, 스키마가 바뀌어도 기존 값은 보존됩니다(soft-update).

요청 파라미터 (POST /api/v1/partners/v1/chat/completions)

요청 예시 (RIDM chat)

{
  "model": "ridm/gpt-5.6-terra",
  "user": "enduser_123",
  "messages": [
    { "role": "user", "content": "내일 아이 생일 파티 계획 도와줘" }
  ],
  "extractProfileFields": ["childAge", "interests", "budget", "constraints"],
  "injectProfileFields": ["name", "childAge", "interests"],
  "endUserProfile": {
    "name": "김철수",
    "childAge": "7",
    "interests": "과학·미술"
  },
  "profileValueMaxChars": 200
}

응답에서의 프로필

프로필 파라미터를 보낸 요청의 응답(스트리밍은 message_done)에는 customProfile 필드가 붙습니다.

"customProfile": {
  "injected": ["name", "childAge", "interests"],  // 이번 턴 프롬프트에 주입된 필드
  "stored": 4,                                     // 현재 저장된 필드 수
  "extractPending": ["budget"]                     // 추출 대상이지만 아직 값이 없는 필드
}

삭제 API

특정 필드를 삭제하려면 DELETE 요청을 보냅니다:

DELETE /api/v1/partners/v1/profile/{endUserId}/field/{key}
X-Partner-Api-Key: your-api-key

응답: { "success": true, "data": { "deleted": true } } — 없는 키나 처음 보는 endUserId여도 200에 "deleted": false입니다 (엔드유저를 새로 만들지 않습니다). 이 API만의 에러 코드는 없습니다 — 공통 에러만 나옵니다.

상한 및 제약

• 필드 상한: 엔드유저당 최대 100개 필드. 초과 시 가장 오래된 필드부터 제거됩니다.
• 값 길이: 필드당 기본 150자, 최대 500자. profileValueMaxChars로 조정 가능합니다.
• 누적 저장: extractProfileFields로 추출한 값은 누적되며, 비어 있거나 null인 값은 건너뛰고 기존 값을 유지합니다. 필드 삭제는 위 DELETE API(또는 100개 초과 시 오래된 순 자동 제거)로만 됩니다. endUserProfile로 지정한 값은 추출값을 덮어씁니다.
• 값 길이 기준은 요청 단위: profileValueMaxChars는 저장되지 않고 그 요청에서 저장되는 값에만 적용됩니다.
• Soft Update: 스키마(필드명)가 바뀌어도 기존 값은 보존되며, 매 호출마다 새로운 값과 합쳐집니다.
• ridm/* 전용: 리셀(openai/*, google/*)은 프로필을 무시합니다.

LLM API (리셀)

openai/*, google/* 등 원본 LLM 모델을 리셀(메모리 없이 원본 응답 그대로). 리셀 모델 요청의 user, systemPrompt, recallCount, memoryCap, summaryEvery, emotion, candor는 무시되며(시스템 지시는 messages에 {"role":"system"}으로), 응답에 메모리 필드(recalledMemories 등)가 없습니다. 가격 = 원가 × 환율 × 1.10.

제공 모델 (GET /api/v1/partners/v1/models와 같은 목록)

• OpenAI (23종): openai/gpt-6-astra · openai/gpt-6-sol · openai/gpt-6-luna · openai/gpt-5.6-sol · openai/gpt-5.6-terra · openai/gpt-5.6-luna · openai/gpt-5.5 · openai/gpt-5.4 · openai/gpt-5.4-mini · openai/gpt-5.4-nano · openai/gpt-5.2 · openai/gpt-5.1 · openai/gpt-5 · openai/gpt-5-mini · openai/gpt-5-nano · openai/gpt-4.1 · openai/gpt-4.1-mini · openai/gpt-4.1-nano · openai/gpt-4o · openai/gpt-4o-mini · openai/o3 · openai/o3-mini · openai/o4-mini
• Google (3종): google/gemini-3.5-flash · google/gemini-3.5-flash-lite · google/gemini-3.1-pro
• Anthropic (13종): 아래 Claude 모델 항목 참고
• RIDM: 위 모델마다 같은 이름에 ridm/ 접두사를 붙인 기억형 모델(리셀가 × 1.3)과, 사주 리포트 전용 ridm/saju-report(/reading/report로만 호출)가 있습니다.

curl https://api.hrum.ai/api/v1/partners/v1/models \
  -H "X-Partner-Api-Key: your-api-key"

GET /api/v1/partners/v1/models 응답 — OpenAI models.list 형식이 아닙니다. 가격은 1M 토큰당 원(₩)이며 아래 숫자는 예시입니다. Claude 모델은 서버에 설정된 경우에만 목록에 나옵니다.

{
  "success": true,
  "data": {
    "models": [
      { "modelId": "openai/gpt-5.6-terra", "upstream": "gpt-5.6-terra", "provider": "openai", "input_cost_krw": 1234, "output_cost_krw": 9876, "category": "base" },
      { "modelId": "ridm/gpt-5.6-terra", "upstream": "gpt-5.6-terra", "provider": "openai", "input_cost_krw": 1604.2, "output_cost_krw": 12838.8, "category": "ridm" }
    ]
  }
}

이 API만의 에러 코드는 없습니다 — 공통 에러만 나옵니다. 무료입니다.

사고(추론) 모델과 max_tokens: 숨은 사고(thinking/reasoning)를 쓰는 모델은 사고 토큰이 출력 상한에 포함됩니다. 서버가 여유분을 더해 호출하지만 max_tokens가 매우 작으면(예: 16) 본문이 비어 있고 finish_reason: "length"로 응답할 수 있으며, 상류에서 소모된 토큰은 과금됩니다. 권장 최소값은 64 이상입니다. 해당 모델: openai/gpt-5 · openai/gpt-5-mini · openai/gpt-5-nano · openai/gpt-6-astra · openai/o3 · openai/o3-mini · openai/o4-mini · anthropic/claude-opus-5 · anthropic/claude-opus-5-5 · anthropic/claude-fable-5 · anthropic/claude-fable-5-1 · google/gemini-3.1-pro (ridm/ 접두사 동명 모델 포함).

사고용 여유분과 청구 토큰: 사고를 끌 수 없는 모델(openai/gpt-5 · openai/gpt-5-mini · openai/gpt-5-nano · openai/gpt-6-astra · openai/o3 · openai/o3-mini · openai/o4-mini · google/gemini-3.1-pro)과 thinking이 항상 켜진 모델(anthropic/claude-opus-5 · anthropic/claude-opus-5-5 · anthropic/claude-fable-5 · anthropic/claude-fable-5-1)은 (ridm/ 접두사 동명 모델 포함) 답변을 보장하기 위해 요청한 max_tokens 위에 서버가 사고용 여유분(최대 1,500토큰)을 더해 호출합니다. 사고 토큰도 출력 단가로 청구되므로 실제 청구되는 출력 토큰이 max_tokens보다 클 수 있습니다(예: max_tokens 200 요청에 사고 747 + 본문 81 = 828토큰 청구). 비용 상한을 엄격히 묶어야 하면 google/gemini-3.5-flash처럼 사고가 꺼지는 모델을 쓰세요.

POST /api/v1/partners/v1/chat/completions

요청 파라미터 (메모리 레이어 없음)

사용 예시 (OpenAI SDK 호환)

const client = new OpenAI({
  apiKey: 'your-float-api-key',
  baseURL: 'https://api.hrum.ai/api/v1/partners/v1',
  defaultHeaders: { 'X-Partner-Api-Key': 'your-float-api-key' }
});

const response = await client.chat.completions.create({
  model: 'openai/gpt-5.6-terra',
  messages: [{ role: 'user', content: 'Hello' }]
});
// RIDM 모델 예: model: 'ridm/gpt-5.6-terra'

응답

비스트리밍 응답은 OpenAI 호환 스키마에 costUsd·costWon·requestId가 더해집니다. stream: true는 OpenAI chunk 형식이 아니므로 OpenAI SDK의 스트림 파서로 읽을 수 없습니다 — 스트리밍(SSE) 형식을 참고해 직접 파싱하세요.

{
  "id": "chatcmpl-1791452814000",
  "object": "chat.completion",
  "created": 1791452814,
  "model": "openai/gpt-5.6-terra",
  "usage": { "prompt_tokens": 9, "completion_tokens": 12, "prompt_tokens_details": { "cached_tokens": 0 } },
  "choices": [
    { "index": 0, "message": { "role": "assistant", "content": "Hello! How can I help?" }, "finish_reason": "stop" }
  ],
  "costUsd": 0.000162,
  "costWon": 1,
  "requestId": "resale-..."
}

에러 코드는 RIDM Memory API의 에러 표와 같습니다. 리셀 모델에는 일일 지출 상한(RATE_LIMITED)이 함께 걸립니다.

AI 사주 리딩 API

생성형 AI가 사주를 분석해 맞춤형 운세 해석과 조언을 제공합니다. 토큰 기반 과금이며, 해석 결과만 반환합니다.

POST /api/v1/partners/v1/reading

사주를 기반으로 AI 사주 리딩을 생성합니다. 내부 프롬프트와 이론은 비공개입니다.

요청 파라미터

요청 파라미터 — tools 옵션

요청 예시

curl -X POST https://api.hrum.ai/api/v1/partners/v1/reading \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "올해 이직해도 괜찮을까요?",
    "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "female" },
    "maxLength": 600,
    "tone": "warm"
  }'

응답 예시

{
  "success": true,
  "data": {
    "interpretation": "당신의 사주에서 보이는 특징은...",
    "sajuSource": "computed",
    "usage": {
      "inputTokens": 450,
      "outputTokens": 280
    },
    "costPoints": 18
  }
}

응답 필드

에러 코드

공통 에러 외에 이 API에서 나오는 코드:

포함 항목 — 자미두수 · 점성술 · 꿈해몽 · 타로

사주 AI 안에 사주·자미두수·점성술·타로·꿈해몽 AI가 다 들어 있습니다. 오늘 일진은 따로 부르지 않아도 모든 풀이에 기본으로 반영됩니다(추가 요금 없음). 통합으로 한 번 부르면 포함된 항목의 계산 결과를 근거로 함께 풀이하고, 빼고 싶은 항목은 exclude로 뺍니다. 필요한 AI 하나만 부르려면 only를 씁니다. 계산 결과만 필요하면 같은 항목을 계산형 엔드포인트(/ziwei-chart · /astrology(점성술 토탈) · /dream · /tarot)로 하나씩 따로 불러 직접 앱을 만들 수도 있습니다. /reading/memory에서도 같은 필드로 씁니다.

• 과금: 기존 토큰 가격(질문 + persona + 포함 항목 근거 블록 글자수 × 0.25 입력 토큰, 출력 토큰)에 포함된 항목마다 그 항목의 단독 엔드포인트 1회 가격을 더합니다. 근거 블록은 항목마다 1,500자 안쪽의 요약입니다. 해당 기능이 계정에서 꺼져 있거나 가격이 없는 항목은 포함되지 않습니다. 항목별 요금과 예상 1회 범위는 요금에 있습니다.
• 4기둥(saju)만 보낸 요청에는 생년월일이 없으므로 자미두수·점성술이 포함되지 않습니다(꿈해몽·타로는 포함됩니다).
• tools.astrology와의 관계: 점성술 항목이 포함되면 같은 네이탈 차트를 두 번 넣지 않도록 tools.astrology의 차트 주입은 건너뜁니다. 점성술 항목이 빠지면(exclude 또는 기능 꺼짐) tools.astrology는 지금처럼 동작합니다.
• 꿈해몽 안전장치: dream 내용이 위기 표현이면 AI를 부르지 않고 도움 안내(support)를 costPoints: 0으로 돌려줍니다.
• 기능 스위치: 지금 켜져 있습니다. 서버 설정이 꺼지면 exclude·dream·tarot을 보내도 무시되고, 풀이·가격·응답이 포함 항목이 없던 때와 같아집니다(modulesUsed·moduleFees·tarot 없음).

요청 예시 (POST /api/v1/partners/v1/reading)

{
  "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "gender": "female" },
  "question": "어젯밤 꿈이 계속 마음에 걸려요. 요즘 저한테 무슨 뜻일까요?",
  "dream": "큰 뱀이 집 안으로 들어와 내 발 옆에 똬리를 틀었어요",
  "tarot": { "spread": "past-present-future" }
}

응답 예시

{
  "success": true,
  "data": {
    "interpretation": "뱀이 집 안으로 들어와 곁에 머무는 꿈은...",
    "sajuSource": "computed",
    "modulesUsed": ["saju", "dream", "ziwei", "astro", "tarot"],
    "moduleFees": { "dream": 30, "ziwei": 50, "astro": 20, "tarot": 20 },
    "tarot": {
      "lang": "ko",
      "count": 3,
      "spread": { "type": "past-present-future", "name": "과거·현재·미래", "description": "시간 흐름을 따라가는 질문", "positions": ["과거", "현재", "미래"] },
      "reversedAllowed": true,
      "seed": null,
      "cards": [
        { "position": 1, "positionLabel": "과거", "id": "wands_10", "name": "완드의 10", "nameEn": "Ten of Wands", "arcana": "wands", "reversed": true, "keywords": ["내려놓기", "위임", "해방"], "meaning": "무거운 짐을 마침내 내려놓거나 도움을 받기 시작하는 시기.", "imageUrl": "https://console.hrum.ai/tarot/cards/v2/wands_10.webp" }
      ],
      "cardBackUrl": "https://console.hrum.ai/tarot/cards/v2/back.webp"
    },
    "usage": {
      "inputTokens": 3140,
      "outputTokens": 760
    },
    "costPoints": 162
  }
}

사주만 (다른 항목 모두 빼기) (POST /api/v1/partners/v1/reading)

{
  "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "gender": "female" },
  "question": "올해 이직해도 괜찮을까요?",
  "exclude": ["ziwei", "astro"]
}

AI 하나만 따로 — only

사주 AI 안에 사주·자미두수·점성술·타로·꿈해몽 AI가 다 들어 있습니다. 위처럼 통합으로 한 번에 부르는 대신, 필요한 AI 하나만 only로 따로 부를 수 있습니다. 그 AI는 자기 근거(명반·차트·뽑힌 카드·해몽 후보)만 보고 답하며, 다른 항목은 넣지 않습니다.

• 과금: 토큰 가격(질문 + persona + 그 AI의 근거 블록 하나만, 글자수 × 0.25 입력 토큰, 출력 토큰) + 그 항목 고정 요금 1개. 도메인별 예상 1회 가격은 요금에 있습니다.
• exclude와 함께 쓸 수 없습니다: 둘 다 보내면 400 ONLY_WITH_EXCLUDE. 그 AI에 필요한 입력이 없으면 400 ONLY_REQUIRES_INPUT, 계정에서 그 기능이 꺼져 있으면 400 ONLY_DOMAIN_UNAVAILABLE — 사주 풀이로 대신 답하지 않습니다. 명반·차트를 계산할 수 없는 날짜면 400 ONLY_INPUT_INVALID.
• tarot·dream은 생년월일이 필요 없습니다. birth·saju 없이 질문과 카드(또는 꿈 내용)만 보내면 됩니다. saju가 아닌 only는 사주를 쓰지 않으므로 응답에 sajuSource가 없습니다.
• 기능 스위치: 포함 항목과 같은 서버 설정을 따르며 지금 켜져 있습니다. 설정이 꺼지면 only는 무시되고 기존 사주 리딩과 같게 동작합니다.

요청 예시 — 타로 AI만 (POST /api/v1/partners/v1/reading)

{
  "question": "지금 준비 중인 이직, 이대로 밀고 나가도 될까요?",
  "only": "tarot",
  "tarot": { "spread": "past-present-future" }
}

응답 예시

{
  "success": true,
  "data": {
    "interpretation": "과거 자리의 완드의 10 역방향은 오래 짊어진 짐을...",
    "only": "tarot",
    "modulesUsed": ["tarot"],
    "moduleFees": { "tarot": 20 },
    "tarot": {
      "lang": "ko",
      "count": 3,
      "spread": { "type": "past-present-future", "name": "과거·현재·미래", "description": "시간 흐름을 따라가는 질문", "positions": ["과거", "현재", "미래"] },
      "reversedAllowed": true,
      "seed": null,
      "cards": [
        { "position": 1, "positionLabel": "과거", "id": "wands_10", "name": "완드의 10", "nameEn": "Ten of Wands", "arcana": "wands", "reversed": true, "keywords": ["내려놓기", "위임", "해방"], "meaning": "무거운 짐을 마침내 내려놓거나 도움을 받기 시작하는 시기.", "imageUrl": "https://console.hrum.ai/tarot/cards/v2/wands_10.webp" }
      ],
      "cardBackUrl": "https://console.hrum.ai/tarot/cards/v2/back.webp"
    },
    "usage": {
      "inputTokens": 1180,
      "outputTokens": 720
    },
    "costPoints": 37
  }
}

주의사항

• 해석 결과만 반환됨: 응답에는 생성된 운세 해석 텍스트만 포함되며, 내부 프롬프트나 사주 이론은 노출되지 않습니다.
• candorApplied: candor를 t로 보낸 경우에만 응답에 실제 적용된 말결(t | f)이 붙습니다. /reading/memory도 같습니다 (말결 (가칭)).
• 과금 기준: 입력 = (question + persona 글자수) × 0.25 토큰(+ /reading에서 주입된 유튜브 자막 글자수 × 0.25), 출력 = 실제 completion 토큰. 사주 주입·시스템 프롬프트는 과금하지 않으며, usage.inputTokens는 참고용입니다. 포함 항목(오늘의 운세 · 자미두수 · 점성술 · 꿈해몽 · 타로)이 켜지면 그 근거 블록과 항목별 고정 요금이 더해집니다. costPoints가 실제 차감액입니다.
• 응답 언어: 한국어가 아닌 질문에는 질문과 같은 언어로 답합니다.
• 출생시간 미상: hour 생략 시 시주를 빼고 년·월·일 3주 기준으로 해석합니다.

AI 사주 리딩 · 메모리 API

엔드유저별 대화 기억을 호스팅하고, 재방문 시 과거 맥락을 이어서 풀이합니다. 개인화된 지속적 상담 경험을 제공합니다. 가격은 AI 사주 리딩 토큰 단가의 1.3배입니다 (1M 토큰당 입력 3,754원 · 출력 30,030원 — 리딩은 입력 2,888원 · 출력 23,100원, 부가세 별도).

POST /api/v1/partners/v1/reading/memory

엔드유저별 기억을 바탕으로 AI 사주 리딩을 생성합니다.

요청 파라미터

요청 파라미터 — tools 옵션

응답 예시

{
  "success": true,
  "data": {
    "interpretation": "당신의 사주에서 보이는 특징은...",
    "sajuSource": "computed",
    "memory": {
      "used": true,
      "summaryInjected": false,
      "notesInjected": 2,
      "tags": ["직장"],
      "overheadTokens": 120
    },
    "usage": {
      "inputTokens": 750,
      "outputTokens": 380
    },
    "costPoints": 36,
    "toolsUsed": ["memory"]
  }
}

그 밖의 응답 필드(sajuMismatch, toolsSkipped, filesUsed)는 AI 사주 리딩 API와 같고, 자동 회상된 문서는 filesRecalled, tools.emotion: true이면 emotion이 붙습니다. 과금 기준(유튜브 제외)도 리딩 API와 같습니다.

요청 예시

curl -X POST https://api.hrum.ai/api/v1/partners/v1/reading/memory \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "endUserId": "member-1024",
    "question": "지난번에 얘기한 이직 건, 다음 달에 움직여도 될까요?",
    "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "female" }
  }'

에러 코드

공통 에러(401·400 본문 검사·402·429·503 등) 외에 이 API에서 나오는 코드:

메모리 관리 API

AI 사주 리딩 메모리형(POST /reading/memory)과 RIDM 채팅(ridm/* 모델의 user)은 같은 엔드유저 기억 저장소를 씁니다. 아래 경로의 {endUserId} 는 그때 보낸 값 그대로입니다(예: 채팅을 세션 단위로 나눴다면 회원id:대화id 같은 키 전체).

요청·응답 예시

# 저장된 메모리 조회
curl https://api.hrum.ai/api/v1/partners/v1/memory/member-1024 \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "endUserId": "member-1024",
    "summary": "이직을 고민 중이며 다음 달 면접을 앞두고 있다...",
    "metaSummary": "...",
    "tags": ["이직", "면접"],
    "profile": null,
    "concerns": ["..."],
    "facts": []
  }
}

# 메시지 목록 (오래된 순)
curl "https://api.hrum.ai/api/v1/partners/v1/memory/member-1024/messages?limit=2&offset=0" \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "endUserId": "member-1024",
    "messages": [
      { "id": "...", "role": "user", "content": "이직 고민이 있어요", "tags": ["이직"], "createdAt": "2026-10-11T09:00:00.000Z" },
      { "id": "...", "role": "assistant", "content": "...", "tags": [], "createdAt": "2026-10-11T09:00:04.000Z" }
    ],
    "offset": 0,
    "limit": 2,
    "total": 18
  }
}

# 태그 검색
curl "https://api.hrum.ai/api/v1/partners/v1/memory/search?endUserId=member-1024&tags=이직,면접" \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "endUserId": "member-1024",
    "query": { "tags": ["이직", "면접"] },
    "results": [
      { "id": "...", "summary": "다음 달 면접 일정을 이야기함", "level": 0, "tags": ["면접"], "createdAt": "2026-10-11T09:00:00.000Z" }
    ]
  }
}

# 전부 삭제 (메모리 + 업로드 파일) — 204, 본문 없음
curl -X DELETE https://api.hrum.ai/api/v1/partners/v1/memory/member-1024 \
  -H "X-Partner-Api-Key: your-api-key"

에러 코드

공통 에러(401·400 본문 검사·402·429·503 등) 외에 이 API에서 나오는 코드:

주의사항

• 1.3배 단가: 메모리 호스팅으로 인해 입력/출력 토큰 단가가 AI 사주 리딩의 1.3배입니다 (1M 토큰당 입력 3,754원 · 출력 30,030원, 부가세 별도).
• endUserId 필수: 각 엔드유저는 고유한 ID를 가져야 하며, 같은 ID로 호출 시 과거 맥락이 유지됩니다.
• 메모리 보관: 저장된 메모리는 명시적 삭제 시까지 보관됩니다.

사주 리포트 API

질문 없이 버튼 한 번으로 총평·재물·연애·대운까지 모든 사주 해석이 한 번에 나옵니다. 대화형(reading)과 별개의 단품 결제형 상품. 전용 모델 ridm/saju-report(RIDM 자체 리포트 특화 모델 — 원샷 상품 특성상 메모리 미장착)가 기본입니다. 리딩 API의 응답 상한은 2,000자입니다 — 그 이상의 장문 해설(최대 12섹션, 약 6,000자)은 이 리포트 API를 사용하세요.

POST /api/v1/partners/v1/reading/report

생년월일(또는 사주)을 넣으면 섹션별 마크다운 사주 리포트를 반환합니다.

요청 파라미터

리포트는 항상 한국어로 작성됩니다. speed·tools·lang·question 등 위 표에 없는 필드를 보내면 400으로 거절됩니다.

요청 예시

curl -X POST https://api.hrum.ai/api/v1/partners/v1/reading/report \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "female" },
    "sections": ["총평", "재물운", "연애·인연"]
  }'

응답

{
  "success": true,
  "data": {
    "report": "## 총평\n...",        // 섹션별 마크다운 전문
    "sections": ["총평", "..."],
    "sajuSource": "computed",
    "usage": { "inputTokens": 5756, "outputTokens": 2019 },
    "costPoints": 77,
    "model": "ridm/saju-report"
    // "candorApplied": "t"  — candor를 t로 보낸 경우에만 (t | f)
  }
}

• 사주 주입 무료: 만세력 계산·주입과 시스템 프롬프트는 과금하지 않습니다. 입력 과금은 persona 길이만, 출력은 실사용 토큰입니다.
• 실측 비용: 기본 8섹션(약 3,000자) 리포트 1회 약 85P (출력 ₩38,077/1M 기준).
• 재시도는 다시 과금됩니다. 응답을 받은 뒤 같은 입력을 재사용하려면 클라이언트에서 저장하세요 (멱등성).

에러 코드

공통 에러(401·400 본문 검사·402·429·503 등) 외에 이 API에서 나오는 코드:

유튜브 요약 API

유튜브 동영상의 자막을 추출하여 요약 및 Q&A 분석을 제공합니다. 자막이 없는 경우 400 에러(무과금).

POST /api/v1/partners/v1/youtube/summary

요청 파라미터

요청 예시

curl -X POST https://api.hrum.ai/api/v1/partners/v1/youtube/summary \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "maxLength": 1000 }'

응답 예시

{
  "success": true,
  "data": {
    "summary": "## 0:00~1:30 오프닝\n영상 제목 설명...\n\n## 1:30~5:00 본론\n...",
    "video": {
      "videoId": "dQw4w9WgXcQ",
      "title": "Video Title",
      "channel": "Channel Name"
    },
    "transcriptSource": "supadata",
    "usage": {
      "promptTokens": 7059,
      "completionTokens": 1384
    },
    "costPoints": 78,
    "model": "ridm/gpt-5.6-terra"
  }
}

주의사항

• 자막 필수: 자막이 없으면 TRANSCRIPT_UNAVAILABLE 400 (무과금).
• 에러: 잘못된 URL·ID 400 INVALID_YOUTUBE_URL / 요약 생성 실패 400 LLM_GENERATION_FAILED / 잔액 부족 402 INSUFFICIENT_BALANCE.
• 실측 비용: 20~30분 영상 1회 약 80P (토큰 포함).
• 리딩 연동: AI 사주 리딩 API(/reading)에서 tools: { "youtube": true }로 질문 속 링크의 자막을 주입할 수 있습니다 (최상위 youtube 필드는 무시). 유튜브 주입은 /reading에서만 지원(/reading/memory는 아직 미지원).

에러 코드

공통 에러(401·400 본문 검사·402·429·503 등) 외에 이 API에서 나오는 코드:

기능 켜고 끄기

유튜브 요약 API는 파트너 계정 및 요청 단위로 옵트인할 수 있습니다. 콘솔의 "기능 설정"에서 전역 활성화 상태를 관리하며, chat은 최상위 youtube:true, reading은 tools: { "youtube": true }를 명시해 요청별로 활성화합니다.

• 전역 비활성: 403 { code: 'FEATURE_DISABLED', feature: 'youtube' } 응답
• 요청 단위: youtube:true 미지정 또는 false = 유튜브 주입 안 함

문서 처리 API

PDF, Word(.docx), Excel(.xlsx), PowerPoint(.pptx), CSV, 텍스트, Markdown, 한글(.hwpx) 문서를 업로드하고, AI로 분석하여 맥락 기반 지식베이스에 적재할 수 있습니다. 문서는 자동 추출되며, "AI 분석" 옵션을 활성화하면 문서를 맥락 단위로 분할하고 각 구간의 요약과 검색 태그를 생성하여 저장합니다.

지원 형식 및 제한

엔드포인트

파일 업로드

POST /api/v1/partners/v1/files

Multipart form 형식으로 파일을 업로드합니다.

요청 필드

cURL 예시

curl -X POST https://api.hrum.ai/api/v1/partners/v1/files \
  -H "X-Partner-Api-Key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "endUserId=user_123" \
  -F "analyze=true"

응답 예시

{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "sample.pdf",
    "originalName": "sample.pdf",
    "mime": "application/pdf",
    "size": 125000,
    "textLength": 8942,
    "charsCapped": false,
    "textPreview": "1장. 개요 ...",
    "summary": "문서 전체 요약...",
    "context": "문서 전체 요약...",
    "status": "analyzed",
    "analysisStatus": "analyzed",
    "analyzeRequested": true,
    "endUserId": "user_123",
    "usage": { "inputTokens": 3100, "outputTokens": 420, "costWon": 1 },
    "totalChunks": 3,
    "createdAt": "2026-08-26T12:34:56Z"
  }
}

목록·상세·삭제

# 목록 — 최신순, limit 1~100 (기본 20)
curl "https://api.hrum.ai/api/v1/partners/v1/files?endUserId=user_123&limit=20&offset=0" \
  -H "X-Partner-Api-Key: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "files": [ { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "sample.pdf", "status": "analyzed", ... } ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

# 상세 — 업로드 응답 필드 + extractedText + chunks
curl https://api.hrum.ai/api/v1/partners/v1/files/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-Partner-Api-Key: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "sample.pdf",
    ...,
    "extractedText": "1장. 개요 ...",
    "chunks": [
      { "id": "...", "chunkIndex": 0, "context": "1장 요약...", "tags": ["개요"], "textLength": 2980 }
    ]
  }
}

# 삭제
curl -X DELETE https://api.hrum.ai/api/v1/partners/v1/files/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-Partner-Api-Key: YOUR_API_KEY"

{ "success": true, "data": { "deleted": true } }

Chat 및 리딩 연동

명시적 첨부: Chat completions 또는 AI 리딩 요청 시 fileIds 파라미터로 최대 5개의 문서를 주입할 수 있습니다. 분석된 파일은 문서 요약(최대 500자)과 원문 텍스트를, 미분석 파일은 원문 텍스트를 주입합니다(원문은 파일당 40,000자 / 전체 80,000자 제한, 자식 청크는 주입하지 않음). 주입된 문서는 마지막 사용자 메시지에 추가되어 입력 토큰에 포함됩니다. 리셀 모델은 fileIds 명시 주입만 지원합니다.

자동 회상 (ridm/* 전용): ridm/* chat 및 reading-memory 모델에서는 사용자 질문의 태그와 겹치는 분석된 파일을 자동으로 검색해 주입합니다(명시적 fileIds 미지정 시에만). 응답에 filesRecalled 배열로 회상된 파일 ID를 표시합니다.

Chat 요청 예시

{
  "model": "ridm/gpt-5.6-terra",
  "messages": [
    { "role": "user", "content": "이 문서에서 주요 내용을 요약해줄 수 있나요?" }
  ],
  "fileIds": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"],
  "user": "user_123"
}

응답 예시

{
  "id": "chatcmpl-abc123",
  "choices": [{
    "message": { "content": "문서의 주요 내용은..." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 2500, "completion_tokens": 150 },
  "filesUsed": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]
}

filesRecalled는 자동 회상된 파일이 있을 때만 붙습니다(비어 있으면 생략).

요금 및 과금

• 업로드 및 추출: 무료 (텍스트 추출 토큰 미과금)
• AI 분석 (analyze=true): 경계 탐지 + 구간별 요약 + 전체 요약의 실제 토큰 사용량을 분석 모델 단가로 과금. 동기 ≤30,000자, 비동기 >30,000자 (status: analyzing)
• Chat 주입: 문서 텍스트가 입력 토큰으로 계산되어 일반 chat 요청과 동일하게 과금
• 로그: 콘솔의 사용 로그에서 file_upload (무료), file_analyze (유료, 실사용 토큰) 분류로 확인 가능

기능 켜고 끄기

문서 처리 기능은 파트너 계정 수준에서 활성화/비활성화할 수 있습니다. 콘솔의 "기능 설정"에서 관리하며, 비활성 시 모든 파일 요청에 대해 403 응답이 반환됩니다.

• 전역 비활성: 403 { code: 'FEATURE_DISABLED', feature: 'files' } 응답
• 요청 단위: fileIds 미지정 = 문서 주입 없음 (정상 처리)

분석 상태 및 청크

GET /api/v1/partners/v1/files/:id 응답에는 analysisStatus, extractedText, chunks가 포함됩니다. chunks는 분석 완료이고 totalChunks가 2 이상일 때만 배열(각 청크: chunkIndex, context(요약), tags 최대 10개)이며, 그 외에는 null입니다. 업로드 응답에는 chunks가 없습니다.

주의사항

• 형식 검증: 지원하지 않는 형식은 400 { code: 'INVALID_FILE_TYPE' } 반환
• 기타 에러: 파일 누락 400 FILE_NOT_PROVIDED / 10MB 초과 400 FILE_TOO_LARGE / 없는 파일 404 FILE_NOT_FOUND / :id가 UUID가 아니면 400
• 분석 필수: analyze=true일 때 endUserId가 없으면 400 { code: 'END_USER_REQUIRED' } 반환
• 추출 실패: 문서 추출 중 오류 시 422 { code: 'EXTRACTION_FAILED' } 반환
• 잔액 확인: 분석 요청 전 파트너 크레딧 충분성 검사. 부족하면 402 반환
• 지식베이스 자동 적재: analyze=true인 경우, 각 구간의 요약과 태그가 지식베이스에 자동 저장되어 이후 auto-recall 대상이 됩니다. endUserId 지정 시 해당 유저의 기억 계층에도 추가됩니다.
• 재업로드 = 새 파일: 업로드할 때마다 새 파일(새 id)이 만들어지고 analyze=true면 다시 분석·과금됩니다. 같은 문서는 한 번만 업로드하고 받은 id를 fileIds로 재사용하세요.

에러 코드

공통 에러(401·400 본문 검사·402·429·503 등) 외에 이 API에서 나오는 코드:

감정 상태 분석 (Emotion)

Chat API에서 요약 사이클에 편승하여 사용자와 AI의 감정 상태를 분석합니다. 별도의 LLM 호출이 없으며, 요약 프롬프트에만 감정 분석 블록을 추가하므로 추가 과금이 없습니다. ridm/* 모델에서만 지원됩니다.

개요

활성화 조건:

1. Global: partner_emotion_enabled ✓
2. Partner: 콘솔 기능 설정에서 "감정 상태 분석" 활성화
3. Request: emotion: true 명시
4. Model: ridm/* 계열만 지원

요약 주기 (summaryEvery)

감정 분석은 요약 사이클마다 자동으로 실행됩니다. summaryEvery 파라미터로 사이클 주기를 조절할 수 있습니다 (기본값: 5, 범위: 1–20).

• summaryEvery=1: 거의 매 턴마다 감정 업데이트 (요약은 응답 뒤 비동기로 실행)
• summaryEvery=5: 5턴 주기 (권장)
• summaryEvery=20: 20턴 주기 (갱신 최소)
• 요약·감정 사이클은 주기와 무관하게 파트너에게 과금되지 않습니다.

요청 파라미터

요청 예시

{
  "model": "ridm/gpt-5.6-terra",
  "user": "user_123",
  "messages": [
    { "role": "user", "content": "오늘 하루가 힘들어..." }
  ],
  "emotion": true,
  "summaryEvery": 3
}

응답 필드

응답 예시

{
  "id": "chatcmpl-xyz",
  "choices": [{
    "message": { "content": "오늘 하루가 힘들었군요..." },
    "finish_reason": "stop"
  }],
  "emotion": {
    "user": {
      "type10": "sad",
      "tone": "warm",
      "distribution6": {"joy": 100, "sadness": 600, "anger": 50, "fear": 100, "disgust": 50, "surprise": 0}
    },
    "assistant": {
      "distribution6": {"joy": 200, "sadness": 100, "anger": 0, "fear": 0, "disgust": 0, "surprise": 0}
    },
    "trend": "stable",
    "updatedAt": "2026-08-26T12:34:56Z",
    "turnsSinceUpdate": 0
  },
  "usage": {...}
}

분포 필드 설명 (distribution6)

추세 판정 (trend)

• improving: 비긍정 감정(sadness+anger+fear+disgust)이 50 이상 감소
• stable: 변화 50 미만
• declining: 비긍정 감정이 50 이상 증가
• null: 이전 사이클 데이터 부재

스트리밍 응답 예시 (SSE)

스트리밍 모드(stream: true)에서는 감정 상태가 event: message_done SSE 이벤트의 데이터에 포함됩니다.

event: message_done
data: {"finish_reason":"stop","usage":{...},"costWon":2,"recalledMemories":[],"memorySaved":{"id":"turn-1756200000000","keywords":[]},"emotion":{"user":{"type10":"concerned","tone":"warm","distribution6":{...}},"assistant":{...},"trend":"stable","updatedAt":"2026-08-26T12:34:56Z","turnsSinceUpdate":0}}

data: [DONE]

비용 안내

• 별도 과금 없음: 감정 분석은 요약 사이클 프롬프트에 포함되어 진행되며, 요약·감정 사이클의 토큰은 파트너에게 과금되지 않습니다. 과금은 채팅 턴 자체의 입력·출력 토큰뿐입니다.

주의사항

• 첫 사이클 전: 첫 요약 사이클이 실행되기 전에는 emotion 필드가 없습니다 (정상 동작).
• 기능 OFF: emotion: true 요청인데 전역 또는 파트너 기능 설정이 비활성이면 403 { code: 'FEATURE_DISABLED', feature: 'emotion' } 응답 (YouTube·문서 처리와 동일). emotion을 보내지 않거나 false면 필드만 생략됩니다.
• ridm/* 모델에서만 지원됩니다. 감정 기능이 켜진 계정이면 리셀(openai/*·google/*) 요청의 emotion 필드는 무시되고, 꺼진 계정이면 모델과 무관하게 emotion:true는 403 FEATURE_DISABLED입니다.
• 스트리밍: 스트리밍 응답에서는 message_done SSE 이벤트에 emotion이 포함됩니다.

사주 이미지 API

사주의 오행과 에너지를 표현하는 AI 아트를 생성합니다. PNG 포맷으로 base64 인코딩되어 반환되며, 고정 ₩200 과금이 적용됩니다.

POST /api/v1/partners/v1/image

생년월일을 기반으로 사주 오행 이미지를 생성합니다.

요청 파라미터

요청 예시

curl -X POST https://api.hrum.ai/api/v1/partners/v1/image \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "female", "style": "portrait" }'

응답 예시

{
  "success": true,
  "data": {
    "imageDataUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
    "costPoints": 200
  }
}

주의사항

• 고정 가격: 모든 이미지 생성은 ₩200이 과금됩니다.
• 생성 시간: 이미지 생성에는 20~30초 소요됩니다. 타임아웃을 충분히 설정해주세요.
• Base64 인코딩: 반환된 imageDataUri는 base64로 인코딩된 PNG 이미지이며, HTML <img src="{imageDataUri}"> 태그에 직접 사용할 수 있습니다.
• 스타일: background(배경 아트)·icon(미니멀 아이콘)·portrait(초상 일러스트)는 분위기만 바꿉니다. 크기는 모든 스타일이 같습니다(기본 1024×1024 정사각형).
• 타임아웃: 상류가 80초 안에 이미지를 돌려주지 않으면 504 IMAGE_UPSTREAM_TIMEOUT을 반환하며 과금하지 않습니다. 다시 시도하세요.
• 출생시간 미상: hour 생략 시 시주를 빼고 년·월·일 3주 기준으로 해석합니다.

에러 코드

공통 에러(401·400 본문 검사·402·429·503 등) 외에 이 API에서 나오는 코드:

이미지 생성 API (모델 리셀)

POST /api/v1/partners/v1/images/generations

OpenAI Images API와 같은 형식으로 GPT-Image·Nano Banana 모델을 하나의 키로 호출합니다. 모델·해상도·품질마다 장당 가격이 정해져 있고, 표의 금액이 그대로 차감됩니다(생성된 장수 × 장당 가격). 프롬프트 입력 토큰 비용도 장당 가격에 포함되어 있어 별도로 붙지 않습니다.

요청 파라미터

GPT-Image에 aspect_ratio·resolution을 보내거나, 모델이 지원하지 않는 해상도를 요청하면 400 INVALID_PARAMETER로 거절되며 과금되지 않습니다.

그 밖의 에러: MODEL_NOT_FOUND·INVALID_MODEL(400, 없는 모델), INVALID_PROMPT(400, 상류가 프롬프트 거절), UPSTREAM_ERROR, RATE_LIMITED(현재 HTTP 400, 본문 status 429), INSUFFICIENT_BALANCE(402).

장당 가격 (₩, 부가세 별도)

요청 예시

curl -X POST https://api.hrum.ai/api/v1/partners/v1/images/generations \
  -H "X-Partner-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/nano-banana-pro",
    "prompt": "A serene mountain landscape at sunset",
    "aspect_ratio": "16:9",
    "resolution": "2K"
  }'

응답 예시

{
  "created": 1791452814,
  "data": [ { "b64_json": "iVBORw0KGgo..." } ],
  "costWon": 225,
  "requestId": "..."
}

• GPT-Image·Google 직접 모델은 b64_json, FAL 모델은 url로 이미지를 돌려줍니다.
• costWon = 장당 가격 × 실제 생성된 장수. 업스트림이 이미지를 하나도 돌려주지 않으면 과금하지 않습니다.
• GPT-Image 응답의 usage(토큰 수)는 참고용이며 가격에는 쓰이지 않습니다.

에러 코드

공통 에러(401·400 본문 검사·402·429·503 등) 외에 이 API에서 나오는 코드:

오류 응답은 다른 API와 같은 {"success": false, ...} 형식입니다(성공 응답만 감싸지 않습니다).

만세력 API

POST /api/v1/partners/v1/manseryeok

사주 정체성 포함 — 응답 끝의 identity 필드에 삼재·신살·공망·통근·계절 강약·대운/세운 타임라인·사주 MBTI가 함께 들어갑니다(추가 요금 없음, 계산 실패 시 null).

원국 4주(년·월·일·시)의 천간·지지·한자·오행·십신·지장간·납음·12운성·신살을 계산합니다. 절기 기반 정확한 계산으로 원국 분석(용신·억부·조후용신·신강약·정탁·통관·병약·오행변수) → 대운 10구간(현재 대운 포함·간지합충형해) → 세운 5개년(연도별 등급·관계·해석) → 격국·상세해석 → 천간 10개론·계절 상태·공망·허자·비합·암록 까지, 최상위 기본 30개 필드 + 옵션 필드(하위 필드 포함 200개 이상)로 완전한 사주 해석을 제공합니다. 출생시간 미상 시 시주(wonkuk.hour)와 실제 시각이 필요한 trueSolarTime만 null이며, 용신·격국·신강약 등 분석 필드는 년·월·일 3주(6글자) 기준으로 계산된 값으로 그대로 제공됩니다 (birthHour.basis: "three_pillars").

요청 파라미터

응답 필드 (기본 30개 + 옵션 필드)

PillarFull 구조 (각 주의 하위 필드)

응답의 wonkuk.year·wonkuk.month·wonkuk.day·wonkuk.hour 각각이 갖는 필드:

DaeunPeriod 구조 (대운 각 구간)

SeunYear 구조 (세운 각 연도)

요청 예시

curl -X POST https://api.hrum.ai/api/v1/partners/v1/manseryeok \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "year": 2000, "month": 1, "day": 15, "hour": 14, "minute": 30,
    "gender": "male", "calendar": "solar", "timezone": "Asia/Seoul"
  }'

응답 예시 (발췌: 2000-01-15 14:30 남성)

{
  "success": true,
  "data": {
    "wonkuk": {
      "year": {
        "stem": "기", "branch": "묘", "stemHanja": "己", "branchHanja": "卯",
        "ohaeng": "토", "stemSipsin": "정관", "branchSipsin": "상관",
        "jijanggan": ["갑", "을"], "chunghyung": [], "hapPosition": ["半合(반합)"],
        "ungSung": "사", "napEum": "성두토",
        "majorSinsal": ["장성살"],
        "minorSinsal": ["천을귀인", "원진살", "현침살", "육해살"]
      },
      "month": { ... },
      "day": { ... },
      "hour": { ... }
    },
    "trueSolarTime": null,
    "ohaengBalance": { "목": 1, "화": 2, "토": 3, "금": 1, "수": 1 },
    "yongshin": "수",
    "johuYongshin": "화",
    "yongshinDetail": {
      "method": "억부",
      "primary": "수",
      "secondary": ["금"],
      "reasoning": ["일간 임(수) 신약 (score=-66)", "신약 + root 있음(8) → 비겁(수)"],
      "shin": { "yongshin": "수", "huishin": "금", "gishin": "토", "gushin": "화", "hanshin": "목" },
      "favorable_sipsin": ["편인", "정인", "비견", "겁재"],
      "unfavorable_sipsin": ["편관", "정관", "편재", "정재", "식신", "상관"],
      "element_states": { "목": { "count": 1, "state": "lack", "effect": "neutral" }, "...": "5오행" }
    },
    "eokbuYongshin": "수",
    "ilganSummary": "壬水 — 큰 바다의 기운. 지혜롭고 포용력이 넓습니다.",
    "daeun": [
      {
        "startAge": 3, "endAge": 13,
        "stem": "병", "branch": "자", "stemHanja": "丙", "branchHanja": "子",
        "ohaeng": "화", "isCurrent": false,
        "stemSipsin": "편재", "branchSipsin": "겁재",
        "sinsal": ["년살", "장성살"]
      },
      {
        "startAge": 13, "endAge": 23,
        "stem": "을", "branch": "해", "stemHanja": "乙", "branchHanja": "亥",
        "ohaeng": "목", "isCurrent": false,
        "stemSipsin": "상관", "branchSipsin": "비견",
        "sinsal": ["지살", "망신살"]
      },
      {
        "startAge": 23, "endAge": 33,
        "stem": "갑", "branch": "술", "stemHanja": "甲", "branchHanja": "戌",
        "ohaeng": "목", "isCurrent": true,
        "stemSipsin": "식신", "branchSipsin": "편관",
        "sinsal": ["천살", "월살"]
      }
    ],
    "seun": [
      {
        "year": 2026, "stem": "병", "branch": "오", "stemHanja": "丙", "branchHanja": "午",
        "ohaeng": "화", "isCurrent": true, "grade": "good",
        "relations": [
          { "type": "해", "target": "월주", "description": "오-축 해" },
          { "type": "육합", "target": "시주", "description": "오-미 육합" }
        ],
        "summary": "전체적으로 순조로운 흐름이 예상됩니다.",
        "sinsal": ["육해살", "재살"]
      }
    ],
    "branchRelations": [
      { "type": "沖(충)", "pillars": ["축", "미"], "description": "丑未沖 (축미충)" },
      { "type": "刑(형)", "pillars": ["축", "미"], "description": "丑未刑 (축미형)" },
      { "type": "半合(반합)", "pillars": ["묘", "미"], "description": "卯未合 (묘미 반합)" }
    ],
    "gongmang": [],
    "cheonEulGwiIn": [],
    "wolryeong": "축",
    "daeunNumber": 3,
    "daeunDirection": "역행",
    "gyeokguk": {
      "name": "정관격",
      "summary": "질서·명예·합리"
    },
    "gyeokgukDetail": { ... },
    "cheonganDetail": { ... },
    "hapChungReport": { ... },
    "heojaReport": { ... },
    "gongmangDetail": { ... },
    "ohaengByeonsuHits": [
      {
        "key": "to_wang_deuk_mok",
        "subject": "土", "target": "木",
        "formula_idiom": "방능소통(方能疏通)",
        "description": "토가 왕성한데 목을 얻으면 소통이 된다",
        "category": "wang_geuk_sunwha"
      }
    ],
    "strength": {
      "dayMaster": "임",
      "score": -66,
      "result": "신약",
      "level": "중약",
      "breakdown": { "season": -30, "support": 8, "control": -38, "hidden": -9, "root": 8 }
    },
    "jeongtak": {
      "verdict": "탁",
      "reasons": ["파괴 십신 2개 감지", "용신 금 생 ✓", "일주 신약"],
      "severity": "극탁"
    },
    "tonggwan": { ... },
    "byeongyak": { ... },
    "countryCodeUsed": null,
    "identity": {
      "rooting_hints": { ... }, "season_strength_hint": { ... }, "sinsal_list": [ ... ],
      "gongmang": { ... }, "samjae": { ... }, "timeline": { ... },
      "mbti_inference": { ... }, "coherence": { ... }
    },
    "ohaengDeficient": []
  }
}

이 예시는 위치를 보내지 않은 요청이라 trueSolarTime이 null입니다. 같은 요청에 "country": "KR"(또는 좌표)를 더하면 trueSolarTime에 보정 결과가 들어가고("basis": "country"), countryCodeUsed는 "KR"이 됩니다. 보정 결과 형태는 아래 주의사항의 음력 입력 예시를 보세요.

주의사항

• 복잡한 응답: 만세력 응답은 원국뿐만 아니라 대운, 세운, 격국, 신살 등 상세 정보를 포함합니다. 필요한 필드만 선택해 사용하세요.
• 선택적 필드 — 출생시간 미상 계약: hour·minute는 생략할 수 있습니다. hour를 생략하면 정오로 가정하지 않고 시주(時柱)를 제외합니다. 응답은 다음처럼 달라집니다.
  • wonkuk.hour = null, trueSolarTime = null
  • ohaengBalance = 년·월·일 3주(천간+지지 6글자) 기준으로 재계산
  • branchRelations·cheonEulGwiIn = 3주 지지만으로 성립하는 항목만 남김
  • 최상위 birthHour 추가: { known: false, hourPillar: null, basis: "three_pillars", excludedFields: [], note }. 분석 필드(yongshin·strength·gyeokguk·hapChungReport·ilganSummary·seun 등)는 제거되지 않고 년·월·일 3주(6글자) 기준으로 계산된 값으로 내려갑니다 (글자 수에 의존하는 임계치도 6글자 기준으로 환산). 정오 참고값이 아니라 3주만으로 산출한 값입니다
  • 미상 여부 판별은 birthHour.known을 사용하십시오 — excludedFields.length로 판별하지 마십시오. 이 배열은 이제 항상 비어 있으며 구버전 클라이언트 호환을 위해서만 유지됩니다
  • minute는 hour 없이 보내면 무시됩니다 (hour가 있을 때만 minute ?? 0)
  • hour를 보낸 요청에는 birthHour 필드가 없고 계산 결과도 이전과 같습니다(2026-10-10부터 붙는 identity·ohaengDeficient 제외). 항상 hour를 보내던 기존 클라이언트는 영향이 없습니다. 짧게 존재했던 "생략 시 정오 계산" 동작에 맞춰 만든 클라이언트는 birthHour.known === false를 확인해 시주 칸을 "미상"으로 표시하십시오. strength·gyeokguk 등은 3주 기준 값으로 항상 내려갑니다(2026-09-16 이전에는 제거됐습니다). 상담 계열(/reading·/reading/memory·/reading/report)도 같은 규칙으로 모델에 3주 기준 값을 전달합니다
• 한글 필드명: 모든 필드명(천간, 지지, 오행 등)은 한글로 표기됩니다. lang을 보내도 필드명은 그대로이고 값(용신·일간 설명·대운 방향·신살 이름 등)만 번역됩니다. 천간·지지·오행 코드(stem·branch·ohaeng)와 ohaengBalance의 키는 모든 언어에서 한글 그대로입니다.
• 추가 옵션은 전부 선택입니다 (2026-10-08): lang·calendar·isLeapMonth·birthLatitude·birthLongitude·country·zaSiRule·birthTimePrecision를 하나도 보내지 않으면 계산 결과는 이전과 같습니다. 단 2026-10-10부터 identity·ohaengDeficient가 항상 응답 끝에 추가됩니다(기존 키의 값·순서는 그대로). 요금도 그대로 ₩50/호출입니다.
• 음력 입력: calendar: "lunar"로 보내면 응답 최상위에 변환 내역 lunarInput이 붙습니다. 진태양시 보정 결과는 trueSolarTime에 들어갑니다. 실제 엔진 출력 예 (음력 1990-07-15 14:30, 부산 좌표, lang: "en"):

  {
    "year": 1990, "month": 7, "day": 15, "hour": 14, "minute": 30,
    "timezone": "Asia/Seoul", "gender": "male",
    "calendar": "lunar", "birthLatitude": 35.1796, "birthLongitude": 129.0756,
    "lang": "en"
  }
  →
  "lunarInput": {
    "calendar": "lunar", "lunarDate": "1990-07-15", "isLeapMonth": false,
    "leapMonthApplied": false, "solarDate": "1990-09-03"
  },
  "trueSolarTime": {
    "originalLocal": "14:30", "correctedLocal": "14:07",
    "longitudeCorrection": -23.6976, "equationOfTime": 0.3241,
    "totalCorrectionMinutes": -23.4, "dayShift": 0, "dstApplied": false,
    "basis": "coords", ...
  },
  "ilganSummary": "辛 Metal — Jewel energy. Sharp intellect and refined aesthetic sense.",
  "daeunDirection": "Forward"

• 입력 오류: 존재하지 않는 음력 날짜(예: 29일까지인 달의 30일)는 400 INVALID_LUNAR_DATE, 위도/경도 중 하나만 보낸 요청은 400 INVALID_LOCATION이며 과금되지 않습니다. timezone 누락 등 형식 오류도 400(과금 없음)입니다.

에러 코드

공통 에러(401·400 본문 검사·402·429·503 등) 외에 이 API에서 나오는 코드:

{
  "year": 1990, "month": 9, "day": 4, "hour": 14, "minute": 30,
  "timezone": "Asia/Seoul", "gender": "male",
  "topic": "career", "lang": "ko"
}

{
  "success": true,
  "data": {
    "topics": [
      {
        "topic": "career",
        "paragraphs": [
          { "component": "ilju", "key": "임신", "text": "..." },
          { "component": "ilgan_wolji", "key": "임_신", "text": "..." },
          { "component": "ilgan_strength", "key": "임_신강", "text": "..." },
          { "component": "ilgan_yongshin", "key": "임_화", "text": "..." },
          { "component": "ohaeng_state", "key": "목_lack", "text": "..." },
          { "component": "ohaeng_state", "key": "토_lack", "text": "..." },
          { "component": "ohaeng_state", "key": "수_lack", "text": "..." },
          { "component": "top_sipsin", "key": "인성", "text": "..." }
        ]
      }
    ],
    "lang": "ko",
    "fallbackLanguage": null,
    "engine": { "version": 1, "styleVersion": "v1" }
  }
}

{
  "year": 1990, "month": 9, "day": 4, "hour": 14, "minute": 30,
  "timezone": "Asia/Seoul", "gender": "male",
  "birthLatitude": 37.5665, "birthLongitude": 126.978,
  "topic": "career", "lang": "ko",
  "layers": ["astro", "ziwei"]
}

{
  "success": true,
  "data": {
    "topics": [
      {
        "topic": "career",
        "paragraphs": [
          { "component": "ilju", "key": "임신", "text": "..." },
          ...
          { "component": "top_sipsin", "key": "인성", "text": "..." },
          { "component": "astro_sun", "key": "vir", "text": "...", "label": "별자리로 보면" },
          { "component": "astro_moon", "key": "pis", "text": "..." },
          { "component": "astro_asc", "key": "sag", "text": "..." },
          { "component": "ziwei_ming", "key": "tt_jm", "text": "...", "label": "자미두수로 보면" },
          { "component": "ziwei_palace", "key": "cr_tj", "text": "..." }
        ]
      }
    ],
    "lang": "ko",
    "fallbackLanguage": null,
    "engine": { "version": 1, "styleVersion": "v1" },
    "layers": {
      "astro": { "included": true, "costWon": 20, "note": null },
      "ziwei": { "included": true, "costWon": 20, "note": null }
    }
  }
}

{
  "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30,
  "gender": "female", "referenceDate": "2026-10-08", "lang": "ko"
}

{
  "success": true,
  "data": {
    "engineVersion": 1,
    "lang": "ko",
    "referenceDate": "2026-10-08",
    "clock": {
      "inputSolarDate": "1990-05-15", "inputTime": "14:30",
      "correctedSolarDate": "1990-05-15", "correctedTime": "14:30",
      "correctionMinutes": 0, "dstApplied": false, "basis": null,
      "hourBranch": { "key": "wei", "label": "미" }
    },
    "chart": {
      "engine": { "name": "iztro", "version": "2.6.1", "config": { ... } },
      "solarDate": "1990-05-15",
      "lunarDate": { "year": 1990, "month": 4, "day": 21, "isLeapMonth": false },
      "yearGanzhi": "경오",
      "yearBasisNote": null,
      "fiveElementsClass": { "key": "earth5", "label": "토오국" },
      "soulPalaceBranch": { "key": "xu", "label": "술" },
      "bodyPalaceBranch": { "key": "zi", "label": "자" },
      "palaces": [
        ...,
        {
          "key": "ming", "label": "명궁",
          "branch": { "key": "xu", "label": "술" },
          "stem": { "key": "bing", "label": "병" },
          "isBodyPalace": false,
          "majorStars": [
            { "key": "ziwei", "label": "자미", "brightness": { "key": "de", "label": "득" }, "mutagen": null },
            { "key": "tianxiang", "label": "천상", "brightness": { "key": "de", "label": "득" }, "mutagen": null }
          ],
          "minorStars": [
            { "key": "lingxing", "label": "영성", "brightness": { "key": "miao", "label": "묘" }, "mutagen": null }
          ],
          "decadal": { "from": 5, "to": 14, "isCurrent": false }
        },
        ...
      ],
      "mutagens": [
        { "type": "lu", "label": "화록", "starKey": "taiyang", "starLabel": "태양", "palaceKey": "children", "palaceLabel": "자녀궁" },
        { "type": "quan", "label": "화권", "starKey": "wuqu", "starLabel": "무곡", "palaceKey": "wealth", "palaceLabel": "재백궁" },
        { "type": "ke", "label": "화과", "starKey": "taiyin", "starLabel": "태음", "palaceKey": "children", "palaceLabel": "자녀궁" },
        { "type": "ji", "label": "화기", "starKey": "tiantong", "starLabel": "천동", "palaceKey": "health", "palaceLabel": "질액궁" }
      ],
      "currentDecadal": { "palaceKey": "children", "from": 35, "to": 44 },
      "yearly": { "palaceKey": "wealth", "year": 2026 }
    },
    "features": [
      "bright:紫微=得", "co:紫微+天相@命", "cs:命=胎", "dir:逆", "hua:祿=太陽@子女",
      "lhua:忌=廉貞@流年", "limit:大限@子女", "limit:小限@辰", "ming:戌", "mingzhu:祿存",
      "star:天姚@辰", "star:紫微@命", "year:庚", "yy:陽女", ...
    ],
    "notes": { "lateZiNotice": null, "approximateTimeNote": null }
  }
}

{
  "success": false,
  "statusCode": 400,
  "code": "birth_time_required",
  "message": "Zi Wei Dou Shu needs the birth hour (hour 0-23). ...",
  "partial": {
    "birthYearMutagens": [
      { "type": "lu", "label": "화록", "starKey": "taiyang", "starLabel": "태양" },
      ...
    ],
    "yearStemStars": [
      { "key": "lucun", "label": "녹존", "branch": { "key": "shen", "label": "신" } },
      ...
    ]
  }
}

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

{
  "success": true,
  "data": {
    "saju": {
      "year":  { "cheongan": "경", "jiji": "오", "ohaeng": "금" },
      "month": { "cheongan": "신", "jiji": "사", "ohaeng": "금" },
      "day":   { "cheongan": "경", "jiji": "진", "ohaeng": "금" },
      "hour":  { ... }
    },
    "sipsin_map": { "year_cheongan": "비견", "year_jiji": "정관", "month_cheongan": "겁재", ... },
    "strength": { "dayMaster": "경", "score": -60, "result": "신약", "level": "중약", ... },
    "rooting_hints": { ... },
    "season_strength_hint": { "season": "여름", "strength_label": "최약(最弱)", ... },
    "sinsal_list": [ { "id": "shinsal_haksang", "name": "학당", "name_hanja": "學堂", "category": "길신", ... } ],
    "gongmang": { "sun": "갑술순", "void_branches": ["신", "유"], "hits": [] },
    "samjae": { "is_in_samjae": false, "current_year_branch": "오" },
    "yongshin": { "method": "조후", "primary": "수", ... },
    "timeline": { "current": { "daeun": { "startAge": 27, "endAge": 37, "stem": "갑", "branch": "신", ... }, ... } },
    "gyeokguk": { "primary": "비견격", ... },
    "mbti_inference": { "e_i": 48, "s_n": -8, "t_f": 16, "j_p": -18, "inferred": "ESFJ", ... },
    ...
  }
}

{
  "year": 1990, "month": 5, "day": 15, "hour": 12, "minute": 0,
  "timezone": "Asia/Seoul", "gender": "male",
  "date": "2026-10-10",
  "temperatureC": 16, "weather": "cloudy", "humidity": 60,
  "mbtiBehavior": true
}

{
  "success": true,
  "data": {
    "date": "2026-10-10",
    "summary": {
      "ilju": "경진",
      "day_master": "경",
      "gyeokguk": "비견격",
      "gyeokguk_reason": "월지 사 중기(경) 투간 [연간=경]",
      "inferred_mbti": "ESFJ",
      "today_mbti": "ESFJ",
      "current_mbti": "ESFJ",
      "strength_label": "신약",
      "yongshin": "수",
      "today_date": "2026-10-10",
      "today_ganji": "정사",
      "today_day_ohaeng": "화",
      "today_sipsin": "정관",
      "flow_score": 60,
      "flow_tier": "good",
      "top_favored_task_type": "routine",
      "top_caution_task_type": "movement",
      "active_sinsal_names": ["학당", "암록", "복성귀인", "화개살", "자형(오오)"],
      "in_samjae": false,
      "daily_flow": "오늘(정사일) 화 에너지가 흘러 소통·확장에 유리해."
    },
    "omen": {
      "relation": { "type": "GEUK", "label": "조율의 날" },
      "color": { "name": "주황", "hex": "#FFA45B", "ohaeng": "화" },
      "food": "고추장비빔밥",
      "keyword": "공개",
      "message": "표현하고 싶은 마음과 주변 반응이 엇갈릴 수 있는 날입니다. 즉흥적인 말보다 한 박자 늦춘 표현이 좋습니다.",
      "luckyHour": "오전 11시 ~ 오후 1시",
      "avoidHour": "밤 11시 이후",
      "activity": "칭찬 먼저 하기"
    },
    "taskAffinity": [
      { "taskType": "focus", "score": -0.25, "verdict": "neutral",
        "reason": "길 십신 2개 일치 · 흉 십신 2개 일치 · 일진 천간 정관(흉) · 일진 지지 편관(흉) · 천간합" },
      { "taskType": "creative", "score": -0.75, "verdict": "caution", "reason": "..." },
      ...,
      { "taskType": "routine", "score": 0.25, "verdict": "favored",
        "reason": "길 십신 4개 일치 · 일진 천간 정관(흉) · 일진 지지 편관(흉) · 천간합" }
    ],
    "fashion": {
      "temperatureC": 16, "tempBand": "T3",
      "main": "버건디 자켓", "accent": "가죽 벨트",
      "colorAttachLabel": "반지나 메탈 액세서리에",
      "byTime": {
        "morning": { "main": "버건디 자켓", "accent": "가죽 벨트", "tempBand": "T3" },
        "noon": { ... }, "evening": { ... }
      },
      "mood": {
        "feelsLikeC": 16, "tempBand": "jacket", "humidBand": "normal", "weatherKey": "cloudy",
        "morning": { "headline": "흐린 자켓 새벽", "body": "햇볕 없어 살짝 서늘. 자켓 한 벌.", "carry": [] },
        "noon": { ... }, "evening": { ... }
      }
    },
    "mbtiBehavior": {
      "mbti": "ESFJ",
      "headline": "협력·돌봄",
      "actions": ["약속·일정 챙기기 좋은 날", "주변에 도움 줄 수 있는 일 1개", "집·환경 정돈", "내 페이스도 지키기 — 다 떠안지 않기"],
      "closingLine": "주변과 결이 맞아 흐름이 부드러워요."
    }
  }
}

{
  "dream": "바다에서 커다란 물고기를 두 손으로 잡는 꿈을 꿨어요"
}

{
  "success": true,
  "data": {
    "lang": "ko",
    "mode": "glossary",
    "items": [
      { "keywords": ["바다"], "score": 1 },
      { "keywords": ["물고기"], "score": 0.979 },
      { "keywords": ["손"], "score": 0.749 }
    ]
  }
}

"kbMatches": [
  {
    "ruleId": "R-DREAM-DRAGON-002",
    "area": "DRAGON",
    "polarity": "positive",
    "status": "verified",
    "statement": "『주공해몽서』(돈황본 P.3908, 第十二 龍蛇章)는 뱀(虵=蛇)이 길에 있는 꿈(夢見虵當道者)에 대해 「大吉」라고 적는다(글자대로: 크게 길하다).",
    "quote": {
      "text": "夢見虵當道者大吉",
      "sourceId": "SRC-DREAM-P3908",
      "source": "『周公解夢書』 (敦煌 P.3908)",
      "location": "P.3908 第十二 龍蛇章 f09/左/行3下",
      "foundAt": "dream-pd/dunhuang-p3908-bnf/P3908-TRANSCRIPTION-merged.md:198"
    },
    "caveatRuleIds": [],
    "matchedTerms": ["구렁이", "길"]
  }
]

{
  "modelName": "face_landmarker",
  "modelVersion": "float16/[email protected]",
  "normalization": "face-norm-1",
  "landmarks": [[0.5012, 0.3121, -0.031], … 478개 …],
  "imageWidth": 1080,
  "imageHeight": 1350,
  "hairline": [0.501, 0.182],
  "quality": { "yawDeg": 2.1, "pitchDeg": -3.4, "blendshapes": { "eyeBlinkLeft": 0.05, "jawOpen": 0.02 } }
}

{
  "success": true,
  "data": {
    "normalization": "face-norm-1",
    "keys": { "face.thirds.upper_ratio": 0.3333, "face.brow.length_vs_eye": 1.625, "face.brow.outer_overhang": 0.1648, … },
    "reasons": {},
    "quality": { "rollDeg": 0, "iodPx": 158, "flags": [] },
    "kbMatches": [
      {
        "ruleId": "R-FACE-PALACE-031",
        "area": "PALACE",
        "kind": "interpretation",
        "polarity": "positive",
        "status": "verified",
        "statement": "『古今圖書集成』 相術部彙考 「十二宮訣」 兄弟는 눈썹이 눈보다 길게 지나가면(眉長過目) …라고 적는다 …",
        "quote": { "text": "眉長過目，三四兄弟", "sourceId": "SRC-FACE-HUIKAO", "source": "…", "location": "…", "foundAt": "…" },
        "caveatRuleIds": ["R-FACE-CAVEAT-001"],
        "matchedConditions": [{ "key": "face.brow.outer_overhang", "op": "gt", "value": 0, "actual": 0.1648 }]
      }
    ]
  }
}

타로 API

POST /api/v1/partners/v1/tarot

장수(count, 1~10장)나 스프레드(spread)를 정하면 78장 덱(메이저 22 · 마이너 56)에서 겹치지 않게 카드를 뽑아, 카드마다 정·역방향, 키워드, 뜻, 카드 이미지 주소를 돌려줍니다. AI 해석은 없습니다 — 뜻은 카드에 정해진 문장 그대로입니다. 그래서 쓰는 방법이 셋입니다.

• 타로만 불러 앱 만들기 — 응답의 카드 이름·뜻·이미지를 그대로 화면에 그립니다.
• 타로 + LLM으로 해석 — 뽑힌 카드를 LLM API 입력으로 넘겨 직접 풀이를 씁니다.
• 사주 AI와 조합 — AI 사주 리딩 요청에 tarot을 넣으면 사주 풀이와 함께 타로를 읽어 줍니다(포함 항목).

요청 파라미터

요청 예시

{
  "spread": "past-present-future",
  "question": "올해 하반기에 이직해도 될까요?",
  "seed": "user-1042:2026-10-10"
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/tarot \
  -H "X-Partner-Api-Key: $FLOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 1, "lang": "en", "reversed": false}'

응답 예시 (카드 1장 발췌)

{
  "success": true,
  "data": {
    "lang": "ko",
    "count": 3,
    "spread": { "type": "past-present-future", "name": "과거·현재·미래", "description": "시간 흐름을 따라가는 질문", "positions": ["과거", "현재", "미래"] },
    "reversedAllowed": true,
    "seed": "hrum-example-1",
    "cards": [
      {
        "position": 1,
        "positionLabel": "과거",
        "id": "wands_10",
        "name": "완드의 10",
        "nameEn": "Ten of Wands",
        "arcana": "wands",
        "reversed": true,
        "keywords": ["내려놓기", "위임", "해방"],
        "meaning": "무거운 짐을 마침내 내려놓거나 도움을 받기 시작하는 시기.",
        "imageUrl": "https://console.hrum.ai/tarot/cards/v2/wands_10.webp"
      }
    ],
    "cardBackUrl": "https://console.hrum.ai/tarot/cards/v2/back.webp",
    "question": "올해 하반기에 이직해도 될까요?",
    "costPoints": 20
  }
}

• cards[]: position(1부터, 뽑은 순서 = 스프레드 위치) · positionLabel(스프레드 위치 이름, count로 뽑으면 null) · id(언어와 무관한 카드 고유값) · name(요청 언어) · nameEn · arcana(major | wands | cups | swords | pentacles) · reversed · keywords·meaning(뽑힌 방향의 것) · imageUrl.
• spread: count로 뽑으면 null입니다.
• 카드 이미지: imageUrl·cardBackUrl은 WebP(가로 600px)이며 주소에 버전(v2)이 들어 있어 바뀌지 않습니다 — 받아서 캐시해 두고 그대로 써도 됩니다. 역방향 카드는 이미지를 180도 돌려서 보여 주세요(이미지 자체는 정방향 하나뿐입니다).
• 그림 출처: 1909 Rider-Waite(Pamela Colman Smith, 퍼블릭 도메인) 원판 스캔입니다. 카드 78장과 뒷면 모두 Wikimedia Commons의 1909 원판 스캔이며, 파일별 출처·라이선스는 출처 원장에 있습니다. 예전 주소(v1)도 같은 그림을 그대로 돌려주므로, 이미 저장해 둔 주소를 바꿀 필요는 없습니다.
• costPoints: 이번 호출의 차감액(₩).

요금

• 호출당 고정 요금 1번 — 1장을 뽑든 10장을 뽑든 같습니다. 가격은 요금의 계산형 표에 있습니다. 성공한 호출만 과금되고, 같은 입력의 반복 호출도 각각 과금됩니다 (멱등성).
• 입력 오류(400)·잔액 부족(402)은 과금되지 않습니다. 사용량 로그 endpoint는 tarot입니다.
• 아직 열리지 않은 상태에서 호출하면 404 tarot_not_enabled(과금 없음)입니다.

Waite 원전 근거 kb 준비 중

열리면 응답에 kb가 붙습니다. 뽑힌 카드마다 A. E. Waite, The Pictorial Key to the Tarot(1910, 퍼블릭 도메인) 원문에서 그 카드의 정·역방향 뜻을 규칙 ID(R-TAROT-*)와 원문 인용으로 돌려줍니다. 위의 meaning·keywords는 그대로 두고 kb만 더해지며, 요금은 같습니다.

• kb.cards[]: position · id · reversed · drawn(뽑힌 방향의 뜻) · upright · reversedMeaning · positionRule. 뜻마다 ruleId · status · statement(한국어) · quotes[](quote 원문 영어, location 장절, foundAt 원문 줄) · variants[](Waite가 적은 다른 설명 alternative, 제3부 §4 추가 의미 additional).
• status는 KB 표시를 그대로 씁니다(verified = 원문 인용 있음). Waite가 뜻을 적지 않은 자리(컵 2 역방향)는 ruleId: null, status: "disputed"입니다.
• method: "celtic-cross": Waite가 책에 적은 켈트식 점법(10장). count·spread 대신 보내며, 10장 자리마다 Waite의 자리 뜻이 positionRule에 옵니다. 다른 spread는 Waite 원문에 없는 배열이라 자리 근거가 없습니다(kb.method: null).
• kb.caveats: 자리에 따라 뜻이 바뀐다는 Waite의 말과 이용 원칙(점의 도구이며 건강·법률·재정 결정을 대신하지 않음).
• 열리기 전 method를 보내면 404 tarot_kb_not_enabled(과금 없음)입니다.

{
  "method": "celtic-cross",
  "seed": "user-1042:2026-10-11"
}

에러 코드

공통 에러(401·400 본문 검사·402·429·503 등) 외에 이 API에서 나오는 코드:

count·spread·method 가운데 정확히 하나를 보내야 합니다. 둘 이상이거나 하나도 없으면 공통 400입니다.

네이탈 차트 API (서양 점성술) 판매 종료

POST /api/v1/partners/v1/natal-chart

생년월일시로 서양 점성술 네이탈 차트(태양·달·수성·금성·화성·목성·토성 7개 천체 위치 + 상승궁)를 계산합니다. 천왕성·해왕성·명왕성은 포함하지 않습니다. 절기가 아닌 서양 점성술의 트로피컬 황도를 기준으로 합니다.

요청 파라미터

응답 필드

요청 예시

curl -X POST https://api.hrum.ai/api/v1/partners/v1/natal-chart \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1990-05-15",
    "birthTime": "12:00",
    "birthLatitude": 37.5665,
    "birthLongitude": 126.978,
    "birthTimezoneOffset": 540,
    "birthTimePrecision": "exact"
  }'

응답 예시

{
  "success": true,
  "data": {
    "sun": {
      "body": "Sun",
      "sign": "황소자리",
      "signEn": "Taurus",
      "element": "흙",
      "degreeInSign": 24.03,
      "eclipticLongitude": 54.0343
    },
    "moon": { "body": "Moon", "sign": "염소자리", "signEn": "Capricorn", "element": "흙", ... },
    "mercury": { "body": "Mercury", "sign": "황소자리", "signEn": "Taurus", ... },
    "venus": { "body": "Venus", "sign": "양자리", "signEn": "Aries", "element": "불", ... },
    "mars": { ... },
    "jupiter": { ... },
    "saturn": { ... },
    "ascendant": {
      "body": "Ascendant",
      "sign": "사자자리",
      "signEn": "Leo",
      "element": "불",
      "degreeInSign": 23.13,
      "eclipticLongitude": 143.1256
    },
    "coordsBasis": "coords"
  }
}

위 예시 요청: {"birthDate": "1990-05-15", "birthTime": "12:00", "birthLatitude": 37.5665, "birthLongitude": 126.978, "birthTimezoneOffset": 540, "birthTimePrecision": "exact"} (실제 엔진 출력 발췌).

{
  "success": true,
  "data": {
    "sun": { ... }, "moon": { ... }, ...,
    "readings": {
      "dignities": [
        { "key": "Me_dom", "lang": "ko",
          "text": "수성이 본궁인 쌍둥이자리나 처녀자리에 있으면 정보를 모으고 분류해 말로 옮기는 기능이 막힘없이 또렷하게 드러나요. 생각이 많아질 때 하나를 골라 끝까지 파고들면 그 명료함이 실제 성과로 이어져요." },
        { "key": "Sa_dom", "lang": "ko",
          "text": "토성이 본궁인 염소자리나 물병자리에 있으면 책임을 지고 구조를 세워 반복 훈련으로 숙련을 쌓는 기능이 막힘없이 또렷하게 드러나요. 기준이 지나치게 굳어질 때 쉬어 갈 틈을 일정에 남겨 두면 그 인내가 성숙하게 쓰여요." }
      ],
      "aspects": [
        { "key": "Me_Sa_tr", "deviation": 0.04, "lang": "ko",
          "text": "수성과 토성의 트라인은 절제와 의지를 생각에 더해, 서두르지 않고 앞을 내다보며 구조를 짜는 데 힘이 실려요. 변화가 필요한 순간에 익숙한 방식만 고집할 수 있으니 새 방법도 한 번 시험해 보세요." },
        { "key": "Mo_Ma_sq", "deviation": 1.03, "lang": "ko",
          "text": "달과 화성이 스퀘어를 이루면 감정이 올라오는 순간 욱하거나 규칙에 반발하는 쪽으로 기울 수 있어요. 화가 난 뒤 반응을 한 템포 늦추는 연습을 하면 그 뜨거움이 지켜야 할 것을 지키는 힘으로 바뀌어요." }
      ],
      "lang": "ko",
      "costWon": 20
    }
  }
}

주의사항

• 가격: ₩20 / 호출 (종량제) · readings: true 면 ₩20 추가 (합계 ₩40)
• 날짜 검증: 잘못된 날짜(예: 2월30일)나 잘못된 좌표/타임존은 400 에러를 반환하며 과금되지 않습니다.
• 상승궁 계산: 출생 시각 + birthTimePrecision(exact/approximate) + 위도/경도가 모두 필요합니다. 하나라도 없으면 ascendant는 null입니다.
• 풀이 문단 오류: readings: true인데 계정에 미개방이면 404 natal_readings_not_enabled, 문단을 불러오지 못하면 503 natal_readings_unavailable — 둘 다 과금되지 않습니다.
• 태양/달/상승궁: 각 행성 및 각도는 트로피컬 황도(서양 점성술 표준)를 기준으로 합니다.

에러 코드

공통 에러(401·400 본문 검사·402·429·503 등) 외에 이 API에서 나오는 코드:

점성술 토탈 API

만세력처럼 한 번 호출로 점성술 계산 전부를 돌려줍니다. 기본은 전체 네이탈 차트(태양~명왕성 10개 천체 · 달 교점 · 4개 앵글 · 하우스(기본 플라시두스) · 애스펙트 · 품위)이고, 요청에 블록을 붙이면 트랜싯 + 2차 진행(timing)과 두 사람 시너스트리(partner)가 같은 응답에 함께 옵니다. 필요한 부분만 골라 쓰면 됩니다. LLM은 쓰지 않습니다. 숫자와 규칙 키(features)에 더해, HRUM이 미리 써 둔 풀이 문단(readings)이 추가 요금 없이 항상 함께 옵니다. INTA와 같은 공용 점성술 엔진이며, 천체 위치는 NASA/JPL Horizons·Swiss Ephemeris 기준값과 대조해 검증했습니다(행성 0.005° 이내). 해석 파라미터(오브·각 종류·품위표)는 모두 고전 원전 규칙에서 왔고, 원전끼리 갈리는 값(트랜싯·진행 오브)은 기본값을 두지 않고 직접 고르게 합니다(아래 "기본값과 직접 골라야 하는 값").

POST /api/v1/partners/v1/astrology

출생 입력은 네이탈 차트 API와 같습니다(birthDate · birthTime · birthTimePrecision · birthLatitude · birthLongitude · birthTimezoneOffset, 기본 540 = KST, 한국 서머타임·1954~61 UTC+8:30 자동 반영). birthTimePrecision을 생략하면 unknown(정오 기준)입니다.

timing 블록 안:

요청 예시 1 — 기본 (네이탈만)

{
  "birthDate": "1990-05-15",
  "birthTime": "14:30",
  "birthTimePrecision": "exact",
  "birthLatitude": 37.5665,
  "birthLongitude": 126.978,
  "houseSystems": ["placidus", "whole_sign"]
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/astrology \
  -H "X-Partner-Api-Key: $FLOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthDate": "1990-05-15", "birthTime": "14:30", "birthTimePrecision": "exact", "birthLatitude": 37.5665, "birthLongitude": 126.978, "minorAspects": true, "lang": "en"}'

응답 예시 1 (발췌, 실제 엔진 출력)

{
  "success": true,
  "data": {
    "natal": {
      "utc": "1990-05-15T05:30:00.000Z",
      "timePrecision": "exact",
      "timeKnown": true,
      "zodiac": "tropical",
      "lang": "ko",
      "bodies": [
        { "id": "Sun", "longitude": 54.1347, "sign": "Taurus", "signKey": "tau", "signName": "황소자리", "degreeInSign": 24.1347, "speed": 0.9643, "retrograde": false, "dignities": [], "house": { "placidus": 9, "whole_sign": 9 } },
        { "id": "Moon", "longitude": 293.8244, "sign": "Capricorn", "signKey": "cap", "signName": "염소자리", "degreeInSign": 23.8244, "speed": 12.2943, "retrograde": false, "dignities": ["det"], "house": { "placidus": 4, "whole_sign": 5 } },
        ...
      ],
      "nodes": [
        { "id": "MeanNode", "longitude": 311.3535, "sign": "Aquarius", "signName": "물병자리", "speed": -0.0529,
          "south": { "longitude": 131.3535, "sign": "Leo", "signName": "사자자리", ... } },
        { "id": "TrueNode", ... }
      ],
      "angles": { "asc": 173.5996, "mc": 82.8067, "dsc": 353.5996, "ic": 262.8067,
        "ascSign": { "sign": "Virgo", "signName": "처녀자리", ... }, "mcSign": { ... }, "dscSign": { ... }, "icSign": { ... }, "polar": false },
      "anglesOmitted": null,
      "houseSystems": ["placidus", "whole_sign"],
      "houses": {
        "placidus": { "cusps": [173.5996, 199.6989, 229.8749, ...], "bodies": { "Sun": 9, "Moon": 4, "Jupiter": 10, ... } },
        "whole_sign": { "cusps": [150, 180, 210, ...], "bodies": { "Sun": 9, "Moon": 5, ... } }
      },
      "housesExcluded": [],
      "orbs": "leo1928",
      "minorAspects": false,
      "aspects": [
        { "a": "Jupiter", "b": "Uranus", "type": "opposition", "code": "op", "key": "Ju_Ur_op", "separation": 179.6986, "orb": 0.3014, "orbLimit": 8, "strength": "exact", "applying": false, "outOfSign": false },
        { "a": "Sun", "b": "Moon", "type": "trine", "code": "tr", "key": "Su_Mo_tr", "orb": 0.3104, "orbLimit": 8, "strength": "exact", "applying": true, "outOfSign": false },
        ...
      ],
      "dignities": { "Sun": [], "Moon": ["det"], "Mercury": [], "Venus": ["det"], "Mars": [], "Jupiter": ["exa"], "Saturn": ["dom"] },
      "moonSignUncertain": false,
      "features": [
        { "type": "planet_sign", "key": "Su_tau" },
        { "type": "dignity", "key": "Mo_det" },
        { "type": "planet_retrograde", "key": "Me_rx" },
        { "type": "planet_house", "key": "Su_h9", "system": "placidus" },
        { "type": "aspect", "key": "Su_Mo_tr", "strength": "exact", "applying": true, "orb": 0.31 },
        { "type": "meta", "key": "time_known" },
        ...
      ]
    },
    "readings": {
      "dignities": [
        { "key": "Mo_det", "text": "달이 염소자리에서 손상 자리에 있으면 감정을 바로 내보이기보다 책임과 일의 질서 속에서 조심스럽게 다루는 경향이 있어요. ...", "lang": "ko" },
        { "key": "Ve_det", ... }, { "key": "Ju_exa", ... }, { "key": "Sa_dom", ... }
      ],
      "aspects": [
        { "key": "Su_Mo_tr", "text": "태양과 달의 트라인은 의지와 정서가 같은 곳을 바라봐, 스스로 길을 내며 생활 전반을 고르게 꾸려 가는 힘이 실려요. ...", "lang": "ko", "deviation": 0.31 },
        { "key": "Su_Sa_tr", ... }, { "key": "Mo_Sa_cj", ... }, ...
      ],
      "lang": "ko"
    },
    "readingsUnavailable": false,
    "costPoints": 50
  }
}

timing·partner를 보내지 않으면 응답에 timing·synastry 키 자체가 없습니다.

• bodies[]: 태양·달·수성·금성·화성·목성·토성·천왕성·해왕성·명왕성. longitude는 황경(0° = 춘분점, 트로피컬), speed는 도/일 — 음수면 retrograde: true. 천체마다 signName(lang 언어 별자리 이름) · degreeInSign(별자리 안 도수 0~30°) · house(요청한 하우스 체계별 하우스 번호, houses[체계].bodies와 같은 값 — 하우스를 계산하지 않으면 {})가 바로 붙어 있어 이것만으로 차트 표를 그릴 수 있습니다.
• dignities: 태양~토성의 품위(dom 본궁 · exa 고양 · det 손상 · fal 추락, 해당 상태 전부). bodies[].dignities와 같은 값입니다.
• nodes[]: MeanNode(평균 교점) · TrueNode(진 교점) = 북교점, south = 남교점(+180°).
• angles: ASC·MC·DSC·IC. 출생 시각(exact/approximate)과 좌표가 둘 다 있을 때만 계산합니다. 없으면 null이고 anglesOmitted가 이유(time_unknown | coordinates_missing)를 알려 줍니다. 이때 하우스도 계산하지 않아 houses는 {}입니다.
• houses: 요청한 체계별 cusps(1~12하우스 시작 황경) + bodies(천체별 하우스 번호).
• houseSystems·houses: 실제로 계산한 체계. 극권 출생지(angles.polar = 위도가 약 66.56° 이상)에서는 플라시두스가 정의되지 않을 수 있어 포르피리로 대신 계산하고 houses.porphyry.fallbackFrom = "placidus"로 표시합니다(몰래 바꾸지 않습니다). 판정은 출생지 위도로 하므로 같은 출생지는 시각과 상관없이 늘 같은 체계를 받습니다. housesExcluded는 그 밖에 계산할 수 없었던 체계와 사유입니다(에러 응답이 아닙니다).
• aspects[]: orb = 정각에서 벗어난 도수, strength = exact(2° 이내) · close(한계의 절반 이내) · wide, applying = 정각을 향해 다가가는 중이면 true(모르면 null), outOfSign = 별자리 경계를 넘은 각(한 단계 약하게 읽습니다).
• moonSignUncertain: 시각 미상일 때 그날 안에 달 별자리가 바뀌면 true — 이때 features의 달 planet_sign에 "uncertain": true가 붙습니다.
• readings (항상 포함, 추가 요금 없음): HRUM이 미리 써 둔 풀이 문단. dignities[] = 품위(태양~토성, 천체마다 가장 센 상태 하나), aspects[] = 출생 천체 사이 각을 오브가 좁은 순서로. 각 문단은 key(features·aspects[].key와 같은 키) · text · lang(실제 문단 언어 — 요청 언어 문단이 없으면 ko) · deviation(각만, 정각에서 벗어난 도수). 미리 써 둔 문단이 있는 키만 붙고 나머지는 건너뜁니다(즉석으로 지어내지 않음) — 천왕성·해왕성·명왕성이 낀 각과 마이너 각은 문단이 없어 빠집니다. 출생 시각이 없으면 달이 낀 각, 달 별자리가 불확실하면 달 품위는 붙지 않습니다. 위 예시(1990-05-15 14:30 서울)는 애스펙트 16개 중 7개 + 품위 4개 = 11문단입니다.
• readingsUnavailable: 풀이 문단을 불러오지 못한 경우 true — 이때도 차트 계산 결과는 그대로 오고 readings는 빈 배열이며 요금(₩50)도 그대로입니다.
• features[]: 규칙 DB 매칭용 키. planet_sign Su_ari · planet_retrograde Me_rx · dignity Ma_dom · node_sign MNn_leo·TNn_leo·Nn_leo·Sn_aqu(Nn·Sn은 node 옵션의 교점) · angle_sign Asc_sco · planet_house Ve_h7(+system) · aspect Su_Mo_cj(교점은 합만 3° — Mo_Nn_cj·Sa_Sn_cj·Nn_Asc_cj, 상승점 쌍은 출생 시각이 있을 때만) · house_cusp_sign h12_ari(12하우스 커스프가 양자리) · house_empty h6(행성 10개 중 하나도 없는 하우스) · house_ruler_house h1_h7(1하우스 주인이 7하우스에) · house_ruler_sign h7_lib(7하우스 주인이 천칭자리에) — 하우스 주인은 커스프 별자리의 전통 주인(태양~토성 7행성) · planet_rising Ju(1하우스, 또는 12하우스에서 상승점 6° 이내) — 이 다섯 종류는 +system, 출생 시각과 좌표가 있을 때만 · planet_solar Ve_cazimi(태양과 17′ 이내) / Me_combust(17′~8°30′, 태양과 같은 별자리) / Ma_beams(그 밖 17° 이내) — 세 단계는 겹치지 않습니다 · moon_phase waxing·waning · meta time_known(시각 있음 — exact·approximate) / time_hour_level(approximate일 때 추가) / time_unknown. 각 키(aspect·transit·progressed·syn_aspect)에는 orb(정각에서 벗어난 도수, 소수 둘째 자리)와, 각이 별자리 경계를 넘을 때만 "outOfSign": true가 붙습니다 — 규칙 키 속성 [orb=…]·[outOfSign=true]와 맞추는 값입니다. 출생 시각을 모르면 달이 낀 출생 각에 "uncertain": true가 붙습니다. 천체 약어 Su Mo Me Ve Ma Ju Sa Ur Ne Pl, 교점 MNn TNn Nn Sn, 각 코드 cj(0°) sx(60°) sq(90°) tr(120°) op(180°) · 마이너 ssx(30°) ssq(45°) sqq(135°) qcx(150°).

요청 예시 2 — timing 포함 (트랜싯 + 2차 진행)

{
  "birthDate": "1990-05-15",
  "birthTime": "14:30",
  "birthTimePrecision": "exact",
  "birthLatitude": 37.5665,
  "birthLongitude": 126.978,
  "houseSystems": ["whole_sign"],
  "timing": { "at": "2026-10-11T09:00:00+09:00", "orbDegrees": 3, "yearLength": "tropical" }
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/astrology \
  -H "X-Partner-Api-Key: $FLOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthDate": "1990-05-15", "timing": {"orbDegrees": 2, "progressions": false}}'

응답 예시 2 (발췌, natal은 예시 1과 같은 모양)

{
  "success": true,
  "data": {
    "natal": { ... },
    "timing": {
      "at": "2026-10-11T00:00:00.000Z",
      "orbDegrees": 3,
      "natalPoints": ["Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto", "Asc", "MC"],
      "transits": {
        "bodies": [ { "id": "Sun", "longitude": 197.6966, "sign": "Libra", "signName": "천칭자리", "speed": 0.9889, "retrograde": false, ... }, ... ],
        "aspects": [
          { "a": "Mars", "b": "Mercury", "type": "square", "key": "tMa_nMe_sq", "orb": 0.6358, "orbLimit": 3, "strength": "exact", "applying": true, "outOfSign": false },
          ...
        ]
      },
      "progressions": {
        "yearLength": "tropical",
        "yearLengthDays": 365.24219,
        "ageYears": 36.4081,
        "instant": "1990-06-20T15:17:39.048Z",
        "bodies": [ { "id": "Sun", "longitude": 89.0352, "sign": "Gemini", "signName": "쌍둥이자리", ... }, ... ],
        "aspects": [
          { "a": "Uranus", "b": "Mercury", "type": "trine", "key": "pUr_nMe_tr", "orb": 0.0862, "orbLimit": 3, "strength": "exact", "applying": false, "outOfSign": false },
          ...
        ]
      },
      "features": [
        { "type": "transit", "key": "tMa_nMe_sq", "strength": "exact", "applying": true, "orb": 0.64 },
        { "type": "progressed", "key": "pUr_nMe_tr", "strength": "exact", "applying": false, "orb": 0.09 },
        ...
      ]
    },
    "readings": { ... }, "readingsUnavailable": false,
    "costPoints": 50
  }
}

• 트랜싯 대상(natalPoints): 출생 천체 10개 + 출생 시각·좌표가 있으면 상승점(Asc)·중천(MC). 키는 t(트랜싯)·n(출생) 접두사 — tSa_nSu_cj = 트랜싯 토성이 출생 태양과 합.
• transit_house tSa_h7(트랜싯 토성이 출생 7하우스에) · progressed_house pMo_h4(진행 달이 출생 4하우스에): 행성 10개씩. 출생 하우스는 기본 체계(플라시두스, 극권이면 포르피리 + "fallbackFrom": "placidus")이고 키에 "system"이 붙습니다 — houseSystems를 다르게 보내도 이 두 키는 기본 체계 기준입니다. 출생 시각이나 좌표가 없으면 나오지 않습니다.
• 진행→출생 각은 출생 행성만 대상입니다. 키 pSu_nJu_tr = 진행 태양이 출생 목성과 트라인. instant는 진행 차트로 쓴 하늘의 시각(출생 + ageYears일)입니다.
• progressions: false면 timing.progressions는 null입니다. yearLength를 생략하면 tropical(365.24219일)입니다.
• progressions가 켜진 상태에서 timing.at이 출생 시각보다 앞서면 400 at_before_birth(과금 없음).
• 시각 미상이면 출생 차트를 정오 기준으로 잡습니다. 출생 달이 대상인 키(…_nMo_…)와 진행 달 키(pMo_…)에는 "uncertain": true가 붙습니다(진행 달은 출생 달 위치를 그대로 물려받아 정오 기준만큼 흔들립니다).

요청 예시 3 — partner 포함 (시너스트리)

{
  "birthDate": "1990-05-15",
  "birthTime": "14:30",
  "birthTimePrecision": "exact",
  "birthLatitude": 37.5665,
  "birthLongitude": 126.978,
  "houseSystems": ["whole_sign"],
  "partner": { "birthDate": "1992-11-03", "birthTime": "08:10", "birthTimePrecision": "exact", "birthLatitude": 35.1796, "birthLongitude": 129.0756 }
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/astrology \
  -H "X-Partner-Api-Key: $FLOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthDate": "1990-05-15", "birthTime": "14:30", "birthTimePrecision": "exact", "partner": {"birthDate": "1992-11-03"}}'

응답 예시 3 (발췌, natal은 예시 1과 같은 모양)

{
  "success": true,
  "data": {
    "natal": { ... },
    "synastry": {
      "partner": {
        "utc": "1992-11-02T23:10:00.000Z",
        "timePrecision": "exact",
        "timeKnown": true,
        "moonSignUncertain": false,
        "bodies": [ { "id": "Sun", "longitude": 220.7903, "sign": "Scorpio", "signName": "전갈자리", "speed": 1.0016, "retrograde": false, "dignities": [], ... }, ... ],
        "angles": { "asc": 252.31, "mc": 175.86, "ascSign": { "sign": "Sagittarius", "signName": "사수자리", ... }, "mcSign": { "sign": "Virgo", "signName": "처녀자리", ... } },
        "anglesOmitted": null
      },
      "orbs": "leo1928",
      "minorAspects": false,
      "aspects": [
        { "a": "Moon", "b": "Mars", "type": "opposition", "code": "op", "key": "aMo_bMa_op", "orb": 0.2993, "orbLimit": 10, "strength": "exact", "applying": null, "outOfSign": false },
        { "a": "Neptune", "b": "Uranus", "type": "conjunction", "code": "cj", "key": "aNe_bUr_cj", "orb": 0.3898, "orbLimit": 8, "strength": "exact", "applying": null, "outOfSign": false },
        ...
      ],
      "features": [
        { "type": "syn_aspect", "key": "aMo_bMa_op", "strength": "exact", "orb": 0.3 },
        { "type": "syn_aspect", "key": "aNe_bUr_cj", "strength": "exact", "orb": 0.39 },
        { "type": "astro_syn", "key": "Su_Mo_se" },
        { "type": "syn_sign", "key": "aAsc_bAsc_es" },
        ...
      ]
    },
    "readings": { ... }, "readingsUnavailable": false,
    "costPoints": 50
  }
}

• 키 접두사 a = 요청한 본인, b = partner. aVe_bMa_cj = 본인 금성이 상대 화성과 합. 본인 천체 10개(+상승점·중천) × 상대 천체 10개(+상승점·중천) 전부를 봅니다(방향이 있어 aSu_bMo와 aMo_bSu는 다른 키).
• 상승점(Asc)·중천(MC)은 그 사람의 출생 시각과 좌표가 둘 다 있을 때만 계산합니다(본인과 같은 규칙, 상대는 synastry.partner.angles/anglesOmitted). 앵글이 낀 교차 각은 합·충만 6°로 봅니다. 단 상승점끼리의 합(aAsc_bAsc_cj)만 17°까지 냅니다(프톨레마이오스 『테트라비블로스』 — 두 상승점이 17° 안이면 결속이 강하다, 규칙 [orb=17]). 실제 벌어진 도수는 orb로 옵니다. 앵글은 그 앵글을 가진 사람의 시각만 확정이면 계산합니다. 하강점·천저는 상승점·중천의 정반대라 따로 키를 내지 않습니다.
• astro_syn: 고전 6쌍(태양–달, 금성–화성, 달–금성, 태양–금성, 달–화성, 금성–토성)의 별자리 관계 중 가장 강한 2개. 두 방향을 한 키로 접습니다(Su_Mo_se = 한쪽 태양과 다른 쪽 달이 같은 원소). syn_sign: 본인 점 × 상대 점 전부의 별자리 관계(aAsc_bAsc_ss). 두 사람 모두 출생 시각이 exact이면 행운점(PoF, 낮/밤 공식 반전)도 점에 넣습니다(aPoF_bPoF_ss) — 행운점은 상승점과 함께 4분에 약 1°씩 움직여 시 단위(approximate)나 시각 미상에서는 내지 않습니다. 관계 코드 ss(같은 별자리) · op(대극) · se(같은 원소) · es(원소 지지) · sm(같은 양상) · ef(원소 마찰) · nt(무관).
• 오브 표와 마이너 각 여부는 네이탈과 같은 orbs·minorAspects를 씁니다. 두 출생 차트 사이라 접근·분리가 없어 applying은 항상 null입니다.
• 어느 한쪽이라도 출생 시각을 모르면 그 사람 차트는 정오 기준입니다. 그 사람의 달이 낀 각에는 features에 "uncertain": true가 붙습니다(달은 하루 약 13° 움직여 오브보다 넓게 흔들립니다). 상대 앵글과 짝지은 각(aAsc_bMo_…, 반대 방향 aMo_bAsc_…)도 같습니다.
• 상대의 하우스는 계산하지 않습니다(시너스트리 하우스 겹침 미제공).

기본값과 직접 골라야 하는 값

• 하우스 체계(기본 placidus): 1819·1929 사전이 "통용"이라 적은 체계입니다. 극권 출생지에서는 포르피리로 대신하고 fallbackFrom으로 표시합니다. 다른 체계가 필요하면 houseSystems로 고르세요.
• 진행 1년 길이(기본 tropical 365.24219일): 원전의 "생일→다음 생일" 1년입니다. 율리우스년(julian)과의 차이는 80세에 진행 시각 약 2.5분입니다.
• 트랜싯·진행 오브(timing.orbDegrees, timing을 보내면 필수): 원전끼리 다릅니다(정각 전 8° 대 10° 구간). 비워 두면 400입니다.
• 명왕성·교점·앵글이 낀 네이탈 각은 기본 오브 표에서 빠집니다: 레오(1928)·하인델(1919) 오브 표가 다루지 않는 점입니다(명왕성은 1930년 발견). 그래서 네이탈 aspects에는 이 점들이 나오지 않습니다(위치·하우스에는 나옵니다). 시너스트리의 앵글 교차 각만 합·충 6°(상승점끼리 합만 17°)로 봅니다.

제공하지 않는 것

• 마이너 품위(삼분·경계 term·얼굴 face), 리셉션, 네이탈 행운점(시너스트리 syn_sign에만 씀), 천왕성·해왕성·명왕성 품위, 패럴렐·중간점
• 진행 앵글(진행 ASC·MC) — 원전이 방법을 정하지 않음
• DSC·IC는 값은 주지만 features 키는 내지 않음(남교점은 Sn 키로 나옴)
• 신월·보름·상현·하현 달 위상 키(moon_phase는 waxing·waning만), 태양 동방·서방(oriental·occidental), 진행 앵글 키
• 시너스트리 하우스 겹침

요금

• 만세력과 같은 1회 ₩50 — timing·partner 블록을 추가해도, 하우스 체계·마이너 각 여부와 상관없이 같은 ₩50 한 번입니다. 응답 costPoints가 이번 차감액(₩)입니다. 사용량 로그 endpoint는 astrology입니다.
• 계산에 성공했을 때만 차감합니다. 입력 오류(400)·잔액 부족(402)은 과금되지 않습니다.
• 아직 열리지 않은 상태에서 호출하면 404 astrology_not_enabled(과금 없음)입니다.

에러 코드

공통 에러(401·400 본문 검사·402·429·503 등) 외에 이 API에서 나오는 코드:

운 흐름 API 준비 중

한 사람의 사주로 대운·세운·월운이 원국 위에 얹히는 흐름을 계산해 그래프용 숫자와 관계 목록으로 돌려줍니다. 한 번에 한 사람, LLM은 쓰지 않습니다. 세로축 값은 "운 글자를 얹은 일간 쪽 점수"입니다 — 원국 강약 총점에 운 글자마다 원국과 같은 글자당 점수표(지원·통제·지장간·뿌리)로 매긴 몫을 더하고 ±100으로 자른 값이며, 운세의 좋고 나쁨을 재지 않습니다(R-SAJU-UN-034). 신강·중화·신약 이름은 원국 것 그대로이고 운으로 다시 붙이지 않습니다.

요금: 1회 ₩50(만세력과 같음, 범위·월운을 늘려도 같은 가격). 400 등 실패 응답은 과금하지 않습니다.

숫자는 모두 INTA와 같은 공용 사주 엔진이 낸 값입니다. 출생 시각은 한국 표준시 이력 벽시계(1954~61 UTC+8:30, 서머타임 자동 반영)로 읽어 절입과 비교하므로 서버 시간대와 상관없이 같은 결과가 나옵니다.

POST /api/v1/partners/v1/saju-flow

요청 예시

{
  "birthDate": "1990-05-15",
  "birthTime": "14:30",
  "calendar": "solar",
  "gender": "male",
  "timezone": "Asia/Seoul",
  "range": { "fromYear": 1990, "toYear": 2090 },
  "monthsOfYear": 2026
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/saju-flow \
  -H "X-Partner-Api-Key: $FLOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: chart-123:flow:2026" \
  -d '{"birthDate": "1990-05-15", "birthTime": "14:30", "calendar": "solar", "gender": "male", "timezone": "Asia/Seoul", "range": {"fromYear": 1990, "toYear": 2090}, "monthsOfYear": 2026}'

응답 예시 (발췌, 실제 엔진 출력)

{
  "success": true,
  "data": {
    "engineVersion": "saju-flow-3",
    "kbVersion": "2026.10.11-2",
    "hourKnown": true,
    "natalAmbiguous": null,
    "natal": {
      "score": -37, "result": "중화", "level": "약약",
      "breakdown": { "season": -30, "support": 36, "control": -28, "hidden": -5, "root": 5 },
      "primaryYongshin": "토",
      "shin": { "yongshin": "토", "huishin": "화", "gishin": "목", "gushin": "수", "hanshin": "금" },
      "ruleIds": ["R-SAJU-STR-001", "R-SAJU-STR-018", "R-SAJU-STR-019", "R-SAJU-YONG-170"]
    },
    "daeun": [
      { "startYear": 1997, "endYear": 2006, "startAge": 7,
        "chars": [
          { "pos": "stem", "char": "임", "hanja": "壬", "ohaeng": "수", "sipsin": "식신", "shinRole": "gushin",
            "share": { "support": 0, "control": -8, "hidden": 0, "root": 0, "total": -8 } },
          { "pos": "branch", "char": "오", "hanja": "午", "ohaeng": "화", "sipsin": "정관", "shinRole": "huishin",
            "share": { "support": 0, "control": -10, "hidden": -5, "root": 0, "total": -15 } }
        ],
        "delta": -23, "line": { "value": -60, "clamped": false },
        "relations": [
          { "type": "자형", "from": "daeun", "with": "yearBranch", "a": "오", "b": "오", "ruleId": "R-SAJU-REL-044", "decisionRuleId": "R-SAJU-UN-036" },
          { "type": "육합", "from": "daeun", "with": "hourBranch", "a": "오", "b": "미", "ruleId": "R-SAJU-REL-015", "decisionRuleId": null }
        ],
        "triples": [], "hapPulim": [ ... ] },
      ...
    ],
    "years": [
      { "year": 2026, "daeunIndex": 2,
        "chars": [ { "pos": "stem", "char": "병", "hanja": "丙", ... "share": { ..., "total": -10 } },
                   { "pos": "branch", "char": "오", "hanja": "午", ... "share": { ..., "total": -15 } } ],
        "delta": -25, "line": { "value": -33, "clamped": false },
        "relations": [
          { "type": "천간합", "from": "seun", "with": "monthStem", "a": "병", "b": "신", "ruleId": "R-SAJU-REL-003", "decisionRuleId": null },
          ...
        ],
        "withDaeun": [], "triples": [],
        "hapPulim": [
          { "kind": "existing", "domain": "jiji", "pair": ["오", "미"], "status": "broken_by_dong",
            "reasonCode": "branch_hap_broken", "params": { "incoming": "오", "origin": "seun" },
            "triggeredBy": { "origin": "seun", "value": "오" },
            "reasonFallback": "동기 오(seun) 도래 → 합반 깨짐" },
          { "kind": "new", "domain": "cheongan", "pair": ["병", "신"], "chartValue": "신", "incomingValue": "병", "incomingOrigin": "seun",
            "reasonCode": "new_stem_hap", "params": { "incoming": "병", "origin": "seun", "partner": "신" },
            "reasonFallback": "병(seun) + 원국 신 → 새 천간 합 형성" },
          ...
        ],
        "ipchunNote": false },
      ...
    ],
    "months": [
      { "index": 1, "startsAt": "2026-02-04T04:55:00+09:00",
        "chars": [ { "pos": "stem", "char": "경", ... }, { "pos": "branch", "char": "인", ... } ],
        "delta": 4,
        "relations": [ { "type": "반합", "from": "wolun", "with": "yearBranch", "a": "인", "b": "오", "ruleId": "R-SAJU-REL-024", "decisionRuleId": "R-SAJU-UN-035" }, ... ] },
      ...
    ],
    "compatInputs": {
      "primaryYongshin": "토",
      "surfaceElementCounts": { "목": 0, "화": 2, "토": 2, "금": 3, "수": 1 },
      "surfaceAbsent": ["목"],
      "hourKnown": true,
      "ruleIds": ["R-SAJU-COMPAT-008", "R-SAJU-COMPAT-009", "R-SAJU-COMPAT-010"]
    },
    "caveats": ["R-SAJU-UN-028", "R-SAJU-PRAC-026", "R-SAJU-UN-034"],
    "birthBeforeIpchun": false,
    "costPoints": 0
  }
}

필드 읽는 법

• line: 누적값 — 대운은 원국 + 대운, 세운은 원국 + 그해 대운 + 세운. 매 단계 ±100으로 자르고 잘렸으면 clamped: true(R-SAJU-UN-033). 월운은 누적선이 없고 그 달 운 몫(delta)만 줍니다.
• share: 글자 하나의 몫 분해(지원·통제·지장간·뿌리). 층 무게는 대운·세운·월운 1:1:1(R-SAJU-UN-030), 운 지지 뿌리는 상한 없음(R-SAJU-UN-031).
• shinRole: 그 글자 오행의 5신 이름(용신·희신·기신·구신·한신, R-SAJU-YONG-170) — 점수가 아니라 이름입니다. 모든 명식에 5신 표가 나옵니다(null 없음).
• relations: 운 글자와 원국 글자의 형충회합 목록(점수에 넣지 않음). ruleId는 짝 표 규칙, decisionRuleId는 운에도 적는 근거 규칙(UN-035 월운, UN-036 자형, UN-037 반합)입니다. withDaeun은 세운 ↔ 그해 대운입니다. 시주 미상이면 시주와의 관계는 내지 않습니다.
• triples: 대운·세운 글자가 끼어 원국과 함께 삼합·방합 세 글자가 찬 경우(R-SAJU-UN-037).
• hapPulim: 대운·세운 글자가 건드린 원국 합(합기·풀림·깨짐)과 새로 맺은 합(R-SAJU-HAP-021~027). 월운은 넣지 않습니다. 화면 문구는 reasonCode와 params(incoming 들어온 운 글자, origin daeun|seun, 필요할 때 target·partner)로 앱 언어에 맞게 직접 만드세요. reasonFallback은 엔진이 쓴 한국어 문장으로 항상 들어 있으며, 앱이 모르는 reasonCode가 왔을 때만 대신 보여 주는 용도입니다. reasonCode는 지금 7가지입니다.
  • stem_hap_kept_jaenghap: 원국 천간합이 그대로 유지되고, 같은 양간 운 글자(incoming)는 쟁합이라 끼어들지 못함.
  • stem_hap_kept_tuhap: 원국 천간합이 그대로 유지되고, 같은 음간 운 글자(incoming)는 투합이라 끼어들지 못함.
  • branch_hap_gi: 운 글자(incoming)가 원국 육합의 한 글자(target)를 충해 합이 일어남(합기).
  • branch_hap_released: 운 글자(incoming)가 원국 육합의 한 글자를 형해 합이 풀림.
  • branch_hap_broken: 원국 육합의 한 글자와 같은 글자(incoming)가 운으로 들어와 합이 깨짐.
  • new_stem_hap: 운 천간(incoming)과 원국의 빈 천간(partner)이 새 천간합을 맺음.
  • new_branch_yukhap: 운 지지(incoming)와 원국 지지(partner)가 새 육합을 맺음.
• startAge: 대운수(첫 대운 나이). 날수는 출생일(한국 날짜) 0시부터 절입까지 세고 태어난 시·분은 넣지 않으며, 3일 = 1년으로 반올림합니다(R-SAJU-UN-038). kbVersion 2026.10.11-2부터 원장에 있는 규칙입니다.
• ipchunNote: 조회 시점(한국 시각)이 그해 입춘 전이면, 올해 칸에만 true. 1월 1일~입춘 전에는 아직 지난해 세운이 이어지고 있다는 표시입니다. 세운은 그해 입춘 간지입니다(R-SAJU-UN-016).
• birthBeforeIpchun: 1월 1일~입춘 전에 태어나 원국 연주가 앞 해 간지인 경우 true(최상위 필드).
• natalAmbiguous: 시각 미상인데 출생일에 절입이 있으면 { "pillar": "month" | "year", "termAt" } — 엔진은 정오로 판정하므로 월주(입춘이면 연주까지)가 실제와 다를 수 있다는 표시입니다.
• compatInputs: 여러 사람을 겹쳐 볼 때 앱이 집합 교차만 하도록 주는 값(용신 오행, 겉 글자 오행 개수, 겉에 보이지 않는 오행). 사람끼리 합산·순위는 만들지 않습니다.

요금

• 준비 중인 기능입니다. 열리지 않은 상태에서 호출하면 404 saju_flow_not_enabled(과금 없음)입니다.
• 계산에 성공했을 때만 차감합니다. 입력 오류(400 — 없는 날짜, 범위 101년 초과 등)는 과금되지 않습니다. 응답 costPoints가 이번 차감액(₩), 사용량 로그 endpoint는 saju-flow입니다.

에러 코드

공통 에러(401·400 본문 검사·402·429·503 등) 외에 이 API에서 나오는 코드:

궁합 API

두 사람의 사주로 궁합을 계산합니다. 사주 궁합(일주 60×60 궁합표 · 용도별 점수와 6축 · 천간/지지 관계 · 8글자 오행 보완 · 십신 · 교차 신살), 속궁합 기호표(참고 문헌(1995) 남녀 일주표의 기호·등급), 별자리 궁합(태양·달·상승궁 3층 + 용도별 행성, 별자리 궁합 문단 최대 2개), 띠 궁합(두 띠의 지지 관계와 등급)을 한 번에 돌려주고, 다섯 가지 점수를 용도별 가중치로 합친 종합 점수(headerBreakdown)도 함께 줍니다. INTA 앱 궁합 화면과 같은 엔진이고, 같은 입력은 항상 같은 결과입니다.

POST /api/v1/partners/v1/compat

두 사람의 사주를 기반으로 궁합을 분석합니다.

요청 파라미터

details·flow·MBTI 옵션은 추가 요금이 없습니다(호출당 ₩20 그대로).

• 시각 보정: 한 사람의 사주(일주·8글자 점수·종합 점수·속궁합 기호표·띠·권위자 분석·yearFlow·관계 서술)는 한 번 계산해 모든 항목에 같이 씁니다. 좌표·personXCountry·정확도 exact를 보내지 않으면 입력 시각 그대로 계산합니다(만세력 API와 동일). INTA 앱(한국어, 시각 직접 입력)과 같은 궁합이 필요하면 두 사람 모두 personXCountry: "KR"(+ personXBirthTimePrecision: "exact")를 보내세요. 출생 시각이 없는 사람은 보정하지 않습니다.
• 2026-10-11 변경: 좌표를 보내면 사주도 진태양시 보정을 합니다(그전에는 별자리 궁합에만 썼습니다). 한 응답 안에서 사주와 별자리가 같은 시각 기준을 쓰도록 맞춘 수정이라, 좌표를 보내던 호출은 사주 점수·일주가 바뀔 수 있습니다. 새 필드와 좌표를 보내지 않는 호출의 응답은 그대로입니다.

응답 예시

아래는 실제 엔진 출력입니다 (A 남 1990-09-04 14:30, B 여 1992-02-20 10:15, 연애, 좌표 없음). 2026-10-10에 추가된 항상 포함 필드(saju.relationRatings·saju.meetingKeywords·saju.authority·tti.conflictFrame)는 이 예시에서 생략했습니다 — 아래 옵션 예시를 보세요.

{
  "success": true,
  "data": {
    "personABirthDate": "1990-09-04", "personABirthTime": "14:30", "personAGender": "male",
    "personBBirthDate": "1992-02-20", "personBBirthTime": "10:15", "personBGender": "female",
    "tti": {
      "userTti": "말", "partnerTti": "원숭이",
      "relation": { "type": null, "detail": null, "relations": [] },
      "tier": "흉"
    },
    "saju": {
      "purpose": "yeonae_attraction",
      "hourKnown": { "a": true, "b": true },
      "personA": { "ilju": "임신" },
      "personB": { "ilju": "병인" },
      "score": { "total": 59, "grade": "맞춰 가면 좋아요",
                 "breakdown": { "ilju": 53, "authority": 65, "eightChar": 65 } },
      "axes": { "attraction": 25, "stability": 59, "growth": 58,
                "communication": 24, "passion": 74, "longevity": 65 },
      "pattern": { "name": "폭발형",
                   "description": "에너지가 크게 부딪히는 뜨거운 관계예요. 감정이 커질 때 잠시 쉬어 가는 규칙이 도움이 돼요." },
      "relation": { "summary": "천간충 + 인신충",
                    "stem": { "type": "천간충", "detail": "병임충" },
                    "branches": [ { "type": "지지충", "detail": "인신충" } ] },
      "elements": { "basis": "eight", "aLacks": [], "bProvidesToA": [], "bLacks": ["토"], "aProvidesToB": ["토"] },
      "tenGods": { "aView": "편재", "bView": "편관(칠살)" },
      "bestFor": ["단기 끌림"],
      "weakFor": ["결혼·동거"],
      "highlights": [ "상대의 시지에 나의 천을귀인 (사) 발현 — 상대가 나의 해결사" ]
    },
    "categoryNarrative": {
      "category": "romantic", "purpose": "yeonae_attraction", "lang": "ko",
      "text": "상대 쪽의 즉각적인 열정과 나 쪽의 자유로운 흐름은 불과 물처럼 정면으로 맞부딪혀서, 처음 만났을 때의 팽팽한 긴장감이 곧 끌림이 되기 쉬워요. 짧고 뜨거운 설렘이 큰 관계라, 감정이 치솟는 날엔 하루쯤 식힐 틈을 두면 더 즐겁게 만날 수 있어요.",
      "styleVersion": "v2"
    },
    "costPoints": 20,
    "classic1995": {
      "symbol": "××", "grade": "대흉", "score": 50,
      "ttiRelation": { "type": null, "detail": null, "relations": [] },
      "conflictFrame": false
    },
    "astroSynastry": {
      "self": {
        "sun": { "signEn": "Virgo", "element": "earth", "modality": "mutable" },
        "moon": { "signEn": "Pisces", "element": "water", "modality": "mutable", "uncertain": false },
        "ascendant": { "signEn": "Sagittarius", "element": "fire", "modality": "mutable", "uncertain": false, "countryBasis": true },
        "venus": { "signEn": "Leo", ... }, "mars": { "signEn": "Gemini", ... },
        "mercury": { ... }, "jupiter": { ... }, "saturn": { ... }
      },
      "partner": { "sun": { "signEn": "Pisces", ... }, "moon": { "signEn": "Virgo", ... }, ... },
      "layers": [
        { "key": "sun", "relation": "opposite", "selfSign": "Virgo", "partnerSign": "Pisces",
          "textKey": "compat.astro.relation.opposite",
          "text": "충 — 정반대라 방향은 다르지만 서로를 끌어당길 수 있어요" },
        { "key": "moon", "relation": "opposite", "selfSign": "Pisces", "partnerSign": "Virgo",
          "textKey": "compat.astro.relation.opposite",
          "text": "충 — 정반대라 방향은 다르지만 서로를 끌어당길 수 있어요" },
        { "key": "ascendant", "relation": "neutral", "selfSign": "Sagittarius", "partnerSign": "Taurus",
          "textKey": "compat.astro.relation.neutral",
          "text": "뚜렷한 결 없이 각자의 스타일을 존중하면 되는 조합이에요" }
      ],
      "purposeBodies": [
        { "body": "venus", "relation": "opposite", "selfSign": "Leo", "partnerSign": "Aquarius",
          "textKey": "compat.astro.relation.opposite",
          "text": "충 — 정반대라 방향은 다르지만 서로를 끌어당길 수 있어요" },
        { "body": "mars", "relation": "same_element", "selfSign": "Gemini", "partnerSign": "Aquarius",
          "textKey": "compat.astro.relation.same_element",
          "text": "같은 원소 — 서로의 방식을 바로 알아볼 만큼 편안할 수 있어요" }
      ],
      "caveats": ["compat.astro.caveat.ascendantCountryBasis"],
      "caveatTexts": ["상승궁은 출생 도시가 없어 국가 대표 좌표로 추정했어요"],
      "score": 64
    },
    "astroReadings": [
      { "key": "Su_Mo_ss", "lang": "ko",
        "text": "한쪽의 태양과 다른 쪽의 달이 같은 별자리에 놓이면, 한 사람이 향하는 방향을 다른 사람의 마음이 낯설지 않게 알아보는 깊은 공명이 생기기 쉬워요. 닮은 만큼 같은 그림자도 함께 커질 수 있으니 서로의 빈틈을 웃으며 짚어 주면 좋아요." },
      { "key": "Ve_Ma_op", "lang": "ko",
        "text": "한쪽의 금성과 다른 쪽의 화성이 정반대 별자리에 놓이면, 서로에게 없는 매력을 알아보며 끌리는 보완의 흐름이 생기기 쉬워요. 원하는 속도와 표현 방식이 반대로 기울 수 있으니 서로의 선을 말로 정해 두면 그 끌림이 편안하게 이어져요." }
    ],
    "headerBreakdown": {
      "sixAxis": 55, "authority": 65, "full8": 65, "classic": 50, "natal": 64,
      "average": 61, "purpose": "yeonae_attraction",
      "weights": { "sixAxis": 0.2, "authority": 0.3, "full8": 0.2, "classic": 0.1, "natal": 0.2 }
    },
    "lang": "ko"
  }
}

• saju(사주 궁합)이 메인입니다. 일주를 계산할 수 없는 드문 경우 null — 그때는 tti 만 보여 주세요
• saju.score.total: 0~100. 일주 궁합표 점수와 8글자 분석 점수의 평균(breakdown 에 각각). grade 는 쉬운 말 등급 — 아주 잘 맞아요(85+)·잘 맞아요(75+)·무난해요(65+)·맞춰 가면 좋아요(55+)·서로 많이 달라요. 이 값은 예전과 같습니다 — 기호표·별자리까지 합친 점수는 headerBreakdown.average
• saju.axes: 끌림·안정·성장·소통·열정·지속 6축(0~100), purpose 에 따라 달라짐. saju.pattern: 관계 유형 이름과 설명(없으면 null)
• saju.elements: 두 사람 원국 전체(시간을 모르면 6글자 — basis: "six")의 오행 분포로 계산. bProvidesToA = A에게 없는 오행 중 B가 가진 것
• saju.tenGods: A 기준으로 본 B의 십신(aView)과 그 반대(bView). highlights: 8글자에서 찾은 교차 신살 문장(최대 5개, 없으면 빈 배열)
• classic1995: 참고 문헌(1995) 남녀 일주 속궁합표의 기호(● 대길 100 · ◎ 중길 90 · ○ 길 80 · △ 무해무덕 70 · × 흉 60 · ×× 대흉 50). 이 표는 남자 일주 × 여자 일주 방향표라, 동성이거나 성별을 안 보내면 두 방향(A를 남자로 · B를 남자로)을 모두 읽어 score 는 두 점수의 평균(예 95), symbol·grade 는 그 평균을 10점 단위로 내린 등급(예 95 → ◎ 중길)으로 옵니다. 두 방향이 같으면 그 기호 그대로. conflictFrame: 기호는 길한데 띠 관계는 흉하거나 그 반대일 때 true. 일주를 못 구하면 전체 null
• astroSynastry: 별자리 궁합. layers = 태양·달·상승궁 3층 비교, purposeBodies = 용도별 우선 행성(연애: 금성·화성, 결혼: +토성, 우정: 수성·목성 …). relation = same_sign·opposite·same_element·element_support·same_modality·element_friction·neutral, text 는 그 뜻풀이(lang). score 0~100. caveats/caveatTexts: 상승궁·달 별자리가 추정이면 그 사실. 시간을 모르면 상승궁 층이 빠집니다
• astroReadings: 두 사람 별자리에서 가장 두드러진 접점(태양–달, 금성–화성 등) 최대 2개에 대해 미리 써 둔 풀이 문단. 없으면 빈 배열. 각 문단의 lang 은 실제 문장 언어(요청 언어 문장이 없으면 ko)
• headerBreakdown: 6축 평균 · 권위자(authority) · 8글자(full8) · 기호표(classic) · 별자리(natal) 다섯 점수를 purpose 별 가중치(weights)로 합친 종합 점수 average(0~100). 빠진 점수는 남은 것끼리 가중치를 다시 나눕니다. INTA 앱 궁합 화면의 큰 숫자와 같은 값. 일주 궁합표를 못 찾으면 null
• 생년월일의 연도는 1900~2100 — 벗어나면 400 INVALID_BIRTH_YEAR(과금 없음). 날짜 입력 칸에 연도를 두 자리로 치면 0090 처럼 들어가니 화면에서도 막으세요. 궁합표에서 결과를 못 찾으면 400 COMPAT_UNAVAILABLE(과금 없음)
• tti.tier: 참고 문헌(1995) 띠궁합의 등급 문자열(예: 대길·길·중길·보통·주의·흉). tti.relation.type = 두 띠 지지의 관계 — 충·원진·형·해·육합·반합·파 중 하나(여러 관계가 겹치면 이 순서로 앞선 것), 없으면 null. detail 은 반합일 때만(예: 수국(水局)). tti.relation.relations = 겹치는 관계 전부(같은 순서, 예: 소·양 띠 ["충","형"], 없으면 빈 배열)
• tti 에는 띠·관계·등급만 옵니다. 참고 문헌의 띠궁합 문장은 싣지 않습니다(2026-10-11부터).
• categoryNarrative: 이 관계(purpose)에서 두 사람이 어떤지 풀어 쓴 2~3문장. 두 사람의 일주 조합(1,830쌍)과 관계 종류 6가지마다 미리 써 둔 문장이라 같은 입력엔 항상 같은 문장이 나옵니다. 문장 속 나 = A, 상대 = B (영어 You/Your partner, 일본어 あなた/相手, 태국어 คุณ/คู่ของคุณ). lang 으로 4개 언어, 문장을 찾지 못하면 null(과금은 동일)
• 항상 포함 (2026-10-10~): saju.relationRatings = 관계 5종별 { key, stars }(key 예: 연애, 결혼·동거, 친구, 사업 파트너, 장기 관계 / 별 1~5) · saju.meetingKeywords = 만남 키워드 3개 · saju.authority = 권위자 궁합 판정(finalScore·grade·gradeTier·pattern·summary·levels(L1~L4)·factors·flags·climateBalance) · tti.conflictFrame = classic1995.conflictFrame과 같은 값
• yearFlow.years[].tier: great · good · neutral · caution. dayFlow.days[].tier: golden · good · neutral · dim · hard (dayFlow.golden/hard는 해당 날짜 목록)

옵션 예시 (details · flow · MBTI)

실제 엔진 출력 발췌입니다. 요청:

{
  "personABirthDate": "1990-05-15", "personABirthTime": "12:00", "personAGender": "male",
  "personBBirthDate": "1992-08-20", "personBBirthTime": "09:00", "personBGender": "female",
  "details": true, "flow": true, "date": "2026-10-10",
  "personAMbti": "ENFP", "personBMbti": "ISTJ"
}

{
  "success": true,
  "data": {
    "tti": { "userTti": "말", "partnerTti": "원숭이", ..., "tier": "흉", "conflictFrame": false },
    "saju": {
      "personA": { "ilju": "경진" }, "personB": { "ilju": "무진" },
      "score": { "total": 56, "grade": "맞춰 가면 좋아요", ... },
      ...,
      "relationRatings": [
        { "key": "연애", "stars": 3 }, { "key": "결혼·동거", "stars": 3 }, { "key": "친구", "stars": 4 },
        { "key": "사업 파트너", "stars": 3 }, { "key": "장기 관계", "stars": 3 }
      ],
      "meetingKeywords": ["괴강", "우직", "일반적 관계"],
      "authority": {
        "finalScore": 51, "grade": "주의", "gradeTier": "caution",
        "pattern": "자형 (자기 갈등 외부화)",
        "summary": "주의 · 자형 (자기 갈등 외부화) · 익숙한 결의 만남. 안락함 위에 자극을 어떻게 만들지가 핵심.",
        "levels": { "L1": { "raw": 0, "norm": 0 }, "L2": { "raw": 5, "norm": 14.3, "type": "동계절 (봄)" },
                    "L3": { "raw": 17, "norm": 56.7 }, "L4": { "raw": -17, "norm": -42.5 } },
        "factors": { "l1": [], "l2Tone": "...", "l3": [ ... ], "l4": ["자형(진진) — 자기 파괴 패턴", ...] },
        "flags": { "cheonHapJiHap": false, "dualChung": false },
        "climateBalance": "동계절 (봄)"
      },
      "conflict": {
        "pattern": "경은 무를 편인으로 인식. 일방향적 관계 성격.",
        "tip": "'괴강'과 '우직'은 서로 다른 결이에요. 같은 사건도 다르게 해석한다는 걸 인정하고, 서로의 관점을 한 번씩 빌려보세요."
      },
      "relationScores": { "stem": { "type": "편인", "category": "neutral", "score": 55 },
                          "branches": [ { "type": "자형", "score": -40 } ] },
      "full8": { "personA": { ... }, "personB": { ... }, "iljuEvaluation": { ... }, ... }
    },
    ...,
    "dictionary": { "a": { "id": "ilju_경진", "name_kr": "경진", "name_hanja": "庚辰", ... }, "b": { ... } },
    "yearFlow": {
      "baseYear": 2026,
      "years": [
        { "year": 2024, "score": 77, "tier": "great", "a": { ... }, "b": { ... },
          "summary": "두 분 모두 흐름이 좋아 같이 시작하기 좋은 해." },
        ...
      ]
    },
    "dayFlow": {
      "baseDate": "2026-10-10",
      "days": [
        { "date": "2026-10-03", "a": -89, "b": -40, "combined": -60, "tier": "hard", "isBaseDate": false },
        ...,
        { "date": "2026-10-10", "a": -9, "b": 27, "combined": 9, "tier": "neutral", "isBaseDate": true },
        ...
      ],
      "golden": [],
      "hard": [ { "date": "2026-10-03", "combined": -60 }, ... ],
      "summary": "3번 같이 가라앉는 날이 있어. 그날은 큰 결정·약속 미루자."
    },
    "mbti": { "id": "mbti_ENFP_ISTJ", "mbti_a": "ENFP", "mbti_b": "ISTJ",
              "socionics_relation": "Duality(이중관계)", "scores": { ..., "total": 64 }, ... }
  }
}

주의사항

• 기본 정보: 두 사람의 출생일은 필수입니다. 시간과 성별은 선택사항입니다. 성별이 없거나 같아도 속궁합 기호표는 나오고(두 방향 합산), 별자리 궁합의 상승궁은 출생 시간이 있어야 나옵니다.
• 결과 구성: 별자리 궁합은 트로피컬 황도 기준입니다. 관계별 서술은 categoryNarrative, 별자리 문단은 astroReadings 로 함께 오고, 더 긴 맞춤 풀이가 필요하면 결과를 /reading 질문에 넣어 쓰세요.
• 호환: 2026-10 추가 필드(classic1995 · astroSynastry · astroReadings · headerBreakdown · lang, 2026-10-10의 saju.relationRatings · saju.meetingKeywords · saju.authority · tti.conflictFrame)는 lang을 보내든 안 보내든 항상 덧붙습니다. 기존 필드의 값은 그대로입니다. 단, 2026-10-11부터 참고 문헌(1995)의 문장을 옮긴 필드 — 띠 궁합 한 줄 풀이와 일주 사전의 애정운·건강운 — 는 응답에서 빠졌습니다.
• 비용: 호출당 ₩20이 차감됩니다 (추가 필드·details·flow·MBTI 옵션 포함, 추가 요금 없음).

에러 코드

공통 에러(401·400 본문 검사·402·429·503 등) 외에 이 API에서 나오는 코드:

요청 예시는 위 옵션 예시와 실행 예시를 보세요.

성격유형 API

MBTI 기반 성격 검사를 제공합니다. 무료 라이트 버전(24문항)과 프리미엄 버전(93문항)을 지원합니다.

GET /api/v1/partners/v1/personality-type/questions

성격 검사 문항을 조회합니다. 무료입니다.

curl "https://api.hrum.ai/api/v1/partners/v1/personality-type/questions?tier=free" \
  -H "X-Partner-Api-Key: your-api-key"

요청 파라미터

응답 예시

{
  "success": true,
  "data": {
    "tier": "free",
    "count": 24,
    "questions": [
      {
        "id": "q_001",
        "text": "갑자기 생긴 모임에도 일단 가본다",
        "choices": [
          { "value": 1, "label": "전혀 그렇지 않다" },
          { "value": 2, "label": "그렇지 않다" },
          { "value": 3, "label": "보통이다" },
          { "value": 4, "label": "그렇다" },
          { "value": 5, "label": "매우 그렇다" }
        ]
      }
    ]
  }
}

POST /api/v1/partners/v1/personality-type

성격 검사 답변을 제출하여 성격유형을 분석합니다.

curl -X POST https://api.hrum.ai/api/v1/partners/v1/personality-type \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "free",
    "answers": [
      { "questionId": "q_001", "answer": 4 },
      { "questionId": "q_002", "answer": 2 }
    ]
  }'

요청 파라미터

응답 예시

{
  "success": true,
  "data": {
    "personalityType": "ENTJ",
    "typeLabel": "지휘관",
    "scores": {
      "extraversion": 72,
      "sensing": 45,
      "thinking": 68,
      "judging": 80
    },
    "tier": "premium",
    "costPoints": 10
  }
}

가격

• 무료 버전 (free): 24문항, ₩0 (무료)
• 프리미엄 (premium): 93문항, ₩10/회
• 없는 questionId나 1~5 밖의 answer는 400이며 과금되지 않습니다.

에러 코드

공통 에러(401·400 본문 검사·402·429·503 등) 외에 이 API에서 나오는 코드:

답이 1~5 밖이면 공통 400입니다. 모두 과금되지 않습니다.

해석 DB (KB) API

신청한 계정에서만 열리는 API입니다. 열리지 않은 계정은 세 경로 모두 404 kb_saju_explain_not_enabled를 받습니다(과금 없음). 사용하려면 지원으로 문의하세요.

사주 원국에서 성립하는 관계(합·충 등)와 구조(십신·지장간 등)를 규칙 카드와 해설 문장으로 풀어 줍니다. LLM을 쓰지 않아 같은 입력에는 항상 같은 결과가 나옵니다.

POST /api/v1/partners/v1/kb/saju/explain

요청 파라미터

요청 예시

curl -X POST https://api.hrum.ai/api/v1/partners/v1/kb/saju/explain \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "birth": {
      "year": 1990, "month": 5, "day": 17, "hour": 14, "minute": 30,
      "timezone": "Asia/Seoul", "gender": "female"
    },
    "sections": ["relations"],
    "channel": "preview"
  }'

응답 예시 (발췌)

{
  "success": true,
  "data": {
    "kbVersion": "2026.10.09-3",
    "kbHash": "sha256:24b9a2d9...",
    "channel": "preview",
    "chart": {
      "pillars": {
        "year":  { "stem": "庚", "branch": "午" },
        "month": { "stem": "辛", "branch": "巳" },
        "day":   { "stem": "壬", "branch": "午" },
        "hour":  { "stem": "丁", "branch": "未" }
      },
      "timeUnknown": false
    },
    "sections": [
      {
        "id": "relations",
        "title": "...",
        "steps": [
          {
            "fact": { "type": "stem_pair", "a": "壬", "b": "丁", "posA": "day", "posB": "hour", "relation": "hap" },
            "factText": "일간 壬과 시간 丁은 천간합(天干合) 관계다.",
            "componentId": "saju:stem_pair:丁壬:hap",
            "rules": [
              { "id": "R-SAJU-REL-004", "kind": "definition", "status": "verified", "sourceCount": 2,
                "statement": "丁과 壬은 천간합 관계이고, 이 짝의 합화 오행은 목(木)이다." }
            ],
            "interp": {
              "meaning": { "text": "丁(정)과 壬(임)은 천간합으로 묶이는 짝이고, ...", "reviewed": false },
              "why": { ... },
              "pitfall": { ... }
            }
          }
        ],
        "absent": [
          { "type": "stem_pair", "a": "庚", "b": "辛", "posA": "year", "posB": "month",
            "note": "庚과 辛은 천간합·천간충 어느 것도 아니다." }
        ]
      }
    ],
    "unregistered": [],
    "pendingReview": []
  }
}

• interp는 해설 칸(meaning 뜻 · why 근거 · pitfall 주의)입니다. 칸마다 {text, reviewed, reviewedBy?, notes?}이고, stable에서는 검수된 칸만 나옵니다.
• unregistered: 성립했지만 해설이 아직 없는 항목. pendingReview: 해설은 있지만 검수 전이라 stable에서 숨긴 항목.
• 규칙 카드의 원전 출처는 아래 GET /kb/rules/{id}로 조회합니다.

GET /api/v1/partners/v1/kb/rules/{id}

규칙 카드 하나와 원전 출처를 돌려줍니다. 무료입니다.

curl https://api.hrum.ai/api/v1/partners/v1/kb/rules/R-SAJU-REL-004 \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "id": "R-SAJU-REL-004",
    "kind": "definition",
    "statement": "丁과 壬은 천간합 관계이고, 이 짝의 합화 오행은 목(木)이다.",
    "status": "verified",
    "schools": [],
    "variantOf": null,
    "sources": [
      { "sourceId": "SRC-SMTH", "location": "『三命通會』 卷二 論十干化氣",
        "quote": "故丁與壬合　丁壬化木", "match": "EXACT", ... }
    ],
    "engineRef": "..."
  }
}

GET /api/v1/partners/v1/kb/release?domain=saju

현재 공개된 해석 DB 판(版)을 돌려줍니다. 무료입니다. domain은 생략하면 saju입니다(예: saju · ziwei · astro · dream · tarot).

curl "https://api.hrum.ai/api/v1/partners/v1/kb/release?domain=saju" \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "version": "2026.10.09-3",
    "hash": "sha256:24b9a2d9...",
    "publishedAt": "2026-10-09T00:00:00.000Z",
    "channel": "stable",
    "counts": { "rules": 412, "interps": 1236 }
  }
}

위 숫자는 예시입니다. 결과를 저장해 둔다면 hash가 바뀌었을 때 다시 받으세요.

에러 코드

공통 에러 외에:

explain은 성공한 호출만 과금하며, 실패한 호출은 ₩0으로 기록됩니다.

인증 API

콘솔 계정 관리를 위한 인증 API입니다.

POST /api/v1/partners/v1/console/auth/login

계정으로 로그인합니다. 이메일/비밀번호 또는 소셜 로그인을 지원합니다.

요청 (이메일)

curl -X POST https://api.hrum.ai/api/v1/partners/v1/console/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "email",
    "email": "[email protected]",
    "password": "your-password"
  }'

요청 (소셜)

curl -X POST https://api.hrum.ai/api/v1/partners/v1/console/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "identityToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ..."
  }'

응답

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "user-123",
      "email": "[email protected]",
      "displayName": "John Doe",
      "provider": "email"
    }
  }
}

user.provider는 email · apple · google 중 하나입니다.

POST /api/v1/partners/v1/console/auth/register

새로운 계정을 등록합니다.

요청

curl -X POST https://api.hrum.ai/api/v1/partners/v1/console/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "secure-password",
    "displayName": "John Doe",
    "agreements": { "terms": true, "privacy": true }
  }'

password는 8~128자, displayName은 2~50자입니다. agreements.terms·agreements.privacy는 반드시 true여야 하며(없거나 false면 400), agreements.aiTraining(boolean)은 선택입니다.

응답

{
  "success": true,
  "data": {
    "message": "인증 메일을 발송했습니다"
  }
}

POST /api/v1/partners/v1/console/auth/verify-email

이메일 인증을 완료합니다. 인증 메일의 토큰과 가입할 때 정한 비밀번호를 함께 보냅니다.

요청

curl -X POST https://api.hrum.ai/api/v1/partners/v1/console/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{
    "token": "인증-메일의-토큰",
    "password": "secure-password"
  }'

응답

{
  "success": true,
  "data": {
    "message": "이메일 인증이 완료되었습니다"
  }
}

토큰이 틀렸거나 만료됐거나 비밀번호가 맞지 않으면 400 EMAIL_VERIFY_FAILED입니다. 인증 메일 링크(GET /api/v1/partners/v1/console/auth/verify-email?token=…)는 인증을 하지 않고 https://console.hrum.ai/verify-email.html?token=…로 302 리다이렉트만 합니다 — 그 페이지에서 비밀번호를 입력하면 위 POST가 호출됩니다.

조회 API

크레딧 잔액과 사용 현황을 조회하는 API입니다. 헤더에 X-Partner-Api-Key를 포함해야 합니다.

GET /api/v1/partners/v1/credits/balance

현재 크레딧 잔액을 조회합니다.

요청

curl -X GET https://api.hrum.ai/api/v1/partners/v1/credits/balance \
  -H "X-Partner-Api-Key: your-api-key"

응답

{
  "success": true,
  "data": {
    "balanceWon": 25000,
    "lastUpdated": "2026-10-09T05:12:30.000Z",
    "estimatedMonthEndBalance": 15000,
    "warningThreshold": 5000,
    "lowBalanceActive": false
  }
}

warningThreshold는 파트너마다 다릅니다 — max(₩5,000, 최근 유료 충전액의 20%). lowBalanceActive는 잔액이 이 기준 아래로 내려가 저잔액 경고 상태인지입니다. API로 충전하는 엔드포인트는 없습니다 — 충전은 콘솔 > 결제에서 합니다. 이 API만의 에러 코드는 없습니다 — 공통 에러만 나옵니다.

GET /api/v1/partners/v1/usage/logs?limit=50&offset=0

API 호출 기록을 최신순으로 조회합니다. 각 항목은 id·timestamp·endpoint(짧은 이름, 예: manseryeok)·statusCode·costWon·responseTimeMs(현재 항상 null)이고, 해당할 때만 idempotencyKey·model·endUserId·cachedTokens가 붙습니다.

요청 파라미터

요청

curl "https://api.hrum.ai/api/v1/partners/v1/usage/logs?limit=50&offset=0&endpoint=manseryeok" \
  -H "X-Partner-Api-Key: your-api-key"

응답

{
  "success": true,
  "data": {
    "logs": [
      {
        "id": "12345",
        "timestamp": "2026-08-10T14:30:00.000Z",
        "endpoint": "manseryeok",
        "statusCode": 200,
        "costWon": 50,
        "responseTimeMs": null,
        "idempotencyKey": "order-8812"
      }
    ],
    "total": 1234,
    "pagination": {
      "limit": 50,
      "offset": 0,
      "hasMore": true
    }
  }
}

GET /api/v1/partners/v1/usage/summary?dateFrom=2026-08-01&dateTo=2026-08-31

기간별 사용 통계를 조회합니다. 날짜를 생략하면 이번 달 전체입니다. dailyBreakdown의 날짜는 한국 시간(KST) 기준입니다.

요청 파라미터

요청

curl "https://api.hrum.ai/api/v1/partners/v1/usage/summary?dateFrom=2026-08-01&dateTo=2026-08-31" \
  -H "X-Partner-Api-Key: your-api-key"

응답

{
  "success": true,
  "data": {
    "dateRange": { "from": "2026-08-01", "to": "2026-08-31" },
    "totalCalls": 1234,
    "totalCostWon": 6170,
    "byEndpoint": [
      {
        "endpoint": "manseryeok",
        "calls": 1234,
        "costWon": 6170,
        "percentOfTotal": 100
      }
    ],
    "dailyBreakdown": [
      {
        "date": "2026-08-10",
        "calls": 150,
        "costWon": 750
      }
    ]
  }
}

에러 코드 (사용량 로그·요약)

공통 에러 외에, 날짜가 YYYY-MM-DD 형식이 아니거나 limit·offset이 음수면 코드 없는 400입니다. 조회는 무료입니다.

GET /api/v1/partners/v1/status/upstream

HRUM이 쓰는 AI 제공사(OpenAI · Google Gemini · Anthropic Claude)의 공개 상태를 모아 돌려줍니다. API 키가 필요 없고 무료이며, 60초 동안 캐시됩니다. 상태 페이지가 이 값을 씁니다.

curl https://api.hrum.ai/api/v1/partners/v1/status/upstream

{
  "success": true,
  "data": {
    "providers": [
      { "name": "OpenAI", "indicator": "none", "description": "All Systems Operational", "url": "https://status.openai.com", "checkedAt": "2026-10-12T03:00:00.000Z" },
      ...
    ],
    "checkedAt": "2026-10-12T03:00:00.000Z"
  }
}

indicator: none(정상) · minor · major · critical · unknown(상태를 읽지 못함). 이 API만의 에러 코드는 없습니다.

게스트 체험

로그인 없이 사주를 체험할 수 있는 무료 API입니다.

POST /api/v1/partners/v1/playground/manseryeok

인증 없이 만세력을 계산합니다. 게스트 엔드포인트(만세력·네이탈 차트) 합산 IP당 월 5회 무료이며, 초과 시 429 GUEST_QUOTA_EXCEEDED가 반환됩니다.

요청

curl -X POST https://api.hrum.ai/api/v1/partners/v1/playground/manseryeok \
  -H "Content-Type: application/json" \
  -d '{
    "year": 1990,
    "month": 1,
    "day": 15,
    "hour": 14,
    "minute": 30,
    "timezone": "Asia/Seoul",
    "gender": "male"
  }'

응답

유료 만세력 API와 같은 원국·분석 필드(wonkuk·ohaengBalance·yongshin·daeun·seun …)에 남은 횟수 guestRemaining이 data 안에 붙습니다. 음력(calendar·isLeapMonth)·위치 보정(좌표·country)·zaSiRule·birthTimePrecision은 유료와 같이 반영되고, 음력 입력이면 lunarInput이 붙습니다. 체험용이라 lang 번역·glossary와 identity·ohaengDeficient는 붙지 않습니다.

{
  "success": true,
  "data": {
    "wonkuk": {
      "year": { "stem": "기", "branch": "사", "stemHanja": "己", "branchHanja": "巳", ... },
      "month": { ... }, "day": { ... }, "hour": { ... }
    },
    "trueSolarTime": null,
    "ohaengBalance": { ... },
    "yongshin": "...",
    ...,
    "guestRemaining": 4
  }
}

한도 초과 (429)

{
  "success": false,
  "statusCode": 429,
  "code": "GUEST_QUOTA_EXCEEDED",
  "message": "게스트 체험 한도(월 5회)를 초과했습니다. API 키를 발급받아 사용해주세요.",
  "timestamp": "..."
}

에러 코드

POST /api/v1/partners/v1/playground/natal-chart

인증 없이 네이탈 차트를 계산합니다. 요청 본문은 유료 /natal-chart와 같고, 응답도 같은 차트에 guestRemaining이 붙습니다. 풀이 문단(readings)은 제공하지 않습니다. 한도는 만세력 게스트와 합산(IP당 월 5회)입니다.

curl -X POST https://api.hrum.ai/api/v1/partners/v1/playground/natal-chart \
  -H "Content-Type: application/json" \
  -d '{ "birthDate": "1990-05-15", "birthTime": "12:00", "birthLatitude": 37.5665, "birthLongitude": 126.978, "birthTimezoneOffset": 540 }'

{
  "success": true,
  "data": {
    "sun": { ... },
    "moon": { ... },
    ...,
    "guestRemaining": 3
  }
}

에러: 한도 초과 429 GUEST_QUOTA_EXCEEDED, 그 밖에는 공통 에러와 같습니다.

유효값

천간 (Cheongan)

갑, 을, 병, 정, 무, 기, 경, 신, 임, 계

지지 (Jiji)

자, 축, 인, 묘, 진, 사, 오, 미, 신, 유, 술, 해

오행 (Ohaeng)

목(목), 화(불), 토(흙), 금(쇠), 수(물)

말결 (candor)

t, f(기본) — 대소문자는 구분하지 않습니다. 예전 값 blunt는 t로, balanced·gentle은 f로 정규화됩니다. 그 밖의 값은 400 (말결 (가칭))

에러 코드

모든 API는 아래 공통 에러를 같은 방식으로 돌려줍니다. 각 API 절의 에러 표에는 그 API에서만 나오는 코드만 적었습니다. 요청은 다음 순서로 검사되며, 앞 단계에서 걸리면 뒤 단계는 실행되지 않습니다.

1. 서비스 보호 상한 — 같은 IP에서 오는 요청 전체 분당 상한 (429, code 없음)
2. API 키 — X-Partner-Api-Key 확인 (401)
3. 기능 열림 여부 — 계정에 열리지 않은 기능 (404 *_not_enabled)
4. 요청 제한 — 콘솔에서 정한 초당·일일 제한 (429 RATE_LIMIT_EXCEEDED)
5. 본문 검사 — 필드 이름·타입·범위 (400)
6. 잔액·계산·호출 — 잔액 부족(402), API별 입력 오류, 외부 모델 오류

공통 에러

오류 응답 본문 형식: {"success": false, "statusCode": 400, "code": "INVALID_LOCATION", "message": "...", "timestamp": "..."} — code는 있을 때만 붙습니다. 분기는 statusCode와 code로 하고, message 문구에 의존하지 마세요.

// 401 — 키 누락·오류
{ "success": false, "statusCode": 401, "message": "Invalid or missing API key", "error": "Unauthorized", "timestamp": "2026-10-12T03:00:00.000Z" }

// 400 — 본문 검사 실패 (message는 배열)
{ "success": false, "statusCode": 400, "message": ["property foo should not exist", "month must not be greater than 12"], "error": "Bad Request", "timestamp": "2026-10-12T03:00:00.000Z" }

// 404 — 계정에 열리지 않은 기능
{ "success": false, "statusCode": 404, "code": "ziwei_not_enabled", "message": "아직 열리지 않은 기능입니다", "timestamp": "2026-10-12T03:00:00.000Z" }

// 429 — 콘솔에서 정한 요청 제한
{ "success": false, "statusCode": 429, "code": "RATE_LIMIT_EXCEEDED", "message": "초당 요청 제한을 초과했습니다. 콘솔 > API 키 > 요청 제한에서 조정할 수 있습니다.", "retryAfterSeconds": 1, "timestamp": "2026-10-12T03:00:00.000Z" }

API별 코드 가운데 자주 보는 것: 422 처리할 수 없는 입력(PROMPT_TOO_LONG, EXTRACTION_FAILED), 503 일시적으로 이용 불가(예: 풀이 문단을 불러오지 못함, 과금 없음), 504 외부 모델 시간 초과. 게스트 체험 한도는 429 GUEST_QUOTA_EXCEEDED입니다.

Rate Limit

서비스 보호용 상한이 항상 걸려 있습니다: API 키당 분당 300회(같은 IP에서 오는 키 요청 전체는 분당 3,000회). 넘으면 429가 반환되며, 이 경우 응답에 code와 Retry-After가 없습니다 — 잠시 뒤(최대 1분) 다시 시도하세요. 이보다 낮은 제한은 파트너가 직접 정합니다 — 콘솔 API 키 > 요청 제한에서 초당 요청과 일일 요청(KST 기준)을 설정하면 키 유출이나 무한 루프로부터 잔액을 지킬 수 있습니다. 비워 두면 위 서비스 보호 상한만 적용됩니다.

• 제한을 설정하면 응답에 X-RateLimit-Limit-Second / X-RateLimit-Remaining-Second / X-RateLimit-Limit-Day / X-RateLimit-Remaining-Day 헤더가 붙습니다.
• 파트너가 설정한 제한을 넘으면 429 + {"code":"RATE_LIMIT_EXCEEDED","retryAfterSeconds":N}, Retry-After 헤더. 차단된 요청은 과금하지 않습니다.
• 게스트(키 없음)는 월 5회 무료 테스트로 고정됩니다.

과금

모든 API 호출은 크레딧에서 차감됩니다. 신규 가입 시 무료 ₩1,000 크레딧을 제공합니다(부정 가입 방지 조건에 걸리면 지급이 보류될 수 있습니다). 게스트는 월 5회까지 무료로 테스트 가능합니다.

게스트 테스트

• 만세력·네이탈 차트 게스트 엔드포인트: 합산 월 5회 무료 (IP 기반 제한)
• 로그인 없이 플레이그라운드에서 테스트 가능
• 잔여 횟수는 응답에 포함됨 (guestRemaining)

멱등성

모든 성공한 요청은 각각 과금됩니다. 같은 요청을 다시 보내면 다시 계산·생성하고 다시 과금하므로, 재시도 중복이나 동일 입력의 재사용은 클라이언트가 응답을 저장해 처리하세요 (예: 요청 해시를 키로 한 캐시).

X-Idempotency-Key 헤더(최대 128자 — 더 길면 앞 128자만 기록)는 여전히 받을 수 있지만 과금을 막지 않습니다. 보낸 키는 사용량 로그의 idempotencyKey에 그대로 기록되어, 어떤 요청이 어떤 호출로 처리됐는지 파트너 쪽 주문·작업 ID와 대조하는 용도로 쓸 수 있습니다.

지원

연동 중 막히는 부분이나 응답이 문서와 다른 경우 알려주세요.

문의 시 아래를 함께 보내주시면 확인이 빠릅니다.

• 호출한 엔드포인트와 시각(타임존 포함)
• API 키 앞 12자리 (float_live_ 포함, 전체 키는 절대 보내지 마세요)
• 받은 응답의 HTTP 상태코드와 본문

약관·개인정보 처리에 관한 사항은 이용약관과 개인정보처리방침을 참고하세요.