> ## 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>
  운세 생성에는 AI 모델이 사용되며, 응답 시간은 선택한 모델에 따라 다릅니다. 실시간 응답이 필요한 경우 [스트리밍 API](/api-reference/fortunes/stream)를 사용하세요.
</Note>

***

## Request Body 파라미터

<ParamField body="profile_id" type="string" required>
  운세를 생성할 프로필의 ID입니다. `prf_` 접두사로 시작합니다.
</ParamField>

<ParamField body="fortune_type" type="string" required>
  운세 유형입니다. `daily`, `yearly`, `monthly` 중 하나입니다.
</ParamField>

<ParamField body="fortune_date" type="string">
  운세 날짜입니다. ISO 8601 형식(YYYY-MM-DD)입니다. 기본값은 오늘입니다.
</ParamField>

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

  * `haiku`: 빠른 응답, 경제적 (기본값)
  * `sonnet`: 상세한 분석, 중간 비용
  * `gpt4o`: 최고 품질, 높은 비용
</ParamField>

<ParamField body="include_lucky_items" type="boolean" default="true">
  행운의 아이템(숫자, 색상, 방향 등)을 포함할지 여부입니다.
</ParamField>

<ParamField body="idempotency_key" type="string">
  멱등성 키입니다. 동일한 키로 재요청 시 동일한 결과가 반환됩니다. 최대 64자입니다.
</ParamField>

***

## Response

### 성공

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

### 실패

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

***

## 요청 예시

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.sajuapi.dev/v1/fortunes', {
    method: 'POST',
    headers: {
      'X-API-Key': 'bs_live_xxx',
      'Content-Type': 'application/json',
      'Idempotency-Key': 'req_abc123'
    },
    body: JSON.stringify({
      profile_id: 'prf_abc123def456',
      fortune_type: 'daily',
      fortune_date: '2025-01-16',
      model: 'sonnet',
      include_lucky_items: true
    })
  });

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

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

  response = requests.post(
      'https://api.sajuapi.dev/v1/fortunes',
      headers={
          'X-API-Key': 'bs_live_xxx',
          'Idempotency-Key': 'req_abc123'
      },
      json={
          'profile_id': 'prf_abc123def456',
          'fortune_type': 'daily',
          'fortune_date': '2025-01-16',
          'model': 'sonnet',
          'include_lucky_items': True
      }
  )

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

***

## 응답 예시

```json theme={null}
{
  "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 객체

| 필드             | 타입      | 설명                                                     |
| -------------- | ------- | ------------------------------------------------------ |
| `id`           | string  | 운세 ID입니다. `ftn_` 접두사로 시작합니다.                           |
| `profile_id`   | string  | 연결된 프로필 ID입니다.                                         |
| `fortune_type` | string  | 운세 유형입니다. `daily`, `yearly`, `monthly` 중 하나입니다.        |
| `fortune_date` | string  | 운세 날짜입니다. YYYY-MM-DD 형식입니다.                            |
| `model`        | string  | 사용된 AI 모델입니다.                                          |
| `score`        | integer | 전체 운세 점수입니다. 0-100 사이의 값입니다.                           |
| `summary`      | string  | 운세 요약입니다.                                              |
| `categories`   | object  | 카테고리별 운세입니다.                                           |
| `lucky_items`  | object  | 행운의 아이템입니다. `include_lucky_items`가 `false`면 `null`입니다. |
| `advice`       | string  | 오늘의 조언입니다.                                             |
| `cached`       | boolean | 캐시된 결과인지 여부입니다.                                        |
| `generated_at` | string  | 생성 시간입니다. ISO 8601 형식입니다.                              |
| `latency_ms`   | integer | 응답 시간(밀리초)입니다.                                         |

***

## 캐싱

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

```json theme={null}
{
  "id": "ftn_xyz789abc123",
  "cached": true,
  "latency_ms": 45
}
```