> ## 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.

# 연간 운세

사주를 기반으로 연간 운세를 생성합니다.

연간 운세는 특정 연도의 전체적인 흐름과 투자 전략을 제공합니다.

***

## Request Body

<ParamField body="saju" type="SajuResult" required>
  클라이언트에서 계산한 사주 데이터 객체입니다.
</ParamField>

<ParamField body="userName" type="string" required>
  사용자 이름입니다.
</ParamField>

<ParamField body="year" type="integer" required>
  운세를 볼 연도입니다. (예: 2025)
</ParamField>

<ParamField body="model" type="string" default="sonnet">
  사용할 AI 모델입니다. 연간 운세는 복잡한 분석이 필요하므로 기본값이 `sonnet`입니다.
</ParamField>

***

## Response

### 성공

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

***

## 요청 예시

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch('/api/fortune', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      saju,
      userName: '김철수',
      year: 2025,
      model: 'sonnet'
    })
  });

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

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

  response = requests.post(
      'https://sajuapi.dev/api/fortune',
      json={
          'saju': saju,
          'userName': '김철수',
          'year': 2025,
          'model': 'sonnet'
      }
  )

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

***

## 응답 예시

```json theme={null}
{
  "success": true,
  "data": {
    "year": 2025,
    "yearStem": "을",
    "yearBranch": "사",
    "yearElement": "wood",
    "overallScore": 75,
    "summary": "2025년 을사년은 목(木)의 기운이 강한 해입니다. 병화(丙火) 일주인 당신에게 목생화(木生火)의 상생 관계가 형성되어 전반적으로 좋은 한 해가 될 것입니다.",
    "keywords": ["성장", "확장", "새로운 시작"],
    "investmentFortune": {
      "score": 78,
      "summary": "투자에 유리한 해입니다. 특히 상반기에 좋은 기회가 많습니다.",
      "favorableMonths": [3, 4, 5, 9, 10],
      "cautionMonths": [7, 8],
      "sectors": ["기술주", "친환경 에너지", "헬스케어"]
    },
    "wealthFortune": {
      "score": 72,
      "summary": "재물운은 안정적입니다. 큰 손실은 없지만 큰 이익도 기대하기 어렵습니다.",
      "peakPeriod": "4월-5월",
      "advice": "안정적인 수입원을 확보하고 절약에 힘쓰세요."
    },
    "quarterlyForecast": [
      {
        "quarter": "Q1",
        "months": "1월-3월",
        "score": 70,
        "focus": "준비와 계획",
        "advice": "새해 계획을 세우고 정보를 수집하는 시기입니다."
      },
      {
        "quarter": "Q2",
        "months": "4월-6월",
        "score": 85,
        "focus": "적극적 투자",
        "advice": "가장 좋은 시기입니다. 계획했던 투자를 실행하세요."
      },
      {
        "quarter": "Q3",
        "months": "7월-9월",
        "score": 65,
        "focus": "보수적 관리",
        "advice": "리스크 관리에 집중하고 신규 투자는 자제하세요."
      },
      {
        "quarter": "Q4",
        "months": "10월-12월",
        "score": 75,
        "focus": "수확과 정리",
        "advice": "한 해를 마무리하며 포트폴리오를 정리하세요."
      }
    ],
    "luckyElements": {
      "color": "녹색",
      "direction": "동쪽",
      "number": 3
    }
  },
  "generatedAt": "2025-01-16T09:00:00Z",
  "meta": {
    "model": "sonnet",
    "requestId": "req_xyz789",
    "costPerCall": 0.066,
    "durationMs": 3500
  }
}
```

***

## YearlyFortune 객체

| 필드                  | 타입      | 설명                   |
| ------------------- | ------- | -------------------- |
| `year`              | integer | 운세 연도입니다.            |
| `yearStem`          | string  | 연도의 천간입니다.           |
| `yearBranch`        | string  | 연도의 지지입니다.           |
| `yearElement`       | string  | 연도의 주요 오행입니다.        |
| `overallScore`      | integer | 전체 운세 점수 (0-100)입니다. |
| `summary`           | string  | 연간 운세 요약입니다.         |
| `keywords`          | array   | 올해의 키워드입니다.          |
| `investmentFortune` | object  | 투자 운세입니다.            |
| `wealthFortune`     | object  | 재물 운세입니다.            |
| `quarterlyForecast` | array   | 분기별 전망입니다.           |
| `luckyElements`     | object  | 행운의 요소입니다.           |

***

## 캐싱

연간 운세는 연도별로 캐싱됩니다. 같은 사주와 연도 조합으로 요청하면 캐시된 결과가 반환됩니다.

| 조건            | 캐시 기간 |
| ------------- | ----- |
| 같은 사주 + 같은 연도 | 1년    |
| 다른 연도         | 새로 생성 |

<Note>
  연간 운세는 복잡한 분석이 필요하므로 기본 모델이 `sonnet`입니다.
  더 저렴한 `haiku`를 사용할 수 있지만, 분석 품질이 다소 떨어질 수 있습니다.
</Note>