> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sajuapi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 연간 운세 계산

<Info>
  **v1 Enterprise API (Coming Soon)**

  이 엔드포인트는 Enterprise 버전에서 제공될 예정입니다.
  현재는 [v0 API](/api-reference/v0/overview)를 사용하세요.
</Info>

특정 연도의 운세를 계산합니다. 사주팔자와 해당 연도의 세운(歲運)을 분석하여 월별 상세 운세를 제공합니다.

<Note>
  이 API는 프로필 없이 일회성 계산을 수행합니다. 저장된 프로필을 사용하려면 [운세 생성](/api-reference/fortunes/create) API에서 `fortune_type: "yearly"`를 사용하세요.
</Note>

***

## Request Body 파라미터

<ParamField body="birth_year" type="integer" required>
  출생 연도입니다. 1900에서 2100 사이의 값이어야 합니다.
</ParamField>

<ParamField body="birth_month" type="integer" required>
  출생 월입니다. 1에서 12 사이의 값이어야 합니다.
</ParamField>

<ParamField body="birth_day" type="integer" required>
  출생 일입니다. 1에서 31 사이의 값이어야 합니다.
</ParamField>

<ParamField body="birth_hour" type="integer">
  출생 시입니다. 0에서 23 사이의 값이어야 합니다.
</ParamField>

<ParamField body="gender" type="string" required>
  성별입니다. `male` 또는 `female` 중 하나입니다.
</ParamField>

<ParamField body="target_year" type="integer" required>
  운세를 계산할 대상 연도입니다. 1900에서 2100 사이의 값이어야 합니다.
</ParamField>

<ParamField body="model" type="string" default="haiku">
  AI 분석에 사용할 모델입니다. `haiku`, `sonnet`, `gpt4o` 중 하나입니다.
</ParamField>

***

## Response

### 성공

연간 운세 계산에 성공하면 YearlyFortune 객체가 반환됩니다.

### 실패

| 상태 코드 | 에러 타입                  | 설명              |
| ----- | ---------------------- | --------------- |
| 400   | `validation_error`     | 요청 데이터가 유효하지 않음 |
| 401   | `authentication_error` | API 키가 유효하지 않음  |
| 429   | `rate_limited`         | 요청 한도 초과        |
| 503   | `service_unavailable`  | AI 모델 서비스 일시 불가 |

***

