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

# v1 API 개요

> 위젯 기반 사주 운세 API - 클라이언트 앱에서 운세 위젯을 구현하기 위한 API

v1 API는 클라이언트 앱에서 사주 운세 위젯을 쉽게 구현할 수 있도록 설계된 API입니다.

## 특징

* **위젯 친화적**: 각 위젯에 필요한 데이터만 반환하는 엔드포인트
* **AI 생성 콘텐츠**: BAML 기반 AI 운세 생성 (내부 구현)
* **분석 데이터**: 플랫폼 집계 데이터 기반 인사이트
* **API 키 인증**: 모든 요청에 API 키 필요
* **다중 모델 지원**: Haiku, Sonnet, GPT-4o, Gemini 선택 가능

## API 카테고리

### 1. 운세 (AI 생성)

AI가 생성하는 운세 콘텐츠입니다. 내부적으로 BAML을 사용합니다.

| 엔드포인트                            | 설명               | 위젯                                             |
| -------------------------------- | ---------------- | ---------------------------------------------- |
| `POST /v1/fortunes/daily`        | 일일 운세 전체         | AICharacterCard, ActionItems, InvestmentAdvice |
| `POST /v1/fortunes/daily-stream` | 일일 운세 스트리밍 (SSE) | 프로그레시브 로딩                                      |
| `POST /v1/fortunes/weekly`       | 주간 운세            | 날짜 네비게이션                                       |
| `GET /v1/fortunes/character`     | 캐릭터만 조회          | AICharacterCard                                |
| `GET /v1/fortunes/tendency`      | 투자 성향만 조회        | StatsCards                                     |
| `GET /v1/fortunes/radar`         | 레이더 차트 데이터       | RadarChart                                     |

### 2. 분석 (Analytics)

플랫폼 데이터를 집계한 인사이트입니다. AI 생성이 아닌 실제 데이터 기반입니다.

| 엔드포인트                                   | 설명            | 위젯                       |
| --------------------------------------- | ------------- | ------------------------ |
| `GET /v1/analytics/popular-coins`       | 같은 일간 선호 코인   | PopularCoinsWidget       |
| `GET /v1/analytics/comparison`          | 내 사주 vs 전체 평균 | ComparisonWidget         |
| `GET /v1/analytics/fortune-ranking`     | 오늘의 사주 운 랭킹   | FortuneRankingWidget     |
| `GET /v1/analytics/trading-styles`      | 사주별 거래 스타일    | TradingStyleWidget       |
| `GET /v1/analytics/portfolio-breakdown` | 사주별 포트폴리오     | PortfolioBreakdownWidget |
| `GET /v1/analytics/saju-twin`           | 사주 쌍둥이 인사이트   | SajuTwinWidget           |

### 3. 계산

사주 계산 및 궁합 분석입니다.

| 엔드포인트                                 | 설명           |
| ------------------------------------- | ------------ |
| `POST /v1/calculations/saju`          | 생년월일로 사주 계산  |
| `POST /v1/calculations/compatibility` | 두 사주 간 궁합 계산 |

## 캐싱 전략

| 데이터 타입         | 캐시 기간 | 설명            |
| -------------- | ----- | ------------- |
| Character      | 30일   | 사주 기반, 변하지 않음 |
| Tendency       | 30일   | 사주 기반, 변하지 않음 |
| Radar          | 30일   | 사주 기반, 변하지 않음 |
| Daily Fortune  | 24시간  | 일일 운세는 매일 갱신  |
| Weekly Fortune | 7일    | 주간 단위 갱신      |
| Analytics      | 1시간   | 실시간 데이터 반영    |

## 모델별 비용

| 모델     | 비용 (호출당) | 특징             |
| ------ | -------- | -------------- |
| Haiku  | \$0.013  | 빠름, 저렴함 (기본값)  |
| Sonnet | \$0.066  | 균형 잡힌 품질       |
| GPT-4o | \$0.050  | OpenAI 모델      |
| Gemini | \$0.010  | Google 모델, 최저가 |

## 위젯 매핑

```
┌──────────────────────────────────────────────────────────────┐
│ Tab 1: 오늘의 운세                                            │
├──────────────────────────────────────────────────────────────┤
│ AICharacterCard    ← POST /v1/fortunes/daily (character)     │
│ ActionItems        ← POST /v1/fortunes/daily (todayFortune)  │
│ InvestmentAdvice   ← POST /v1/fortunes/daily (investment)    │
├──────────────────────────────────────────────────────────────┤
│ Tab 2: 사주 인사이트                                          │
├──────────────────────────────────────────────────────────────┤
│ StatsCards         ← GET /v1/fortunes/tendency               │
│ PopularCoinsWidget ← GET /v1/analytics/popular-coins         │
│ ComparisonWidget   ← GET /v1/analytics/comparison            │
│ FortuneRankingWidget ← GET /v1/analytics/fortune-ranking     │
└──────────────────────────────────────────────────────────────┘
```

<Note>
  Enterprise 기능(프로필 관리, 웹훅, 암호화 등)이 필요하시면 [v2 API](/api-reference/v2/overview)를 참고하세요.
</Note>