> ## 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는 현재 베타 버전입니다. 기능과 응답 형식이 변경될 수 있습니다.
</Note>

***

## Request Body 파라미터

### person1 (필수)

<ParamField body="person1.birth_year" type="integer" required>
  첫 번째 사람의 출생 연도입니다.
</ParamField>

<ParamField body="person1.birth_month" type="integer" required>
  첫 번째 사람의 출생 월입니다.
</ParamField>

<ParamField body="person1.birth_day" type="integer" required>
  첫 번째 사람의 출생 일입니다.
</ParamField>

<ParamField body="person1.birth_hour" type="integer">
  첫 번째 사람의 출생 시입니다.
</ParamField>

<ParamField body="person1.gender" type="string" required>
  첫 번째 사람의 성별입니다.
</ParamField>

### person2 (필수)

<ParamField body="person2.birth_year" type="integer" required>
  두 번째 사람의 출생 연도입니다.
</ParamField>

<ParamField body="person2.birth_month" type="integer" required>
  두 번째 사람의 출생 월입니다.
</ParamField>

<ParamField body="person2.birth_day" type="integer" required>
  두 번째 사람의 출생 일입니다.
</ParamField>

<ParamField body="person2.birth_hour" type="integer">
  두 번째 사람의 출생 시입니다.
</ParamField>

<ParamField body="person2.gender" type="string" required>
  두 번째 사람의 성별입니다.
</ParamField>

### 기타 파라미터

<ParamField body="relationship_type" type="string" default="romantic">
  관계 유형입니다. `romantic`(연애/결혼), `business`(비즈니스), `friendship`(우정) 중 하나입니다.
</ParamField>

<ParamField body="model" type="string" default="haiku">
  AI 분석에 사용할 모델입니다.
</ParamField>

***

## Response

### 성공

궁합 계산에 성공하면 Compatibility 객체가 반환됩니다.

### 실패

| 상태 코드 | 에러 타입                  | 설명              |
| ----- | ---------------------- | --------------- |
| 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/compatibility \
    -H "X-API-Key: bs_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "person1": {
        "birth_year": 1990,
        "birth_month": 3,
        "birth_day": 15,
        "birth_hour": 14,
        "gender": "male"
      },
      "person2": {
        "birth_year": 1992,
        "birth_month": 7,
        "birth_day": 22,
        "birth_hour": 10,
        "gender": "female"
      },
      "relationship_type": "romantic",
      "model": "sonnet"
    }'
  ```

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

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

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

  response = requests.post(
      'https://api.sajuapi.dev/v1/calculations/compatibility',
      headers={'X-API-Key': 'bs_live_xxx'},
      json={
          'person1': {
              'birth_year': 1990,
              'birth_month': 3,
              'birth_day': 15,
              'birth_hour': 14,
              'gender': 'male'
          },
          'person2': {
              'birth_year': 1992,
              'birth_month': 7,
              'birth_day': 22,
              'birth_hour': 10,
              'gender': 'female'
          },
          'relationship_type': 'romantic',
          'model': 'sonnet'
      }
  )

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

***

## 응답 예시

```json theme={null}
{
  "relationship_type": "romantic",
  "overall": {
    "score": 82,
    "rating": "excellent",
    "summary": "두 분의 궁합은 매우 좋습니다. 병화(丙火)와 임수(壬水)의 조합으로 서로를 보완하는 관계입니다."
  },
  "person1": {
    "day_master": "병화",
    "element": "fire",
    "characteristics": ["열정적", "리더십", "적극적"]
  },
  "person2": {
    "day_master": "임수",
    "element": "water",
    "characteristics": ["지혜로움", "유연함", "포용력"]
  },
  "element_interaction": {
    "type": "상극",
    "description": "화(火)와 수(水)는 상극 관계이지만, 적절한 균형을 이루면 서로를 제어하고 보완합니다.",
    "balance": "positive",
    "advice": "서로의 다름을 인정하고 존중하면 더욱 강한 유대를 형성할 수 있습니다."
  },
  "categories": {
    "emotional": {
      "score": 85,
      "description": "감정적으로 서로를 잘 이해합니다. 첫 번째 분의 열정을 두 번째 분이 차분하게 받아줍니다."
    },
    "communication": {
      "score": 78,
      "description": "의사소통 스타일이 다르지만, 노력하면 좋은 대화가 가능합니다."
    },
    "values": {
      "score": 80,
      "description": "핵심 가치관이 비슷합니다. 가정과 안정을 중시합니다."
    },
    "physical": {
      "score": 88,
      "description": "물리적 케미스트리가 좋습니다."
    },
    "growth": {
      "score": 82,
      "description": "함께 성장할 수 있는 관계입니다."
    }
  },
  "strengths": [
    "서로 부족한 부분을 보완합니다",
    "열정과 지혜가 조화를 이룹니다",
    "갈등 해결 능력이 있습니다",
    "장기적인 관계에 적합합니다"
  ],
  "challenges": [
    "의사소통 방식의 차이",
    "에너지 레벨의 차이로 인한 갈등 가능성",
    "서로 다른 표현 방식"
  ],
  "advice": {
    "for_person1": "상대방의 조용한 시간을 존중해주세요. 모든 것을 적극적으로 끌고 가려 하지 마세요.",
    "for_person2": "상대방의 열정에 좀 더 적극적으로 반응해주세요. 감정 표현을 조금 더 해주면 좋겠습니다.",
    "together": "서로의 다름을 인정하고, 정기적으로 깊은 대화 시간을 가지세요."
  },
  "lucky_elements": {
    "shared_colors": ["보라", "파랑"],
    "shared_numbers": [1, 6],
    "best_date_days": ["수요일", "토요일"]
  },
  "generated_at": "2025-01-16T09:00:00Z",
  "model": "sonnet",
  "latency_ms": 4200
}
```

***

## Compatibility 객체

| 필드                    | 타입     | 설명                 |
| --------------------- | ------ | ------------------ |
| `relationship_type`   | string | 관계 유형입니다.          |
| `overall`             | object | 전체 궁합 점수와 요약입니다.   |
| `person1`             | object | 첫 번째 사람의 사주 정보입니다. |
| `person2`             | object | 두 번째 사람의 사주 정보입니다. |
| `element_interaction` | object | 오행 상호작용 분석입니다.     |
| `categories`          | object | 카테고리별 호환성입니다.      |
| `strengths`           | array  | 관계의 강점입니다.         |
| `challenges`          | array  | 관계의 도전 과제입니다.      |
| `advice`              | object | 각자와 함께에 대한 조언입니다.  |
| `lucky_elements`      | object | 함께 어울리는 행운 요소입니다.  |

***

## 궁합 등급

| 점수     | 등급            | 설명    |
| ------ | ------------- | ----- |
| 90-100 | `perfect`     | 천생연분  |
| 80-89  | `excellent`   | 매우 좋음 |
| 70-79  | `good`        | 좋음    |
| 60-69  | `moderate`    | 보통    |
| 50-59  | `challenging` | 노력 필요 |
| 0-49   | `difficult`   | 어려움   |

<Warning>
  궁합 결과는 참고용입니다. 실제 관계의 성공은 두 사람의 노력과 소통에 달려있습니다.
</Warning>