만세력·운세 API 문서.
v5.0 Sandbox 현재 제공 · 신규 유료 요금 2026.12.01 적용 예정
상품 안내는 2026.10.12 개정 한국어 소개서 v5.0을 기준으로 합니다. 신규 고객은 지금 v5.0 기준의 승인형 Sandbox를 신청할 수 있습니다. 신규 정식 유료 가입은 2026년 12월 1일 전까지 대기 상태입니다. 신규 유료 요금은 2026년 12월 1일 적용 예정이며, 기존 요금제로는 신규 가입을 받지 않습니다. 기존 고객의 이용 조건과 전환은 개별 계약 및 별도 안내를 따릅니다. 이 기술 문서의 API 경로와 요청·응답 예제는 기존 v2 기준입니다.
상품 소개 문서는 v5.0이며 실제 API는 기존 /api/v2/ 경로를 유지합니다. 문서 버전과 API 버전은 별개입니다.
API 고객 소개서 v5.0 · 12월 1일 적용 예정
만세력 API와 사주 API를 앱·웹 서비스에 연동하기 위한 개발 문서입니다.
인증, 요청 파라미터, JSON 응답, 신살 옵션, 비동기 분석, 오류 코드와 테스트 키 신청 방법을 확인하세요.
인증
API 키
승인된 상품과 사용 범위에 맞춰 발급합니다. 키는 서버에서 관리합니다.
계산 데이터
GET 조회
Core와 전문 만세력+SIS는 같은 경로를 사용하며 키 권한으로 제공 필드를 구분합니다.
맞춤 해설
POST + Callback
요청 접수 응답과 최종 분석 결과를 구분해 처리합니다.
가용성, 지원 시간과 장애 대응 범위는 계약별 SLA로 정합니다.
만세력 & 신살 API v2 연동 기준
- 현재 문서는 v2 전용 기준으로 안내합니다.
- 모든 신규 테스트키와 정식키는
/api/v2/...경로 기준으로 발급됩니다. - 비동기 분석 계열은
POST요청 후X-Callback-URL로 결과를 전달받습니다. - 궁합(2인)처럼 입력 구조가 다른 API는 별도 예제를 먼저 확인해 주세요.
첫 조회 준비
API 키와 첫 조회 준비
Ablecity 사주 API는 v2 전용 문서 기준으로 연동합니다. 먼저 API 키를 준비하고, 동기 GET 호출과 비동기 POST+Callback 호출의 차이를 확인하세요.
1. API 키 준비
모든 요청은 Authorization: Bearer <API_KEY> 헤더를 사용합니다.
키를 받은 뒤에는 API Dashboard에서 회원가입 후 사용량, 구독, API 조회를 확인할 수 있습니다.
2. 단일 조회는 GET
기본 만세력 조회는 호출 즉시 JSON 결과를 반환합니다.
3. 심화 분석은 POST + Callback
궁합, 작명, 재물운 등은 요청 접수 후 callback URL로 최종 결과를 전송합니다.
기본 만세력 조회 예시
curl -X GET \
"https://api.ablecity.kr/api/v2/saju/fortune?birth=1990-01-01T01:00:00&gender=male&city=서울특별시&calendar=solar&midnightType=0" \
-H "Authorization: Bearer <API_KEY>" \
-H "Accept: application/json"만세력·운세 API
상품 범위와 키 권한
v5.0 기준의 상품 제공 범위입니다. 만세력 Core는 원국·오행·십성·십이운성·대운 등 계산 데이터만 반환합니다. 전문 만세력+SIS는 Core 전체에 강약·격국·용신·지지 관계·공망과 신살 54종의 위치·상태·영향도 데이터를 더합니다. 기존 고객의 제공 항목은 현재 계약과 신규 상품의 데이터를 비교한 뒤 별도로 전환을 안내합니다. 기존 Core의 전문 분석 항목은 신규 Core의 포함 항목과 구분해 확인합니다.
두 상품은 기존 GET /api/v2/saju/fortune 엔드포인트를 공유하며 API 키 권한으로 제공 범위를 구분합니다. 아래 통합 필드·응답 예시는 해당 권한이 승인된 경우의 구조이며 Core에 모든 전문 필드가 포함된다는 뜻은 아닙니다. SIS 상대강도는 통계 확률이 아닌 내부 지수입니다.
만세력·운세 API
30일 승인형 Sandbox
신규 고객은 지금 v5.0 기준의 승인형 Sandbox를 신청할 수 있습니다. 30일 제공량은 콘텐츠 100회, Core/전문 만세력+SIS 합산 1,000회, 표준 결과 합산 20회, 생성형 Callback 완료 결과 5건입니다. 신규 정식 유료 가입은 2026년 12월 1일 전까지 대기 상태입니다. 테스트용이며 상업 서비스나 최종 사용자에게 제공할 수 없습니다. 실제 기간·제품·한도는 승인 후 발급 안내에서 확인합니다. 내부 테스트 상품의 승인 범위는 별도로 확인합니다.
제출 후 영업일 기준 1일 이내 1차 검토 결과와 발급 범위를 이메일로 안내합니다. API 키는 승인된 제품과 사용 범위에 한해 별도 이메일로 발급합니다.
2026년 12월 1일 적용 예정 PAYG는 콘텐츠·리텐션 20P/건, 만세력 Core 90P/건, 전문 만세력+SIS 150P/건입니다. 1P=1원, VAT 별도이며 한국어 표준 범위 기준입니다. Starter는 월 500건에 Core 30,000원, 전문 만세력+SIS 50,000원입니다. 전문 만세력+SIS Launch는 월 2,000건에 89,000원입니다. 전체 요금과 해설·전문 결과 단가는 요금 페이지에서 확인하세요.
월정액 초과 단가와 사용 한도, 미사용 포함량의 이월 여부, 요금제 변경·해지의 적용일, 결제일과 일할 계산은 Live 키 발급 전 견적·계약에서 정합니다. 표에 적힌 PAYG 단가가 월정액 초과 요금으로 자동 적용되지는 않습니다.
Sandbox 키 발급 후 Dashboard에 계정을 등록해 사용량을 확인할 수 있습니다. 신규 정식 유료 가입은 2026년 12월 1일 전까지 대기 상태이며, Sandbox 키 발급이 유료 가입이나 포인트 충전의 시작을 뜻하지는 않습니다. 포인트 충전과 유료 이용은 정식 이용 단계에서 안내합니다. 기존 유료 고객은 현재 계약에 따라 이용합니다.
Sandbox 키는 자동으로 Live 키로 바뀌지 않습니다. 실제 서비스나 최종 사용자에게 제공하기 전에 사용할 API·요금·적용 화면·예상 호출량·출시일을 확인하고 별도 Live 키를 발급받아야 합니다.
만세력·운세 API
기존 운영 API와 내부 테스트 상품
기존 맞춤 해설은 현재 POST + Callback 계약을 유지합니다. 표준 해설은 내부 테스트 중이며 승인형 PoC로 문의할 수 있습니다. 표준 해설의 즉시 응답은 테스트 상품의 제공 방식으로, 기존 Callback 엔드포인트가 동기형으로 변경된다는 뜻이 아닙니다.
내부 테스트 중 · 승인형 PoC 문의
다음 경로는 제품 검토용 예정 명세이며 실행 가능한 공개 API 예제가 아닙니다. 승인 후 실제 경로·입력·응답 범위를 별도로 안내합니다. 기존 작명 경로는 유지하되 작명 상품은 내부 테스트 대상으로 안내합니다.
| 상품 | 경로 | 상태 |
|---|---|---|
| 표준 해설 | /api/v2/saju/fortune/standard/{product} | 예정 경로 · 변경 가능 · 일반 호출 불가 |
| 토정비결 | /api/v2/saju/fortune/tojeong | 예정 경로 · 변경 가능 · 일반 호출 불가 |
| 맞춤 택일 | /api/v2/saju/fortune/request-analysis/date-selection | 예정 경로 · 변경 가능 · 일반 호출 불가 |
| 작명 표준·프리미엄 내부 테스트 중 · 승인형 PoC 문의 | /api/v2/saju/fortune/request-analysis/naming | 기존 경로 유지 · 내부 테스트 · 승인 필요 |
| 별자리운세 | /api/v2/saju/fortune/star-sign-luck | 예정 경로 · 변경 가능 · 일반 호출 불가 |
| 바이오리듬 | /api/v2/saju/fortune/biorhythm | 예정 경로 · 변경 가능 · 일반 호출 불가 |
표준 해설의 예정 하위 경로: week-luck, this-year-luck, telling, match, love-luck, rich-luck.
1. 인증
모든 API 요청에는 HTTP Header에 Bearer Token을 포함해야 합니다. API 키는 서버 측에서 관리하고, 클라이언트 앱에 직접 노출하지 않는 것을 기본 원칙으로 둡니다.
Authorization: Bearer <API_KEY>30일 Sandbox는 상단의 신청 버튼에서 접수합니다. API 키 발급은 제품별 승인 범위에 따릅니다.
운영 기준
연동 전에는 인증, 사용량, 요금제와 모니터링 범위를 확인합니다. 운영 기준은 트래픽 규모와 계약 범위에 맞춰 별도 검증합니다.
| 운영 항목 | 기본 확인 기준 | Ablecity 문서/상담 기준 |
|---|---|---|
| 응답 구조 | 성공·오류 응답 형식 확인 | REST JSON 응답 기준 |
| 사용량 관리 | 키별 사용량 확인 | 키별 요청량·월별 사용량 기준 |
| 도메인 필드 | 상품별 제공 필드 확인 | 사주표, 오행, 신살, 공망 등 구조화 필드 |
| 연동 방식 | 요청·최종 결과 전달 방식 확인 | 동기 GET + 비동기 POST/Callback 구분 |
| 운영 지원 | 지원 시간·대응 범위 확인 | 계약 범위에 따른 SLA 옵션 제공 |
2. 공통 응답 형식
모든 endpoint는 성공과 오류를 같은 top-level JSON envelope로 반환합니다. 클라이언트에서는 status, data, message를 기준으로 일관되게 처리하면 됩니다.
{
"status": "success",
"data": ...,
"message": "..."
}3. 요청 경로
신규 테스트키와 정식키는 v2 endpoint 기준으로 발급됩니다. 단일 조회는 GET, 분석형 요청은 POST + callback 구조를 사용합니다.
3.1 GET /api/v2/saju/fortune
v2 조회
사용자의 생년월일·출생 시각(birth), 성별(gender),
(선택) 태어난 도시(city), 자정 처리 방식, 사용 달력을 기반으로
만세력(사주팔자), 오행, 격국, 용신, 대운, 띠 궁합, 공망, 신살까지 v2 기준으로 계산합니다.
v5.0 기준의 상품 제공 범위입니다. 만세력 Core는 원국·오행·십성·십이운성·대운 등 계산 데이터만 반환합니다. 전문 만세력+SIS는 Core 전체에 강약·격국·용신·지지 관계·공망과 신살 54종의 위치·상태·영향도 데이터를 더합니다. 기존 고객의 제공 항목은 현재 계약과 신규 상품의 데이터를 비교한 뒤 별도로 전환을 안내합니다. 기존 Core의 전문 분석 항목은 신규 Core의 포함 항목과 구분해 확인합니다.
두 상품은 기존 GET /api/v2/saju/fortune 엔드포인트를 공유하며 API 키 권한으로 제공 범위를 구분합니다. 아래 통합 필드·응답 예시는 해당 권한이 승인된 경우의 구조이며 Core에 모든 전문 필드가 포함된다는 뜻은 아닙니다. SIS 상대강도는 통계 확률이 아닌 내부 지수입니다.
v2 사용 기준
- 신규 테스트키/정식키는 모두
GET /api/v2/saju/fortune기준으로 제공됩니다. - 현재 문서는
v2기준으로만 요청 경로, 파라미터, 응답 예시를 안내합니다. - 응답은
status,message,data구조를 그대로 유지하므로 기존 JSON 처리 패턴을 재사용하기 쉽습니다.
신살(SIS) 옵션 안내
- 기본 만세력 조회는 신살(SIS)을 제외하고 반환합니다.
- SIS(신살) 포함은 API 키 발급 신청 시 별도 신청/승인이 필요합니다. 승인된 API Key에는
sinsal,relations_ui,gongmang등이 포함됩니다. - v2 문서에는 실제 서비스에서 활용하는 공개 필드만 안내합니다. 엔진 내부 디버그용 필드는 문서에서 제외했습니다.
cURL 예제
curl -X GET \
"https://api.ablecity.kr/api/v2/saju/fortune?birth=1990-01-01T01:00:00&gender=male" \
-H "Authorization: Bearer <API_KEY>" \
-H "Accept: application/json"Python 예제
import requests
url = "https://api.ablecity.kr/api/v2/saju/fortune"
params = {
"birth": "1990-01-01T01:00:00",
"gender": "male",
"city": "서울특별시",
"calendar": "solar"
}
headers = {"Authorization": "Bearer <api_key>"}
response = requests.get(url, params=params, headers=headers)
print(response.json())Node.js 예제
const axios = require('axios');
const config = {
method: 'get',
url: 'https://api.ablecity.kr/api/v2/saju/fortune',
params: {
birth: '1990-01-01T01:00:00',
gender: 'male',
city: '서울특별시'
},
headers: {
'Authorization': 'Bearer <api_key>'
}
};
axios(config)
.then((res) => console.log(JSON.stringify(res.data, null, 2)))
.catch((err) => console.error(err));Java 예제
OkHttpClient client = new OkHttpClient();
HttpUrl url = HttpUrl.parse("https://api.ablecity.kr/api/v2/saju/fortune").newBuilder()
.addQueryParameter("birth", "1990-01-01T01:00:00")
.addQueryParameter("gender", "male")
.build();
Request request = new Request.Builder()
.url(url)
.addHeader("Authorization", "Bearer <api_key>")
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
* midnightType(0:야자/조자 분리)과 calendar(solar:양력)는 미입력 시 기본값으로 처리됩니다.
요청 매개변수
| Name | Type | Required | Description |
|---|---|---|---|
| birth | string | Yes |
태어난 시간. yyyy-MM-ddTHH:mm:ss 형식만 지원합니다. 날짜와 시간 사이에는 대문자 T만 허용하며, 공백이나 소문자 t는 허용하지 않습니다.
|
| gender | string | Yes |
성별. 남자: male, 여자: female (그 외 값 오류)
|
| city | string | Optional |
태어난 도시 (LMT 보정용). 미입력 시 서울특별시 기준. 지원 도시는 아래 목록 참고. |
| midnightType | integer | Optional |
0: 야자/조자 분리 (기본값)1: 정자시 방식 (23:00~00:59를 모두 익일로 처리)
|
| calendar | string | Optional |
solar(양력, 기본값), lunar(음력), leap(윤달)
|
📍 사주 API 지원 도시 목록 (city) 전체 보기 ▼
표기 예: city=서울특별시
응답 예시
만세력 기본 응답 예제
{
"status": "success",
"message": "요청이 완료되었습니다.",
"data": {
"year": {
"branch_element": "earth",
"branch_polarity": "yang",
"branch_sipseong": "정인",
"stem_polarity": "yang",
"stem_sipseong": "정인",
"hangul": "무진",
"hanja": "戊辰",
"stem_element": "earth"
},
"month": {
"branch_element": "water",
"branch_polarity": "yang",
"branch_sipseong": "식신",
"stem_polarity": "yang",
"stem_sipseong": "정재",
"hangul": "갑자",
"hanja": "甲子",
"stem_element": "wood"
},
"day": {
"branch_element": "earth",
"branch_polarity": "yin",
"branch_sipseong": "편인",
"stem_polarity": "yin",
"stem_sipseong": "비견",
"hangul": "신축",
"hanja": "辛丑",
"stem_element": "metal"
},
"hour": {
"branch_element": "water",
"branch_polarity": "yang",
"branch_sipseong": "식신",
"stem_polarity": "yang",
"stem_sipseong": "정인",
"hangul": "무자",
"hanja": "戊子",
"stem_element": "earth"
},
"fortune": 8,
"hehua": {
"effective": [],
"failed": [],
"applied_true": false,
"applied_pseudo": false,
"applied_any": false,
"applied": false,
"five_before_pct": {
"earth": 32.8,
"metal": 11,
"fire": 0,
"wood": 12.6,
"water": 43.6
},
"five_after_pct": {
"earth": 32.8,
"metal": 11,
"fire": 0,
"wood": 12.6,
"water": 43.6
},
"five_changed": false,
"strength_before": "balanced",
"strength_after": "balanced",
"strength_changed": false,
"yongshin_changed": false
},
"five_pct": {
"earth": 32.8,
"metal": 11,
"fire": 0,
"wood": 12.6,
"water": 43.6
},
"five_star": {
"earth": "★★★★☆",
"metal": "★☆☆☆☆",
"fire": "★☆☆☆☆",
"wood": "★☆☆☆☆",
"water": "★★★★★"
},
"five_kor": {
"목(木)": 1.3,
"금(金)": 1.13,
"토(土)": 3.38,
"화(火)": 0,
"수(水)": 4.49
},
"twelve_growth": { "month": "長生", "hour": "長生", "year": "墓", "day": "養" },
"twelve_growth_kor": { "month": "장생", "hour": "장생", "year": "묘", "day": "양" },
"strength": "balanced",
"geokguk": {
"geok": "식신격",
"geok_kor": "식신격",
"geok_detail": null,
"is_follower": false,
"follower_candidate": false,
"variant_signal": false
},
"yongshin": {
"primary": "fire",
"primary_kor": "화(火)",
"secondary": "earth",
"secondary_kor": "토(土)"
},
"branch_relations": {
"harmonies": ["子-丑", "丑-子"],
"breaks": ["辰-丑"],
"clashes": [],
"punishments": [],
"harms": [],
"wonjins": [],
"half_three_harmonies": ["子-辰"]
},
"branch_relations_kor": {
"harmonies": ["자-축", "축-자"],
"breaks": ["진-축"],
"clashes": [],
"punishments": [],
"harms": [],
"wonjins": [],
"half_three_harmonies": ["자-진"]
},
"relations_ui": {
"summary": {
"harmony_count": 2,
"tension_count": 2,
"special_count": 1,
"top_alert": "공망"
},
"items": [
{
"key": "branch_harmony",
"label": "지지육합",
"group": "harmony",
"tone": "good",
"count": 2,
"tokens": ["子-丑 (자-축)", "丑-子 (축-자)"]
},
{
"key": "gongmang",
"label": "공망",
"group": "tension",
"tone": "warn",
"count": 2,
"tokens": ["공망지 辰巳 (진사)", "원국 포함 辰 (진)"]
}
],
"gongmang": {
"day_pillar": "辛丑",
"xun_start": "甲午",
"void_branches": ["辰", "巳"],
"void_branches_kor": ["진", "사"],
"present_branches": ["辰"],
"present_branches_kor": ["진"]
}
},
"big_luck": [
{ "age_range": "8–17", "year_range": "1996–2005", "pillar": "乙丑", "pillar_kor": "을축" },
{ "age_range": "18–27", "year_range": "2006–2015", "pillar": "丙寅", "pillar_kor": "병인" },
{ "age_range": "28–37", "year_range": "2016–2025", "pillar": "丁卯", "pillar_kor": "정묘" }
],
"first_big_luck": "을축",
"lucky": {
"good_num": 2,
"bad_num": 7,
"good_dir": "서쪽",
"bad_dir": "동쪽",
"need_elem": "fire",
"need_elem_kor": "화(火)"
},
"summary": {
"pillars": "무진년 갑자월 신축일 무자시",
"strength": "중화(中和)",
"zodiac": "용띠"
},
"zodiac_compatibility": [
{
"score": 95,
"grade": "best",
"animal": "쥐",
"branch": "子",
"relation": "삼합(三合)",
"desc": "서로 부족한 점을 채워주는 최상의 궁합입니다."
},
{
"score": 20,
"grade": "bad",
"animal": "개",
"branch": "戌",
"relation": "충(沖)",
"desc": "서로 부딪히는 기운으로, 갈등에 주의가 필요합니다."
}
],
"sinsal": [
{
"sis_code": "S005",
"name_kr": "공망",
"name_en": "The Void (Null State)",
"chart_vector": {
"creativity": 100,
"material_luck": 79,
"reality_grip": 74,
"reversal_potential": 95,
"spiritual_depth": 100
},
"attributes": {
"affected_element": "재성 (Wealth)",
"void_type": "진사공망 (Dragon/Snake Void)",
"positions": ["year"],
"manifest_label": "년주(태어난 해)",
"resolved_by_combine": true
},
"final_verdict": {
"grade": "S_ACTIVE",
"keyword": "채워질 준비가 된 그릇",
"description": "공망이 합 작용으로 해공된 상태입니다.",
"advice": "협업과 관계 조정을 활용해 공백 리스크를 줄이는 편이 좋습니다."
},
"beginner_explanation": "공망이 합 작용으로 해공된 상태이며, 급격한 붕괴보다 완충 흐름이 우세합니다.",
"is_present": true
}
],
"gongmang": {
"sinsals": [
{
"name": "공망",
"score": 6,
"desc": "[수(水)]비움과 채움의 미학. 해당 궁위의 결핍.",
"relatedChar": "辰",
"positions": ["YEAR"],
"is_present": true
}
],
"present_branches": ["辰"],
"hanja": ["辰", "巳"],
"hangul": ["진", "사"]
}
}
}오늘 운세 응답 예제
{
"status": "success",
"message": "요청이 완료되었습니다.",
"data": {
"date": "2026-01-10",
"summary": {
"exam": "평이한 흐름입니다. 성실함이 기회를 만듭니다. 합(合) 기운을 활용해 주변과 협력하면 개선될 수 있습니다.",
"wealth": "평이한 흐름입니다. 성실함이 기회를 만듭니다. 합(合) 기운을 활용해 주변과 협력하면 개선될 수 있습니다.",
"marriage": "평이한 흐름입니다. 성실함이 기회를 만듭니다. 합(合) 기운을 활용해 주변과 협력하면 개선될 수 있습니다.",
"contract": "평이한 흐름입니다. 성실함이 기회를 만듭니다. 합(合) 기운을 활용해 주변과 협력하면 개선될 수 있습니다.",
"childbirth": "변수가 많은 날입니다. 지나친 모험은 삼가세요. 합(合) 기운을 활용해 주변과 협력하면 개선될 수 있습니다.",
"health": "변수가 많은 날입니다. 지나친 모험은 삼가세요. 합(合) 기운을 활용해 주변과 협력하면 개선될 수 있습니다.",
"employment": "평이한 흐름입니다. 성실함이 기회를 만듭니다. 합(合) 기운을 활용해 주변과 협력하면 개선될 수 있습니다.",
"relationship": "변수가 많은 날입니다. 지나친 모험은 삼가세요. 합(合) 기운을 활용해 주변과 협력하면 개선될 수 있습니다.",
"accident": "평이한 흐름입니다. 성실함이 기회를 만듭니다. 합(合) 기운을 활용해 주변과 협력하면 개선될 수 있습니다.",
"promotion": "평이한 흐름입니다. 성실함이 기회를 만듭니다. 합(合) 기운을 활용해 주변과 협력하면 개선될 수 있습니다."
},
"scores": {
"exam": 57,
"wealth": 67,
"marriage": 66,
"contract": 64,
"childbirth": 53,
"health": 42,
"employment": 64,
"relationship": 51,
"accident": 55,
"promotion": 60
},
"stars": {
"exam": "★★★☆☆",
"wealth": "★★★☆☆",
"marriage": "★★★☆☆",
"contract": "★★★☆☆",
"childbirth": "★★★☆☆",
"health": "★★☆☆☆",
"employment": "★★★☆☆",
"relationship": "★★★☆☆",
"accident": "★★★☆☆",
"promotion": "★★★☆☆"
}
}
}주간 운세 응답 예제
{
"status": "success",
"message": "요청이 완료되었습니다.",
"data": {
"traceId": "4ea84d94-258f-41f1-b14d-a5173c359bb2",
"result": {
"user_info": {
"manse": "경진년 경진월 기해일 갑자시",
"gender": "여성",
"birth_year": "2000년",
"daeun": "2세 시작, 10년 주기"
},
"week_info": {
"range": "2026-01-04 ~ 2026-01-10",
"labels": ["4(일)", "5(월)", "6(화)", "7(수)", "8(목)", "9(금)", "10(토)"]
},
"sections": [
{
"id": 1, "key": "general", "title": "총론",
"daily": [
{ "label": "4(일)", "fortune": "생각이 많아지기 쉬운 날이라, 결론을 급히 내리기보다 정리부터 하시면 좋겠습니다..." },
{ "label": "5(월)", "fortune": "일의 우선순위를 세우면 성과가 빠르게 보이는 날입니다..." },
{ "label": "6(화)", "fortune": "사람과의 조율이 핵심인 날입니다. 내 기준을 고집하기보다..." },
{ "label": "7(수)", "fortune": "작은 성취가 쌓이는 흐름이라 꾸준함이 힘이 됩니다..." },
{ "label": "8(목)", "fortune": "새로운 제안이나 아이디어가 들어오기 쉬운 날입니다..." },
{ "label": "9(금)", "fortune": "정리와 마무리에 강한 날이라 미뤄둔 일을 끝내기 좋습니다..." },
{ "label": "10(토)", "fortune": "휴식과 재충전이 필요한 날입니다..." }
]
},
{ "id": 2, "key": "wealth", "title": "재물운", "daily": [ ... ] },
{ "id": 3, "key": "lotto", "title": "로또운", "daily": [ ... ] },
{ "id": 4, "key": "love", "title": "애정운", "daily": [ ... ] },
{ "id": 5, "key": "health", "title": "건강운", "daily": [ ... ] }
]
}
}
}올해 운세 응답 예제
{
"status": "success",
"message": "요청이 완료되었습니다.",
"data": {
"traceId": "86baf4ed-f355-48d2-86b4-706ecb72a9e3",
"result": {
"user_info": {
"manse": "경진년 경진월 기해일 갑자시",
"gender": "여성",
"birth_year": 2000,
"daeun": "정축(丁丑) 대운 (2022–2031, 5년차)"
},
"year_info": { "year_label": "2026년 (병오년)" },
"general": { "title": "총론", "content": "2026년 병오년은 하늘도 땅도 ‘불(丙午)’이라..." },
"wealth": { "title": "재물운", "content": "기해일주(己亥) 기준으로 물(水)은 재성인데..." },
"career_business": { "title": "직장 / 사업운", "content": "원국에서 관성(규칙·직장·평가)은 시간의..." },
"family_health": { "title": "가정 / 건강운", "content": "오행 분포에서 화(火)가 비어 있고..." },
"relationship": { "title": "이성 / 대인관계", "content": "올해는 화(火)가 강해지며..." },
"monthly_fortunes": [
{ "month": 1, "label": "1월", "fortune": "기축월은 토(土)가 강해 계획은 세워지지만..." },
{ "month": 2, "label": "2월", "fortune": "경인월은 목(木)이 살아나며..." },
{ "month": 3, "label": "3월", "fortune": "신묘월은 목 기운이 더 선명해져..." },
{ "month": 4, "label": "4월", "fortune": "임진월은 원국의 辰과 겹치며..." },
{ "month": 5, "label": "5월", "fortune": "계사월은 불(火)의 문이 열리며..." },
{ "month": 6, "label": "6월", "fortune": "갑오월은 화가 절정이라..." },
{ "month": 7, "label": "7월", "fortune": "을미월은 화의 열기가 토로 내려앉아..." },
{ "month": 8, "label": "8월", "fortune": "병신월은 병화가 다시 강해지며..." },
{ "month": 9, "label": "9월", "fortune": "정유월은 관계의 합(六合) 기운이 살아나..." },
{ "month": 10, "label": "10월", "fortune": "무술월은 토가 강해지며..." },
{ "month": 11, "label": "11월", "fortune": "기해월은 원국의 亥와 겹쳐..." },
{ "month": 12, "label": "12월", "fortune": "경자월은 子가 겹치며..." }
]
}
}
}정통 사주 응답 예제
{
"status": "success",
"message": "요청이 완료되었습니다.",
"data": {
"traceId": "fa94d892-e635-4f75-8221-343e977583ee",
"result": {
"user_info": { "manse": "...", "daeun": "..." },
"sections": [
{ "id": 1, "key": "manse_daeun_ilgan", "title": "1. 만세력·대운·일간 성향", "content": "일간은 기토(己) 성향으로..." },
{ "id": 2, "key": "ohaeng", "title": "2. 오행 분석", "content": "토(土)가 강하고 화(火)가 0에 가까워...", "ohaeng_stars": [ ... ] },
{ "id": 3, "key": "sipseong_personality", "title": "3. 십성 & 개인 성향", "content": "격국은 겁재격으로..." },
{ "id": 4, "key": "sinsal", "title": "4. 신살 분석", "content": "지지 관계에서 ‘辰-自刑(진 자형)’이 핵심..." },
{ "id": 5, "key": "daeun_seun_flow", "title": "5. 대운·세운 흐름", "content": "2025년은 ‘정리와 점검’ 관점이..." },
{ "id": 6, "key": "job_business", "title": "6. 직장·사업운", "content": "정관이 시주에 있어..." },
{ "id": 7, "key": "wealth_invest", "title": "7. 재물·투자운", "content": "재성(정재·편재)이 함께 있어..." },
{ "id": 8, "key": "love_marriage", "title": "8. 연애·결혼운", "content": "독립성이 강한 구조라..." },
{ "id": 9, "key": "health_mental", "title": "9. 건강·멘탈운", "content": "화(火) 부족은 체온·순환..." },
{ "id": 10, "key": "zodiac_compat", "title": "10. 띠 궁합", "content": "데이터상 궁합이 가장 좋은 띠는..." }
]
}
}
}애정운 응답 예제
{
"status": "success",
"message": "요청이 완료되었습니다.",
"data": {
"traceId": "e14ad1c0-...",
"result": {
"user_info": { ... },
"year_info": { "year_label": "2026년" },
"love_summary": {
"title": "2026년 반쪽찾기 총론",
"overall_score": 4,
"keyword": "관계가 ‘정리’되며, 진짜 인연이 남는 해",
"content": "2026년은 겉으로는 조용해 보여도..."
},
"confession_guide": {
"title": "사랑고백·프러포즈하기 좋은달",
"content": "2026년의 고백은 ‘감정의 폭발’보다..."
},
"monthly_love": [
{ "month": 1, "label": "1월", "score": 3, "keyword": "호감은 생기지만...", "fortune": "새 인연은 들어오지만..." },
{ "month": 2, "label": "2월", "score": 2, "keyword": "오해가 커지기 쉬운 때", "fortune": "상대의 말 한마디를..." },
... (3~12월 데이터 포함) ...
]
}
}
}재물운 응답 예제
{
"status": "success",
"message": "요청이 완료되었습니다.",
"data": {
"traceId": "d1342655-...",
"result": {
"user_info": { ... },
"year_info": { "year_label": "2026년" },
"summary": { "title": "2026년 부자되기 총론", "content": "사주 전체로는 토(土) 기운이..." },
"wealth_overview": { "title": "2026년 재물운", "content": "2026년은 수입 기회가 늘어나는..." },
"monthly_strategy": { "title": "2026년 부자되기 월별 활용법", "content": "상반기에는 기반을 다지고..." },
"monthly_fortunes": [
{ "month": 1, "label": "1월", "score": 3, "keyword": "새해 예산을 세우면...", "fortune": "초반에는 수입보다..." },
... (2~12월 데이터 포함) ...
]
}
}
}처음 쓰는 개발자를 위한 읽는 순서
data.summary부터 읽으면 사람이 바로 이해할 수 있는 핵심 요약을 먼저 보여줄 수 있습니다.data.year / month / day / hour는 사주 원국 4기둥입니다. 표나 카드 UI를 만들 때 가장 먼저 매핑하는 필드입니다.data.five_pct와data.five_star는 오행 분포를 시각화할 때 사용할 수 있습니다. 차트, 막대그래프, 배지 UI에 활용할 수 있습니다.data.yongshin,data.strength,data.geokguk은 해석형 서비스의 핵심 요약 변수입니다.data.big_luck와data.lucky는 대운 타임라인, 추천 방향/숫자 같은 부가 UI에 적합합니다.data.sinsal,data.relations_ui,data.gongmang는 신살 옵션 승인 시 활용하는 심화 데이터입니다.
주요 필드 설명
사주 기둥 (year, month, day, hour)
hangul, hanja, 천간/지지 오행, 음양, 십성 정보가 함께 들어갑니다. 사주표를 그릴 때 사용하는 필드입니다.
운세 점수 (fortune)
전체 흐름을 빠르게 요약하는 숫자입니다. 목록형 카드나 간단한 요약 배지에 붙이기 좋습니다.
오행 분포 (five_pct, five_star, five_kor)
퍼센트, 별점, 한글 키 버전을 함께 제공합니다. 차트나 설명문에 필요한 형태를 선택할 수 있습니다.
합화 분석 (hehua)
합화가 실제로 적용됐는지, 적용 전후 오행 비율과 강약이 바뀌었는지를 확인하는 영역입니다.
강약 / 격국 / 용신
strength, geokguk, yongshin은 해석형 콘텐츠에 사용할 수 있는 강약·격국·용신 정보입니다.
지지 관계 (branch_relations, relations_ui)
합·충·형·해·파 같은 관계를 원본 배열과 UI 친화 요약 두 가지 방식으로 제공합니다.
대운 / 행운 정보
big_luck, first_big_luck, lucky는 타임라인, 추천 방향, 숫자 UI를 구성할 때 유용합니다.
신살 / 공망 / 띠 궁합
sinsal, gongmang, zodiac_compatibility는 해석 콘텐츠와 관계형 기능을 확장할 때 바로 활용할 수 있습니다.
v2 주요 필드 상세
| Field | Type | Description |
|---|---|---|
| year / month / day / hour | Object | 각 기둥의 간지, 오행, 음양, 십성 정보입니다. 사주 원국 UI의 기본 데이터입니다. |
| fortune | Number | 현재 만세력 종합 점수입니다. 정렬, 추천, 간단한 등급 표시용으로 쓰기 좋습니다. |
| hehua | Object | effective, failed, applied*, five_before_pct, five_after_pct 등으로 합화 적용 결과를 보여줍니다. |
| five_pct / five_star / five_kor | Object | 오행 비율, 별점, 한글 표기 버전입니다. 숫자 UI와 설명 텍스트를 함께 만들기 좋습니다. |
| twelve_growth / twelve_growth_kor | Object | 십이운성 정보입니다. 한자/한글 버전이 모두 제공돼 표기 방식 선택이 쉽습니다. |
| strength | String | 일간 강약을 요약한 값입니다. 예: balanced, weak, strong. |
| geokguk | Object | geok, geok_kor, geok_detail, follower_candidate 등 격국 요약을 담습니다. |
| yongshin | Object | 보완이 필요한 핵심 오행입니다. 추천 컬러, 방향, 콘텐츠 추천 로직과 연결하기 쉽습니다. |
| branch_relations / branch_relations_kor | Object | 합·충·형·해·파·원진 등 관계를 원본 표기와 한글 표기로 함께 반환합니다. |
| relations_ui | Object | 관계 신호를 화면에 바로 쓰기 쉬운 형태로 정리한 객체입니다. (SIS 옵션) |
| big_luck / first_big_luck | Array / String | 10년 단위 대운 흐름과 첫 대운 정보를 제공합니다. 타임라인 카드 구성에 적합합니다. |
| lucky | Object | 행운 숫자, 방향, 보완 오행 등 부가 추천 정보를 제공합니다. |
| summary | Object | 사람에게 바로 보여주기 좋은 요약 필드입니다. 카드 상단 제목용으로 가장 먼저 쓰기 좋습니다. |
| zodiac_compatibility | Array<Object> | 본인 띠 기준 12지신 궁합 데이터입니다. 띠궁합 콘텐츠와 관계형 운세 콘텐츠에 활용할 수 있습니다. |
| sinsal | Array<Object> | sis_code, chart_vector, attributes, final_verdict, beginner_explanation를 포함한 신살 상세 데이터입니다. (SIS 옵션) |
| gongmang | Object | 공망지 한자/한글 목록과 관련 신살 요약을 제공합니다. 공망 특화 UI에 바로 사용할 수 있습니다. (SIS 옵션) |
지원하는 신살 전체 목록 (54종) Enum Reference ▼
Ablecity 사주 API는 54종의 신살을 분석합니다.
응답 데이터는 SIS(신살) 정식 버전에서 sis_code(S001~S054)·name_kr·name_en를 반환합니다.
아래 목록의 No.와 sis_code는 1:1로 매핑됩니다. (예: No. 1 ↔ S001)
* 상세 산출 로직(공식)은 에이블시티의 핵심 IP로, API 응답을 통해서만 결과를 제공합니다.
| No. | 구분 | 한글명 (Name) | 영문 키 (Key) |
|---|---|---|---|
| 1 | 흉살 | 격각살 | gyeok-gak-sal |
| 2 | 흉살 | 겁살 | geop-sal |
| 3 | 흉살 | 고란살 | go-ran-sal |
| 4 | 흉살 | 고신살 | go-sin-sal |
| 5 | 기타 | 공망 | gong-mang |
| 6 | 흉살 | 과숙살 | gwa-suk-sal |
| 7 | 길신 | 괴강귀인 | goe-gang-gwi-in |
| 8 | 흉살 | 괴강살 | goe-gang-sal |
| 9 | 흉살 | 귀문관살 | gwi-mun-gwan-sal |
| 10 | 길신 | 금여 | geum-yeo |
| 11 | 길신 | 록신귀인 | rok-sin-gwi-in |
| 12 | 흉살 | 망신살 | mang-sin-sal |
| 13 | 길신 | 문곡귀인 | mun-gok-gwi-in |
| 14 | 길신 | 문창귀인 | mun-chang-gwi-in |
| 15 | 길신 | 반안살 | ban-an-sal |
| 16 | 흉살 | 백호살 | baek-ho-sal |
| 17 | 길신 | 복성귀인 | bok-seong-gwi-in |
| 18 | 길신 | 삼기 | sam-gi |
| 19 | 흉살 | 조객살 | jo-gaek-sal |
| 20 | 흉살 | 상문살 | sang-mun-sal |
| 21 | 흉살 | 양인살 | yang-in-sal |
| 22 | 흉살 | 역마살 | yeok-ma-sal |
| 23 | 흉살 | 도화살(연살,함지살) | do-hwa-sal |
| 24 | 흉살 | 원진살 | won-jin-sal |
| 25 | 길신 | 월덕귀인 | wol-deok-gwi-in |
| 26 | 흉살 | 월살 | wol-sal |
| 27 | 흉살 | 육해살 | yuk-hae-sal |
| 28 | 길신 | 장성살 | jang-seong-sal |
| 29 | 흉살 | 재살 | jae-sal |
| 30 | 흉살 | 지복살 | ji-bok-sal |
| 31 | 길신 | 지살 | ji-sal |
| 32 | 길신 | 천계귀인 | cheon-gye-gwi-in |
| 33 | 길신 | 천관성 | cheon-gwan-seong |
| 34 | 길신 | 천덕귀인 | cheon-deok-gwi-in |
| 35 | 흉살 | 천라지망 | cheon-ra-ji-mang |
| 36 | 길신 | 천문성 | cheon-mun-seong |
| 37 | 길신 | 천복성 | cheon-bok-seong |
| 38 | 길신 | 천수성 | cheon-su-seong |
| 39 | 길신 | 천을귀인 | cheon-eul-gwi-in |
| 40 | 길신 | 천의성 | cheon-ui-seong |
| 41 | 길신 | 천주귀인 | cheon-ju-gwi-in |
| 42 | 흉살 | 충살 | chung-sal |
| 43 | 길신 | 태극귀인 | tae-geuk-gwi-in |
| 44 | 길신 | 학당귀인 | hak-dang-gwi-in |
| 45 | 기타 | 현침살 | hyeon-chim-sal |
| 46 | 흉살 | 형살 | hyeong-sal |
| 47 | 길신 | 홍염살 | hong-yeom-sal |
| 48 | 기타 | 화개 | hwa-gae |
| 49 | 길신 | 천덕합 | cheon-deok-hap |
| 50 | 길신 | 월덕합 | wol-deok-hap |
| 51 | 길신 | 협록 | hyeop-rok |
| 52 | 길신 | 암록 | am-rok |
| 53 | 흉살 | 파살 | pa-sal |
| 54 | 흉살 | 천살 | cheon-sal |
3.2 v2 Add-ons 및 심화 분석
오늘의 운세, 올해 운세, 정통사주, 궁합, 작명, 관상, 손금 등 v2 Add-on API의 요청 경로를 안내합니다. 실제 이용은 상품별 제공 상태와 발급된 키의 승인 범위를 따릅니다.
fortune/request-analysis/로 시작하는 엔드포인트는 모두 POST + Callback 방식이며, 나머지는 GET 방식입니다.
-
GET
동기 처리:
/fortune,/daily,/zodiac-luck,/luck-flow는 호출 즉시 결과를 반환합니다. -
POST
비동기 처리:
/fortune/request-analysis/...계열은 연산 후X-Callback-URL로 결과를 전송합니다. - CHECK 궁합(2인), 작명, 이미지 기반 분석은 입력 구조가 다르므로 각 예시의 payload 키 이름을 그대로 사용하세요.
서비스 엔드포인트 목록
| Method | Endpoint Path (Full URL) | Description |
|---|---|---|
| GET | /api/v2/saju/fortune/daily | 오늘의 운세 |
| GET | /api/v2/saju/fortune/zodiac-luck | 오늘의 띠별 운세 |
| GET | /api/v2/saju/fortune/luck-flow | 대운 / 연운 / 월운 |
| POST | /api/v2/saju/fortune/request-analysis/this-year-luck | 올해 운세 (Callback 필수) |
| POST | /api/v2/saju/fortune/request-analysis/telling | 정통사주 (Callback 필수) |
| POST | /api/v2/saju/fortune/request-analysis/match | 궁합(2인) (Callback 필수) |
| POST | /api/v2/saju/fortune/request-analysis/week-luck | 주간 운세 (Callback 필수) |
| POST | /api/v2/saju/fortune/request-analysis/love-luck | 올해 애정운 (Callback 필수) |
| POST | /api/v2/saju/fortune/request-analysis/rich-luck | 올해 재물운 (Callback 필수) |
| POST 내부 테스트 중 · 승인형 PoC 문의 |
/api/v2/saju/fortune/request-analysis/naming | 작명(추천 + 풀이) (Callback 필수) |
| POST | /api/v2/saju/fortune/request-analysis/face | 관상(얼굴 이미지) (Callback 필수) |
| POST | /api/v2/saju/fortune/request-analysis/palmistry | 손금(손 이미지) (Callback 필수) |
POST + Callback Recipe
궁합(2인) API 호출 예시
궁합 API는 한 명의 생년월일만 보내는 기본 조회와 다릅니다. male, female 두 객체를 JSON body에 넣고, 분석 결과를 받을 callback URL을 헤더로 전달해야 합니다.
1. Callback URL 준비
분석 결과를 받을 서버 endpoint를 먼저 만들어 둡니다.
2. 궁합 요청 전송
male, female 객체와 X-Callback-URL 헤더를 함께 보냅니다.
3. 결과 수신
요청 성공 응답은 접수 확인이며, 최종 분석 결과는 callback으로 받습니다.
완성형 cURL 예시
curl -X POST \
"https://api.ablecity.kr/api/v2/saju/fortune/request-analysis/match" \
-H "Authorization: Bearer <API_KEY>" \
-H "X-Callback-URL: https://your-server.com/webhook/saju-match" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"male": {
"birth": "1999-04-10T00:30:00",
"gender": "male",
"midnightType": 0,
"city": "서울특별시",
"calendar": "solar"
},
"female": {
"birth": "1998-03-10T00:10:00",
"gender": "female",
"midnightType": 0,
"city": "태안군",
"calendar": "solar"
}
}'payload 필드
| 필드 | 필수 | 설명 |
|---|---|---|
| male | Yes | 남성 사용자 또는 첫 번째 대상자의 생년월일 정보 객체입니다. |
| female | Yes | 여성 사용자 또는 두 번째 대상자의 생년월일 정보 객체입니다. |
| birth | Yes | YYYY-MM-DDTHH:mm:ss 형식의 생년월일과 출생 시각입니다. 날짜와 시간 사이에는 대문자 T만 허용하며, 공백이나 소문자 t는 허용하지 않습니다. |
| gender | Yes | male 또는 female 값을 사용합니다. |
| midnightType | Yes | 자시 처리 방식입니다. 일반 연동은 0 기준으로 시작합니다. |
| city | Yes | 출생지입니다. 예: 서울특별시, 태안군. |
| calendar | Yes | 양력은 solar 값을 사용합니다. |
요청 성공 시 즉시 응답 예시
{
"status": "success",
"message": "분석 요청이 접수되었습니다.",
"data": {
"request_id": "match_20260409_000001",
"service": "match",
"callback_status": "queued",
"callback_url": "https://your-server.com/webhook/saju-match"
}
}Node.js callback 수신 예시
app.post("/webhook/saju-match", express.json(), (req, res) => {
console.log("궁합 분석 결과:", req.body);
res.status(200).json({ ok: true });
});callback 결과 구조 예시
{
"request_id": "match_20260409_000001",
"service": "match",
"status": "success",
"data": {
"summary": "두 사람의 관계 성향과 보완 지점을 요약합니다.",
"score": 82,
"sections": [
{
"title": "성향 궁합",
"content": "서로의 기질과 관계 흐름을 설명합니다."
},
{
"title": "주의할 점",
"content": "갈등이 생기기 쉬운 지점과 대화 방식을 안내합니다."
}
]
}
}자주 실패하는 부분
X-Callback-URL헤더에서 콜론(:)을 빼면 안 됩니다.male,female키 이름을 임의로 바꾸면 안 됩니다.Content-Type: application/json없이 JSON body를 보내면 서버가 body를 읽지 못할 수 있습니다.- callback URL은 외부에서 접근 가능한 HTTPS endpoint를 권장합니다.
요청 예시 (POST / Callback, v2)
* /api/v2/saju/fortune/request-analysis/... 계열은 모두 X-Callback-URL 헤더가 필수입니다.
curl -X POST \
"https://api.ablecity.kr/api/v2/saju/fortune/request-analysis/rich-luck" \
-H "Authorization: Bearer <API_KEY>" \
-H "X-Callback-URL: https://your-server.com/webhook/result" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"birth": "1990-01-01T00:00:00",
"gender": "male",
"city": "서울특별시",
"calendar": "solar",
"midnightType": 0
}'준비 중 문서
점성술 API 문서 준비 중
점성술 API는 아직 정식 공개 전 문서입니다. 현재는 URL 구조와 응답 스키마 검토를 위해 준비 중이며, 검색 색인은 차단된 상태로 유지합니다.
4. 오류 코드
| HTTP Status | Code | Description |
|---|---|---|
| 400 | INVALID_REQUEST | 잘못된 요청입니다. |
| 401 | UNAUTHORIZED | 인증 실패 또는 토큰 만료. |
| 404 | NOT_FOUND | 리소스를 찾을 수 없습니다. |
| 429 | RATE_LIMIT | 요청 한도 초과입니다. |
| 500 | SERVER_ERROR | 서버 내부 오류. |
4.1 공통 message 값
요청이 완료되었습니다.– 성공 처리.서버 처리 중 오류가 발생했습니다.– 서버 내부 오류. 서버 로그 확인 필요.서비스를 찾을 수 없습니다.– 지원하지 않는 서비스(URL)를 호출한 경우.
4.2 인증·호출 제한 관련 message
-
●
유효하지 않은 API Key입니다.
API Key가 삭제(비활성화)되었거나 만료되었거나, 요청 헤더에 존재하지 않을 때. -
●
허용된 전체 분당 요청 횟수가 초과되었습니다.
API Key에 할당된 1분당 전체 요청 횟수를 초과. -
●
허용된 전체 일일 요청 횟수가 초과되었습니다.
API Key에 할당된 일일 전체 요청 횟수를 초과. -
●
허용되지 않은 서비스입니다.
요청한 서비스(URI)가 해당 API Key에 할당되지 않았거나, 비활성/만료 상태일 때. -
●
서비스가 일시적으로 불안정합니다. 잠시 후 다시 시도해주세요.
Redis 등 내부 요청 횟수 관리 중 일시적인 오류가 발생했을 때.
4.3 사주 API 전용 message
-
ℹ️
invalid birth date format
birth형식 오류.yyyy-MM-ddTHH:mm:ss형식만 허용됩니다. 날짜와 시간 사이에는 대문자 T만 허용하며, 공백이나 소문자 t는 허용하지 않습니다. -
ℹ️
gender must be 'male' or 'female'
gender값이male또는female이 아닐 때. -
ℹ️
invalid timezone
태어난 지역 시간대 오류. IANA tz 데이터베이스 기준으로 검증됩니다.
5. 호출 빈도 제한
안정적인 서비스 제공을 위해 API 호출 빈도를 제한하고 있습니다. 모든 엔드포인트는 발급받은 API Key를 기준으로 아래의 기본 한도가 적용됩니다.
⚠️ 한도 초과 시 처리 (Throttling)
서비스별 혹은 전체 한도를 초과하면 HTTP Status 429 (Too Many Requests)와 함께
Rate Limit 관련 message가 반환됩니다.
비즈니스 규모에 따라 더 높은 한도가 필요하신 경우, 고객센터([email protected])를 통해 상향을 요청할 수 있습니다.
아래 호출 빈도 제한과 Sandbox 총 제공량은 별개입니다. 적용 제품·한도는 발급된 키의 승인 범위를 따릅니다.
6. 자주 묻는 질문
Ablecity 사주 API는 어떤 버전으로 연동하나요? ▼
현재 문서는 v2 전용 기준으로 안내합니다.
모든 신규 테스트키와 정식키는 /api/v2/... 경로 기준으로 연동합니다.
궁합 API 요청은 기본 조회와 어떻게 다른가요? ▼
궁합 API는 한 명이 아니라 두 사람의 정보를 함께 보내야 하므로 male, female 두 객체가 필요합니다.
또한 분석 결과가 즉시 반환되지 않고 X-Callback-URL로 전달되므로 callback endpoint를 먼저 준비해야 합니다.
X-Callback-URL에는 어떤 값을 넣어야 하나요?
▼
분석 결과를 받을 서버 endpoint URL을 넣습니다.
예를 들어 https://your-server.com/webhook/saju-match처럼 외부에서 접근 가능한 HTTPS URL을 권장합니다.
헤더 문법은 X-Callback-URL: https://...처럼 콜론을 포함해야 합니다.
fortune/request-analysis/로 시작하는 엔드포인트는 왜 POST와 callback URL이 필요한가요?
▼
정통사주, 올해 운세, 궁합, 작명처럼 생성 시간이 더 필요한 분석형 API는 비동기로 처리합니다.
그래서 요청은 POST로 보내고, 결과는 X-Callback-URL로 전달받는 구조입니다.
만세력 API 사용료는 어떻게 되나요? ▼
2026년 12월 1일 적용 예정 PAYG는 콘텐츠·리텐션 20P/건, 만세력 Core 90P/건, 전문 만세력+SIS 150P/건입니다. 1P=1원, VAT 별도이며 한국어 표준 범위 기준입니다. Starter는 월 500건에 Core 30,000원, 전문 만세력+SIS 50,000원입니다. 전문 만세력+SIS Launch는 월 2,000건에 89,000원입니다. 전체 요금과 해설·전문 결과 단가는 요금 페이지에서 확인하세요. 월정액 초과 단가와 사용 한도, 미사용 포함량의 이월 여부, 요금제 변경·해지의 적용일, 결제일과 일할 계산은 Live 키 발급 전 견적·계약에서 정합니다. 표에 적힌 PAYG 단가가 월정액 초과 요금으로 자동 적용되지는 않습니다. 신규 고객은 지금 v5.0 기준의 승인형 Sandbox를 신청할 수 있습니다. 30일 제공량은 콘텐츠 100회, Core/전문 만세력+SIS 합산 1,000회, 표준 결과 합산 20회, 생성형 Callback 완료 결과 5건입니다. 신규 정식 유료 가입은 2026년 12월 1일 전까지 대기 상태입니다. 테스트용이며 상업 서비스나 최종 사용자에게 제공할 수 없습니다. 실제 기간·제품·한도는 승인 후 발급 안내에서 확인합니다. 내부 테스트 상품의 승인 범위는 별도로 확인합니다. Sandbox 키는 자동으로 Live 키로 바뀌지 않습니다. 실제 서비스나 최종 사용자에게 제공하기 전에 사용할 API·요금·적용 화면·예상 호출량·출시일을 확인하고 별도 Live 키를 발급받아야 합니다.
사주 API는 어떤 프로그래밍 언어에서 사용할 수 있나요? ▼
표준 RESTful JSON 응답을 제공하므로 Python, JavaScript(Node.js), Java, PHP, Go 등 HTTP 클라이언트를 지원하는 모든 언어 및 플랫폼에서 호출할 수 있습니다.
API Dashboard는 언제 사용하나요? ▼
API 키를 받은 고객이 API Dashboard에서 회원가입한 뒤 사용량, 구독 상태, API 조회를 확인할 수 있습니다. 키 발급 전에는 먼저 30일 Sandbox 신청을 진행해 주세요.
테스트 신청 후 API 키는 어떻게 안내받나요? ▼
제출 후 영업일 기준 1일 이내 1차 검토 결과와 발급 범위를 이메일로 안내합니다. API 키는 승인된 제품과 사용 범위에 한해 별도 이메일로 발급합니다.
Sandbox 제공량과 이용 제한은 무엇인가요?
제출 후 영업일 기준 1일 이내 1차 검토 결과와 발급 범위를 이메일로 안내합니다. API 키는 승인된 제품과 사용 범위에 한해 별도 이메일로 발급합니다.
신규 고객은 지금 v5.0 기준의 승인형 Sandbox를 신청할 수 있습니다. 30일 제공량은 콘텐츠 100회, Core/전문 만세력+SIS 합산 1,000회, 표준 결과 합산 20회, 생성형 Callback 완료 결과 5건입니다. 신규 정식 유료 가입은 2026년 12월 1일 전까지 대기 상태입니다. 테스트용이며 상업 서비스나 최종 사용자에게 제공할 수 없습니다. 실제 기간·제품·한도는 승인 후 발급 안내에서 확인합니다. 내부 테스트 상품의 승인 범위는 별도로 확인합니다.
7. 기술 문의
API 연동 문의.
API 연동 전 문의는 이메일로 보내 주세요. API 키를 받은 고객은 Dashboard에서 회원가입 후 사용량, 구독, API 조회를 확인할 수 있습니다.
연동 전 확인할 운영 조건
예상 호출량·응답 필드·오류 처리를 샘플로 확인하고, Callback 수신·중복 처리·재시도 방식을 검토합니다. 키 권한, 지원 시간, 장애 대응, 데이터 저장·삭제와 버전 변경 안내 범위는 도입 검토 및 계약에서 확정합니다.