## 요청 예시

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.sajuapi.dev/v1/calculations/yearly \
    -H "X-API-Key: bs_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "birth_year": 1990,
      "birth_month": 3,
      "birth_day": 15,
      "birth_hour": 14,
      "gender": "male",
      "target_year": 2025,
      "model": "sonnet"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.sajuapi.dev/v1/calculations/yearly', {
    method: 'POST',
    headers: {
      'X-API-Key': 'bs_live_xxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      birth_year: 1990,
      birth_month: 3,
      birth_day: 15,
      birth_hour: 14,
      gender: 'male',
      target_year: 2025,
      model: 'sonnet'
    })
  });

  const yearlyFortune = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.sajuapi.dev/v1/calculations/yearly',
      headers={'X-API-Key': 'bs_live_xxx'},
      json={
          'birth_year': 1990,
          'birth_month': 3,
          'birth_day': 15,
          'birth_hour': 14,
          'gender': 'male',
          'target_year': 2025,
          'model': 'sonnet'
      }
  )

  yearly_fortune = response.json()
  ```
</CodeGroup>

***

## 응답 예시

```json theme={null}
{
  "target_year": 2025,
  "year_pillar": {
    "stem": "을",
    "stem_hanja": "乙",
    "branch": "사",
    "branch_hanja": "巳",
    "element": "wood",
    "animal": "뱀"
  },
  "day_master": {
    "name": "병화",
    "element": "fire"
  },
  "year_energy_interaction": {
    "relationship": "상생",
    "description": "을목(乙木)이 병화(丙火)를 생하여 좋은 에너지 흐름이 있습니다.",
    "impact": "positive"
  },
  "overall": {
    "score": 78,
    "summary": "2025년은 전반적으로 성장과 발전의 해가 될 것입니다. 을사년(乙巳年)의 목화(木火) 기운이 병화 일주와 조화를 이루어 창의력과 활력이 넘칩니다.",
    "keywords": ["성장", "창의력", "새로운 시작", "인간관계 확장"],
    "advice": "상반기에 새로운 프로젝트를 시작하기 좋습니다. 하반기에는 안정을 추구하세요."
  },
  "categories": {
    "wealth": {
      "score": 72,
      "summary": "재물운은 안정적입니다. 투자보다는 저축을 권합니다.",
      "best_months": [3, 6, 9],
      "caution_months": [2, 8]
    },
    "career": {
      "score": 85,
      "summary": "직장운이 좋습니다. 승진이나 이직의 기회가 있을 수 있습니다.",
      "best_months": [4, 5, 10],
      "caution_months": [7]
    },
    "love": {
      "score": 75,
      "summary": "인간관계가 원만합니다. 새로운 만남의 기회가 있습니다.",
      "best_months": [2, 5, 11],
      "caution_months": [8]
    },
    "health": {
      "score": 70,
      "summary": "건강에 주의가 필요합니다. 특히 심장과 혈액순환에 신경 쓰세요.",
      "best_months": [4, 9],
      "caution_months": [6, 12]
    }
  },
  "monthly": [
    {
      "month": 1,
      "stem": "정",
      "branch": "축",
      "score": 72,
      "summary": "한 해를 시작하는 달로, 계획을 세우기 좋습니다.",
      "focus": "계획 수립",
      "caution": "과도한 지출 주의"
    },
    {
      "month": 2,
      "stem": "무",
      "branch": "인",
      "score": 80,
      "summary": "활력이 넘치는 달입니다. 적극적으로 행동하세요.",
      "focus": "새로운 시작",
      "caution": "무리한 일정 주의"
    },
    {
      "month": 3,
      "stem": "기",
      "branch": "묘",
      "score": 85,
      "summary": "상반기 최고의 운세입니다. 중요한 일을 추진하세요.",
      "focus": "도전과 기회",
      "caution": "자만심 경계"
    }
  ],
  "lucky_elements": {
    "colors": ["빨강", "주황", "보라"],
    "numbers": [3, 7, 9],
    "directions": ["남쪽", "동쪽"],
    "items": ["태양 모티프 액세서리", "붉은색 소품"]
  },
  "generated_at": "2025-01-16T09:00:00Z",
  "model": "sonnet",
  "latency_ms": 3450
}
```

***

## YearlyFortune 객체

| 필드                        | 타입      | 설명                  |
| ------------------------- | ------- | ------------------- |
| `target_year`             | integer | 대상 연도입니다.           |
| `year_pillar`             | object  | 해당 연도의 연주(年柱)입니다.   |
| `day_master`              | object  | 일주(日柱) 정보입니다.       |
| `year_energy_interaction` | object  | 연도 기운과 일주의 상호작용입니다. |
| `overall`                 | object  | 전체 운세 요약입니다.        |
| `categories`              | object  | 카테고리별 운세입니다.        |
| `monthly`                 | array   | 월별 상세 운세입니다.        |
| `lucky_elements`          | object  | 행운의 요소입니다.          |

***

## 연도 기운 상호작용

| 관계   | 설명               | 영향       |
| ---- | ---------------- | -------- |
| `상생` | 연도 기운이 일주를 돕습니다  | 긍정적      |
| `상극` | 연도 기운이 일주와 충돌합니다 | 주의 필요    |
| `비화` | 연도 기운이 일주와 동일합니다 | 중립적/경쟁   |
| `식상` | 일주가 연도 기운을 생합니다  | 에너지 소모   |
| `재성` | 일주가 연도 기운을 극합니다  | 기회/노력 필요 |