Skip to main content
POST
https://sajuapi.dev
/
v1
/
fortunes
운세 생성
curl --request POST \
  --url https://sajuapi.dev/v1/fortunes \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "profile_id": "<string>",
  "fortune_type": "<string>",
  "fortune_date": "<string>",
  "model": "<string>",
  "include_lucky_items": true,
  "idempotency_key": "<string>"
}
'
v1 Enterprise API (Coming Soon)이 엔드포인트는 Enterprise 버전에서 제공될 예정입니다. 현재는 v0 API를 사용하세요.
프로필 정보를 기반으로 운세를 생성합니다. 생성된 운세는 자동으로 저장되며, 동일한 조건으로 재요청 시 캐시된 결과가 반환됩니다.
운세 생성에는 AI 모델이 사용되며, 응답 시간은 선택한 모델에 따라 다릅니다. 실시간 응답이 필요한 경우 스트리밍 API를 사용하세요.

​
Request Body 파라미터

​
profile_id
string
required
운세를 생성할 프로필의 ID입니다. prf_ 접두사로 시작합니다.
​
fortune_type
string
required
운세 유형입니다. daily, yearly, monthly 중 하나입니다.
​
fortune_date
string
운세 날짜입니다. ISO 8601 형식(YYYY-MM-DD)입니다. 기본값은 오늘입니다.
​
model
string
default:"haiku"
사용할 AI 모델입니다. haiku, sonnet, gpt4o 중 하나입니다.
  • haiku: 빠른 응답, 경제적 (기본값)
  • sonnet: 상세한 분석, 중간 비용
  • gpt4o: 최고 품질, 높은 비용
​
include_lucky_items
boolean
default:"true"
행운의 아이템(숫자, 색상, 방향 등)을 포함할지 여부입니다.
​
idempotency_key
string
멱등성 키입니다. 동일한 키로 재요청 시 동일한 결과가 반환됩니다. 최대 64자입니다.

​
Response

​
성공

운세 생성에 성공하면 Fortune 객체가 반환됩니다.

​
실패

상태 코드에러 타입설명
400validation_error요청 데이터가 유효하지 않음
401authentication_errorAPI 키가 유효하지 않음
404not_found프로필을 찾을 수 없음
429rate_limited요청 한도 초과
503service_unavailableAI 모델 서비스 일시 불가

​
요청 예시

curl -X POST https://api.sajuapi.dev/v1/fortunes \
  -H "X-API-Key: bs_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req_abc123" \
  -d '{
    "profile_id": "prf_abc123def456",
    "fortune_type": "daily",
    "fortune_date": "2025-01-16",
    "model": "sonnet",
    "include_lucky_items": true
  }'

​
응답 예시

{
  "id": "ftn_xyz789abc123",
  "profile_id": "prf_abc123def456",
  "fortune_type": "daily",
  "fortune_date": "2025-01-16",
  "model": "sonnet",
  "score": 85,
  "summary": "오늘은 새로운 기회가 찾아오는 날입니다. 오행 중 화(火) 기운이 강해 창의적인 활동에 유리합니다.",
  "categories": {
    "overall": {
      "score": 85,
      "description": "전반적으로 긍정적인 하루가 예상됩니다."
    },
    "wealth": {
      "score": 75,
      "description": "재물운이 안정적입니다. 큰 지출은 피하세요."
    },
    "love": {
      "score": 90,
      "description": "인간관계가 원만합니다. 새로운 만남에 열린 마음을 가지세요."
    },
    "health": {
      "score": 80,
      "description": "건강은 양호하나 과로를 주의하세요."
    },
    "career": {
      "score": 88,
      "description": "업무에서 좋은 성과가 기대됩니다."
    }
  },
  "lucky_items": {
    "number": 7,
    "color": "빨강",
    "direction": "남쪽",
    "time": "오후 2시-4시"
  },
  "advice": "오늘은 적극적으로 행동하되, 중요한 결정은 신중하게 내리세요.",
  "cached": false,
  "generated_at": "2025-01-16T09:00:00Z",
  "latency_ms": 2340
}

​
Fortune 객체

필드타입설명
idstring운세 ID입니다. ftn_ 접두사로 시작합니다.
profile_idstring연결된 프로필 ID입니다.
fortune_typestring운세 유형입니다. daily, yearly, monthly 중 하나입니다.
fortune_datestring운세 날짜입니다. YYYY-MM-DD 형식입니다.
modelstring사용된 AI 모델입니다.
scoreinteger전체 운세 점수입니다. 0-100 사이의 값입니다.
summarystring운세 요약입니다.
categoriesobject카테고리별 운세입니다.
lucky_itemsobject행운의 아이템입니다. include_lucky_items가 false면 null입니다.
advicestring오늘의 조언입니다.
cachedboolean캐시된 결과인지 여부입니다.
generated_atstring생성 시간입니다. ISO 8601 형식입니다.
latency_msinteger응답 시간(밀리초)입니다.

​
캐싱

동일한 profile_id, fortune_type, fortune_date, model 조합으로 요청하면 캐시된 결과가 반환됩니다. 캐시된 응답은 cached: true로 표시되며, latency_ms가 크게 줄어듭니다. 
{
  "id": "ftn_xyz789abc123",
  "cached": true,
  "latency_ms": 45
}