Skip to main content

​
기본 URL

모든 API 요청은 다음 주소로 보내야 합니다: 
https://api.sajuapi.dev

​
엔드포인트

메서드엔드포인트설명
POST/api/daily-fortune개인화된 일일 운세 조회
POST/api/daily-fortune-streamSSE로 운세 스트리밍
POST/api/saju생년월일로 사주 계산

​
요청 형식

모든 요청은 다음 조건을 충족해야 합니다:
  • POST 메서드 사용
  • Content-Type: application/json 헤더 포함
  • X-API-Key 헤더에 API 키 포함
  • JSON 본문 전송
curl -X POST https://api.sajuapi.dev/api/daily-fortune \
  -H "Content-Type: application/json" \
  -H "X-API-Key: bs_live_xxx" \
  -d '{"saju": {...}, "userName": "홍길동"}'

​
응답 형식

모든 응답은 다음 구조를 따릅니다:

​
성공 응답

{
  "success": true,
  "data": {
    // 엔드포인트별 데이터
  },
  "meta": {
    "requestId": "req_abc123",
    "model": "haiku",
    "cached": true,
    "cost": 0.013,
    "latency": 1234
  }
}

​
에러 응답

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "사람이 읽을 수 있는 에러 메시지",
    "hint": "에러 수정을 위한 제안",
    "field": "saju.pillars.day"  // 선택: 에러가 발생한 특정 필드
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

​
공통 파라미터

​
사주 객체

saju 파라미터는 운세 엔드포인트에 필수이며 사주팔자를 포함해야 합니다: 
interface Saju {
  pillars: {
    year: Pillar;
    month: Pillar;
    day: Pillar;
    hour: Pillar;  // 출생 시간을 모르면 null 가능
  };
  dayMaster?: {
    element: 'wood' | 'fire' | 'earth' | 'metal' | 'water';
    name: string;  // 예: "병화"
  };
}

interface Pillar {
  stem: {
    hangul: string;  // 예: "갑", "을", "병"...
    hanja?: string;  // 예: "甲", "乙", "丙"...
  };
  branch: {
    hangul: string;  // 예: "자", "축", "인"...
    hanja?: string;
  };
}

​
모델 선택

운세 생성을 위한 AI 모델 선택:
모델파라미터속도품질비용
Claude Haikuhaiku~2초좋음$0.013
Claude Sonnetsonnet~5초우수$0.031
GPT-4ogpt4o~4초매우 좋음$0.025
{
  "saju": {...},
  "userName": "홍길동",
  "model": "haiku"
}

​
응답 타입

​
운세 타입

type 파라미터로 특정 운세 타입을 요청합니다:
타입설명함수 호출 횟수
all (기본값)전체 운세 분석3 (성격, 성향, 운세)
fortune_only일일 운세만1
character성격 분석만1
compare모든 모델 비교9 (3 함수 × 3 모델)
compare 타입은 9번의 API 호출을 하며 비용이 3배입니다. 신중하게 사용하세요.

​
페이지네이션

목록을 반환하는 엔드포인트는 페이지네이션을 지원합니다: 
{
  "page": 1,
  "limit": 20,
  "sort": "createdAt",
  "order": "desc"
}
응답에 페이지네이션 메타데이터가 포함됩니다: 
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

​
버전 관리

API는 URL 경로를 통해 버전 관리됩니다. 현재 버전: v1 (기본값) 
https://api.sajuapi.dev/v1/api/daily-fortune
/v1 접두사는 선택 사항입니다. 버전 접두사가 없는 요청은 최신 안정 버전을 사용합니다.