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

# Jev

> TypeSafe Jev 의사결정 모델: 선택지, 점수, 예/아니요 확률 또는 이미지 경계 상자와 신뢰도를 반환

## 소개

Jev는 TypeSafe의 **System One 의사결정 모델**입니다. **텍스트를 생성하지 않고**, 제공된 내용(`state`)에 대해 답변 범위가 정해진 질문(`questions`)을 평가하여 코드에서 바로 사용할 수 있는 구조화된 결과를 반환합니다.

* **선택 (`choice`)**: 정의한 선택지 중 하나를 고릅니다. 예: 이 문의를 어느 부서로 전달할지 판단합니다.
* **점수 (`score`)**: 정의한 단계에 따라 평가합니다. 예: 고객의 분노 수준을 0 차분함 / 1 불만 / 2 분노로 평가합니다.
* **예/아니요 (`noul`)**: 예일 확률을 반환합니다. 예: 고객이 환불을 요청하는지 판단합니다.
* **경계 상자 (`box`)**: 이미지에서 설명한 대상을 찾아 상하좌우 경계를 반환합니다. 예: 차량의 흠집을 찾습니다.

한 요청에서 여러 질문을 할 수 있습니다. 내용은 한 번 읽고 각 질문은 독립적으로 평가합니다. Choice, Score, Box 답변에는 신뢰도가, Noul 답변에는 확률이 포함됩니다. 문의 분류, 콘텐츠 검토, 감정 평가, 의도 파악, 에이전트 도구 호출 검증, 모델 라우팅 등 빠른 판단이 필요한 작업에 활용할 수 있습니다.

> [!NOTE]
>
> 요청 구조와 성공 응답의 필드는 TypeSafe 공식 [System One API](https://docs.typesafe.ai/api/system-one)를 따릅니다. 오류 응답은 플랫폼에서 래핑할 수 있습니다. [오류 처리](#오류-처리)를 참고하세요.

> [!WARNING]
>
> Jev는 OpenAI의 `/v1/chat/completions`, `/v1/responses` 등 대화 인터페이스를 **지원하지 않습니다**. 아래의 `/v1/systemone`으로 호출하세요. 답변 문장이나 코드를 작성하거나 추론 과정을 설명하지 않습니다.

## 인증

**Authorization** `string` *required*

Bearer Token, 예: `Bearer sk-xxxxxxxxxx`

**Content-Type** `string` *required*

`application/json`. multipart 이미지 업로드에는 `multipart/form-data`를 사용합니다. [multipart 이미지 업로드](#multipart-이미지-업로드)를 참고하세요.

**TypeSafe-Danger-Zone-Images** `string`

`true`로 설정합니다. 공식 규격상 이미지(`assets`)나 Box 질문(`box`)이 포함된 요청에는 **필수**입니다.

**TypeSafe-Danger-Zone-Long-Context** `string`

`true`로 설정하면 긴 컨텍스트 모드가 활성화되어 한도가 64k에서 262k로 늘어납니다. [컨텍스트 길이](#컨텍스트-길이)를 참고하세요.

플랫폼의 API 키 페이지에서 키를 생성하세요. 프런트엔드 코드, 공개 저장소 또는 클라이언트 설치 패키지에 API 키를 포함하지 마세요.

## 모델 정보

| 모델 이름 | 설명 | 질문 유형 | 입력 |
| - | - | - | - |
| `jev-latest` | 최신 정식 버전. 현재 `jev-1.14.0`을 가리킴 | choice / score / noul / box | 텍스트, 이미지 |
| `jev-preview` | 미리보기 포함 최신 버전. 현재도 `jev-1.14.0`을 가리킴 | choice / score / noul / box | 텍스트, 이미지 |
| `jev-1.14.0` | Jev 1.14 고정 버전 | choice / score / noul / box | 텍스트, 이미지 |
| `jev-1.13.0` | Jev 1.13 고정 버전 | choice / score / noul (**box 미지원**) | 텍스트, 이미지 |

* `jev-latest`와 `jev-preview`는 별칭입니다. 공식 새 버전이 출시되면 대상 버전이 바뀌어 답변도 달라질 수 있습니다. 응답의 `model` 필드는 실제 평가에 사용된 버전입니다.
* 특정 버전에 맞춰 신뢰도 임계값을 조정했다면 고정 버전 ID를 사용하고, 새 버전의 결과를 확인한 뒤 전환하는 것을 권장합니다.

| 항목 | 설명 |
| - | - |
| 인터페이스 유형 | 동기 응답 |
| 스트리밍 | 지원하지 않음 |
| 요청당 질문 수 | 컨텍스트 한도 이내라면 별도 제한 없음 |
| 이미지 형식 | PNG, JPEG |
| 과금 | 입력 토큰에만 과금, 출력 토큰은 무료 |

## 엔드포인트

```http theme={null}
POST https://api.gravitex.ai/v1/systemone
```

## 요청 매개변수

| 매개변수 | 유형 | 필수 | 설명 |
| - | - | - | - |
| `model` | string | 예 | 모델 이름. [모델 정보](#모델-정보) 참고 |
| `state` | string / object / array | 예 | 모든 질문이 평가할 내용. [state](#state) 참고 |
| `questions` | object | 예 | 질문 이름을 키로, 질문 정의를 값으로 지정하며 최소 1개 필요. [questions](#questions) 참고 |
| `assets` | object | 아니요 | 자리표시자를 키로, 이미지 정의를 값으로 지정한 모음. [assets](#assets) 참고 |

> [!NOTE]
>
> Jev에는 `temperature`, `max_tokens` 같은 샘플링 매개변수가 없으며 출력 길이를 설정할 필요도 없습니다.

### state

평가할 내용은 다음 세 가지 형태 중 하나로 제공합니다.

* **문자열**: 고객 메시지, 문의 내용, 계약서 전문 등의 텍스트입니다.
* **객체**: `{"subject": "중복 결제", "message": "처리해 주세요"}` 같은 구조화된 데이터입니다. 고객 메시지, 주문 기록, 업무 규칙을 함께 제공할 때 적합합니다.
* **배열**: 대화 기록처럼 여러 텍스트를 제공합니다.

```json theme={null}
"state": {
  "customer_message": "주문 금액이 두 번 결제되었는데 사흘째 처리되지 않고 있습니다",
  "orders": [{ "id": "A1024", "charged_times": 2 }],
  "refund_policy": "중복 결제된 추가 금액은 전액 환불할 수 있습니다"
}
```

### questions

질문 모음입니다. 직접 지정한 질문 이름이 키가 되며, 응답의 `answers`에서도 같은 이름으로 답변이 반환됩니다. 각 값은 질문 정의입니다.

| 필드 | 유형 | 필수 | 설명 |
| - | - | - | - |
| `type` | string | 예 | 질문 유형: `choice`, `score`, `noul`, `box` |
| `instructions` | string / object / array | 아니요 | 모델이 무엇을 판단할지 설명 |
| `criteria` | object / array | 유형에 따라 다름 | 선택지 또는 평가 기준. 아래 표 참고 |

| 질문 유형 | `criteria` 형식 | 요구 사항 |
| - | - | - |
| `choice` 선택 | 객체: `{선택지_이름: 선택지_설명}` | **필수**, 선택지 1\~255개. 설명이 비어 있으면 이름만으로 해석합니다. |
| `score` 점수 | 낮은 단계부터 높은 단계 순으로 설명을 나열한 배열 | **필수**, 1\~10단계이며 최소 2단계 권장. 첫 단계는 0점이며 순서대로 1씩 증가합니다. |
| `noul` 예/아니요 | 객체: `{"true": "예에 해당하는 기준", "false": "아니요에 해당하는 기준"}` | 선택 사항. `instructions` 또는 `criteria` 중 하나 이상을 제공해야 하며, 없으면 업스트림에서 오류를 반환합니다. |
| `box` 경계 상자 | 보내지 않음 | `jev-1.14.0`과 이를 가리키는 별칭만 지원. 이미지 및 `TypeSafe-Danger-Zone-Images: true` 필수. |

```json theme={null}
"questions": {
  "department": {
    "type": "choice",
    "instructions": "이 문의를 어느 부서에서 처리해야 하나요?",
    "criteria": {
      "billing": "결제, 청구, 환불",
      "technical": "기능 장애, 오류",
      "sales": "구매 전 문의, 요금제 업그레이드"
    }
  },
  "anger": {
    "type": "score",
    "instructions": "고객은 얼마나 화가 났나요?",
    "criteria": ["차분함", "다소 불만", "매우 화남"]
  },
  "wants_refund": {
    "type": "noul",
    "instructions": "고객이 환불을 요청하고 있나요?",
    "criteria": { "true": "명시적으로 환불을 요청함", "false": "환불을 요청하지 않음" }
  }
}
```

> [!NOTE]
>
> * 질문은 서로 독립적입니다. 각 질문은 `state`만 평가하며 다른 질문의 답변을 보지 않습니다.
> * 선택지와 단계 설명이 구체적일수록 판단이 안정적입니다. 선택지의 의미가 겹치지 않도록 작성하세요.

### assets

이미지 모음입니다. 키는 직접 지정한 **자리표시자**이며 이미지마다 새 UUID 사용을 권장합니다. 자리표시자가 `state`, 질문의 `instructions` 또는 `criteria` 내 문자열에 나타나면 해당 이미지로 대체됩니다.

| 필드 | 유형 | 필수 | 설명 |
| - | - | - | - |
| `type` | string | 아니요 | 지정한다면 `image`로 고정. 예제에서는 명시적으로 지정 |
| `format` | string | `data_base64` 사용 시 필수 | `png`, `jpg`, `jpeg`. 실제 형식은 이미지 바이트로 판별 |
| `data_base64` | string | 두 방식 중 하나 | `data:image/...;base64,` 접두사가 **없는** 이미지 Base64 데이터 |
| `part` | string | 두 방식 중 하나 | multipart 요청에서 이미지가 들어 있는 파트 이름. 지정하면 `data_base64`는 무시됨 |

다음 예제는 흰 배경에 빨간 직사각형이 있는 **280 × 280** PNG를 사용합니다. 아래 이미지 판단 및 경계 상자 예제에서도 사용합니다. 최소 크기보다 작은 자리표시자 이미지로 바꾸지 마세요.

```json theme={null}
"state": "photo",
"assets": {
  "photo": {
    "type": "image",
    "format": "png",
    "data_base64": "iVBORw0KGgoAAAANSUhEUgAAARgAAAEYCAIAAAAI7H7bAAAC/UlEQVR42u3TwQ0AMAgDsey/NN0BPlT4lAEqVKckjYsTSCBJIEkgSQJJAkkCSQJJEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSSJJAkkCSQJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIkkCSQJJAkkCSBJIEkgSSJJAkkCSQmi+NXRxIIBlIIBlIIBlIIIFkIIFkIIFkIIFkIIEEkoEEkoEEkoEEkoEEEkgGEkgGEkgGEkgGEkggGUggGUggGUggGUgggWQggWQggWQggQQSSCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIBhJIIBlIIBlIIBlIIBlIIIFkIIFkIIFkIIFkIIEEkoEEkoEEkoEEkoEEEkgGEkgGEkgGEkgggQQSSAYSSAYSSAYSSCAZSCAZSCAZSCAZSCCBZCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIBhJIIBlIIBlIIBlIIPlSIIEEkoEEkoEEkoEEEkgggQSSgQSSgQSSgQQSSAYSSAYSSAYSSAYSSCAZSCAZSCAZSCAZSCCBZCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIIIEEEkgGEkgGEkgGEkggGUggGUggGUggGUgggWQggWQggWQggWQggSR9HUgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSQJJAkkCSRJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIkkCSQJJAkkCSBJIEkgSSBJIkkCSQJJAkkJxAAkkCSQJJEkgSSNKyHikG6UERft5KAAAAAElFTkSuQmCC"
  }
}
```

> [!WARNING]
>
> 공식 규격상 `assets`가 포함된 요청에는 `TypeSafe-Danger-Zone-Images: true` 헤더가 필수입니다. 이미지 입력과 Box 질문은 초기 기능이므로 버전에 따라 요청 형식, 답변, 제한이 바뀔 수 있습니다.

### 이미지 제한

이미지는 다음 [공식 제한](https://docs.typesafe.ai/images#limits)을 모두 충족해야 합니다. 크기가 맞지 않으면 자동 조정되지 않으며 요청 전체가 실패합니다.

| 항목 | 제한 |
| - | - |
| 형식 | 정지 PNG 또는 JPEG. 애니메이션 PNG 미지원 |
| 너비와 높이 | 각각 **280\~1568픽셀**, 양 끝값 포함 |
| 전체 픽셀 수 | 78,400\~2,458,624 |
| 개별 파일 | 최대 16 MiB. Base64는 디코딩 후 파일 크기 기준 |
| 요청 본문 | JSON, Base64 또는 multipart 오버헤드 포함 최대 32 MiB |
| 모든 이미지 / 참조 확장 후 요청 | 각각 최대 32 MiB. 같은 이미지의 반복 참조는 확장 크기에 중복 계산 |

모든 asset은 `state`, `instructions` 또는 `criteria`에서 참조되어야 합니다. 너무 작은 이미지, 잘못된 형식, 참조되지 않은 asset 등은 보통 400을 반환합니다. 파일, 이미지 크기 또는 요청 크기 상한 초과 시 413을 반환할 수 있습니다.

### multipart 이미지 업로드

이미지가 크거나 여러 장이면 Base64 대신 `multipart/form-data`로 원본 파일을 업로드할 수 있습니다.

* 첫 번째 파트의 이름은 `request`이며 JSON 요청 본문을 담습니다(`Content-Type: application/json`).
* 이후 이미지마다 별도 파트를 사용합니다. 파트 이름은 고유하고 비어 있지 않아야 하며 asset의 `part`에서 참조해야 합니다.

```bash theme={null}
curl --location 'https://api.gravitex.ai/v1/systemone' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'TypeSafe-Danger-Zone-Images: true' \
  --form 'request={"model":"jev-latest","state":"photo","questions":{"damage":{"type":"noul","instructions":"차량에 눈에 띄는 흠집이 있나요?"}},"assets":{"photo":{"type":"image","part":"img1"}}};type=application/json' \
  --form 'img1=@./car.jpg;type=image/jpeg'
```

### 컨텍스트 길이

각 요청은 두 한도를 모두 충족해야 합니다.

| 한도 | 기본값 | 긴 컨텍스트 활성화 시 |
| - | - | - |
| 요청당 (`state` + 모든 질문) | 64k 토큰 | 262k 토큰 |
| 질문당 (`state` + 해당 질문) | 32k 토큰 | 262k 토큰 |

* 한도를 넘으면 업스트림에서 400과 `max_tokens_exceeded` 오류를 반환합니다.
* 긴 계약서나 대화 기록을 처리하려면 `TypeSafe-Danger-Zone-Long-Context: true` 헤더를 보내세요. **토큰당 단가는 동일**하지만 속도가 느리고 정확도가 다소 낮으므로 필요한 경우에만 활성화하세요.

## 호출 예제

> [tab] 선택
>
> ```bash theme={null}
> curl --location 'https://api.gravitex.ai/v1/systemone' \
>   --header 'Authorization: Bearer sk-xxxxxxxxxx' \
>   --header 'Content-Type: application/json' \
>   --data '{
>     "model": "jev-latest",
>     "state": "도와주세요! 사흘째 정산금을 받지 못하고 있습니다.",
>     "questions": {
>       "department": {
>         "type": "choice",
>         "instructions": "어느 팀에서 이 문의를 처리해야 하나요?",
>         "criteria": {
>           "billing": "결제, 청구, 환불",
>           "technical": "버그, 서비스 장애, 연동",
>           "sales": "가격, 업그레이드, 신규 계정"
>         }
>       }
>     }
>   }'
> ```

> [tab] 여러 질문
>
> ```bash theme={null}
> curl --location 'https://api.gravitex.ai/v1/systemone' \
>   --header 'Authorization: Bearer sk-xxxxxxxxxx' \
>   --header 'Content-Type: application/json' \
>   --data '{
>     "model": "jev-latest",
>     "state": "주문 금액이 두 번 결제되었는데 사흘째 처리되지 않고 있습니다. 환불하지 않으면 민원을 제기하겠습니다!",
>     "questions": {
>       "department": {
>         "type": "choice",
>         "instructions": "이 문의를 어느 부서에서 처리해야 하나요?",
>         "criteria": { "billing": "결제, 청구, 환불", "technical": "기능 장애, 오류", "sales": "구매 전 문의, 요금제 업그레이드" }
>       },
>       "anger": {
>         "type": "score",
>         "instructions": "고객은 얼마나 화가 났나요?",
>         "criteria": ["차분함", "다소 불만", "매우 화남"]
>       },
>       "wants_refund": { "type": "noul", "instructions": "고객이 환불을 요청하고 있나요?" }
>     }
>   }'
> ```

> [tab] 구조화된 state
>
> ```bash theme={null}
> curl --location 'https://api.gravitex.ai/v1/systemone' \
>   --header 'Authorization: Bearer sk-xxxxxxxxxx' \
>   --header 'Content-Type: application/json' \
>   --data '{
>     "model": "jev-1.14.0",
>     "state": {
>       "customer_message": "주문 금액이 두 번 결제되었습니다",
>       "orders": [{ "id": "A1024", "charged_times": 2 }],
>       "refund_policy": "중복 결제된 추가 금액은 전액 환불할 수 있습니다"
>     },
>     "questions": {
>       "refund_allowed": { "type": "noul", "instructions": "환불 규정에 따라 이 주문은 환불 대상인가요?" }
>     }
>   }'
> ```

> [tab] 이미지 판단
>
> ```bash theme={null}
> curl --location 'https://api.gravitex.ai/v1/systemone' \
>   --header 'Authorization: Bearer sk-xxxxxxxxxx' \
>   --header 'Content-Type: application/json' \
>   --header 'TypeSafe-Danger-Zone-Images: true' \
>   --data '{
>     "model": "jev-latest",
>     "state": "photo",
>     "questions": {
>       "has_red": { "type": "noul", "instructions": "이미지에 빨간색 물체가 있나요?" }
>     },
>     "assets": {
>       "photo": {
>         "type": "image",
>         "format": "png",
>         "data_base64": "iVBORw0KGgoAAAANSUhEUgAAARgAAAEYCAIAAAAI7H7bAAAC/UlEQVR42u3TwQ0AMAgDsey/NN0BPlT4lAEqVKckjYsTSCBJIEkgSQJJAkkCSQJJEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSSJJAkkCSQJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIkkCSQJJAkkCSBJIEkgSSJJAkkCSQmi+NXRxIIBlIIBlIIBlIIIFkIIFkIIFkIIFkIIEEkoEEkoEEkoEEkoEEEkgGEkgGEkgGEkgGEkggGUggGUggGUggGUgggWQggWQggWQggQQSSCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIBhJIIBlIIBlIIBlIIBlIIIFkIIFkIIFkIIFkIIEEkoEEkoEEkoEEkoEEEkgGEkgGEkgGEkgggQQSSAYSSAYSSAYSSCAZSCAZSCAZSCAZSCCBZCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIBhJIIBlIIBlIIBlIIPlSIIEEkoEEkoEEkoEEEkgggQSSgQSSgQSSgQQSSAYSSAYSSAYSSAYSSCAZSCAZSCAZSCAZSCCBZCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIIIEEEkgGEkgGEkgGEkggGUggGUggGUggGUgggWQggWQggWQggWQggSR9HUgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSQJJAkkCSRJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIkkCSQJJAkkCSBJIEkgSSBJIkkCSQJJAkkJxAAkkCSQJJEkgSSNKyHikG6UERft5KAAAAAElFTkSuQmCC"
>       }
>     }
>   }'
> ```

> [tab] 경계 상자
>
> ```bash theme={null}
> curl --location 'https://api.gravitex.ai/v1/systemone' \
>   --header 'Authorization: Bearer sk-xxxxxxxxxx' \
>   --header 'Content-Type: application/json' \
>   --header 'TypeSafe-Danger-Zone-Images: true' \
>   --data '{
>     "model": "jev-1.14.0",
>     "state": "photo",
>     "questions": {
>       "red_rectangle": { "type": "box", "instructions": "빨간 직사각형을 찾으세요." },
>       "has_rectangle": { "type": "noul", "instructions": "이미지에 빨간 직사각형이 있나요?" }
>     },
>     "assets": {
>       "photo": {
>         "type": "image",
>         "format": "png",
>         "data_base64": "iVBORw0KGgoAAAANSUhEUgAAARgAAAEYCAIAAAAI7H7bAAAC/UlEQVR42u3TwQ0AMAgDsey/NN0BPlT4lAEqVKckjYsTSCBJIEkgSQJJAkkCSQJJEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSSJJAkkCSQJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIkkCSQJJAkkCSBJIEkgSSJJAkkCSQmi+NXRxIIBlIIBlIIBlIIIFkIIFkIIFkIIFkIIEEkoEEkoEEkoEEkoEEEkgGEkgGEkgGEkgGEkggGUggGUggGUggGUgggWQggWQggWQggQQSSCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIBhJIIBlIIBlIIBlIIBlIIIFkIIFkIIFkIIFkIIEEkoEEkoEEkoEEkoEEEkgGEkgGEkgGEkgggQQSSAYSSAYSSAYSSCAZSCAZSCAZSCAZSCCBZCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIBhJIIBlIIBlIIBlIIPlSIIEEkoEEkoEEkoEEEkgggQSSgQSSgQSSgQQSSAYSSAYSSAYSSAYSSCAZSCAZSCAZSCAZSCCBZCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIIIEEEkgGEkgGEkgGEkggGUggGUggGUggGUgggWQggWQggWQggWQggSR9HUgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSQJJAkkCSRJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIkkCSQJJAkkCSBJIEkgSSBJIkkCSQJJAkkJxAAkkCSQJJEkgSSNKyHikG6UERft5KAAAAAElFTkSuQmCC"
>       }
>     }
>   }'
> ```
>
> Box에는 "찾을 수 없음" 답변이 없습니다. 대상이 이미지에 없어도 네 경계를 반환합니다. 대상의 존재 여부를 확인하려면 위 예제처럼 같은 요청에 Noul 질문을 추가하세요.

> [tab] 긴 컨텍스트
>
> ```bash theme={null}
> curl --location 'https://api.gravitex.ai/v1/systemone' \
>   --header 'Authorization: Bearer sk-xxxxxxxxxx' \
>   --header 'Content-Type: application/json' \
>   --header 'TypeSafe-Danger-Zone-Long-Context: true' \
>   --data '{
>     "model": "jev-latest",
>     "state": "<긴 계약서 전문>",
>     "questions": {
>       "has_termination_clause": {
>         "type": "noul",
>         "instructions": "계약서에 어느 한쪽이 계약을 조기 해지할 수 있도록 허용하는 조항이 있나요?"
>       }
>     }
>   }'
> ```

> [tab] Python
>
> ```python theme={null}
> import requests
>
> # 먼저 의존성을 설치하세요: pip install requests
> resp = requests.post(
>     "https://api.gravitex.ai/v1/systemone",
>     headers={"Authorization": "Bearer sk-xxxxxxxxxx"},
>     json={
>         "model": "jev-latest",
>         "state": "주문 금액이 두 번 결제되었습니다. 환불하지 않으면 민원을 제기하겠습니다!",
>         "questions": {
>             "wants_refund": {"type": "noul", "instructions": "고객이 환불을 요청하고 있나요?"},
>         },
>     },
>     timeout=60,
> )
> resp.raise_for_status()
> answer = resp.json()["answers"]["wants_refund"]
> if answer["noul"] >= 0.8:
>     print("환불 처리 절차로 전달")
> ```

## 성공 응답

```json theme={null}
{
  "model": "jev-1.14.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "confidence": 1,
      "probabilities": { "billing": 1, "technical": 0, "sales": 0 }
    },
    "anger": {
      "type": "score",
      "score": 1.87,
      "confidence": 0.8,
      "legend": { "0": "차분함", "1": "다소 불만", "2": "매우 화남" },
      "probabilities": { "0": 0, "1": 0.13, "2": 0.87 }
    },
    "wants_refund": {
      "type": "noul",
      "noul": 0.97
    }
  },
  "usage": {
    "input_tokens": 443,
    "output_tokens": 71
  }
}
```

**Box 답변**

```json theme={null}
{
  "type": "box",
  "box": { "top": 0.2, "bottom": 0.66, "left": 0.19, "right": 0.68 },
  "confidence": 0.9
}
```

### 응답 필드

| 필드 | 유형 | 설명 |
| - | - | - |
| `model` | string | 실제 평가한 모델 버전. 별칭으로 요청해도 `jev-1.14.0` 같은 버전 ID를 반환 |
| `answers` | object | 요청의 질문 이름에 대응하는 답변 모음 |
| `answers.*.type` | string | 질문 유형: `choice`, `score`, `noul`, `box` |
| `answers.*.choice` | string | Choice: 확률이 가장 높은 선택지 이름 |
| `answers.*.score` | number | Score: 단계별 확률로 가중 평균한 기대 점수. `1.87`처럼 정수 단계 사이의 값일 수 있음 |
| `answers.*.noul` | number | 예일 확률, 0\~1. 1에 가까우면 예, 0에 가까우면 아니요, 0.5에 가까우면 불확실함 |
| `answers.*.box` | object | `top`, `bottom`, `left`, `right` 경계. 이미지 높이 또는 너비에 대한 비율 0\~1이며 왼쪽 위가 기준 |
| `answers.*.confidence` | number | Choice, Score, Box의 신뢰도, 0\~1. 높을수록 확실함. Box는 `null`일 수 있음 |
| `answers.*.probabilities` | object | Choice는 선택지별, Score는 단계 인덱스를 키로 한 단계별 확률. 합은 약 1 |
| `answers.*.legend` | object | Score: 단계 인덱스와 설명의 대응 관계 |
| `usage.input_tokens` | integer | 입력 토큰 수. **과금 기준** |
| `usage.output_tokens` | integer | 출력 토큰 수. 현재 **과금하지 않음** |

> [!NOTE]
>
> **신뢰도 활용**: 확률과 신뢰도는 보정되어 있어 임계값 기반 자동 의사결정에 사용할 수 있습니다. 예를 들어 `noul ≥ 0.8`은 자동 처리, `0.2 ~ 0.8`은 사람의 검토, `< 0.2`는 통과로 설정할 수 있습니다. 사람이 라벨링한 샘플로 임계값을 조정하세요.

## 과금 안내

**계산식**: 요청당 비용 = `usage.input_tokens` / 1,000,000 × 입력 단가

| 모델 | 입력 단가 (USD / 백만 토큰) | 출력 |
| - | - | - |
| `jev-1.14.0` | 0.042 | 무료 |
| `jev-1.13.0` | 0.042 | 무료 |
| `jev-latest` | 0.042 | 무료 |
| `jev-preview` | 0.042 | 무료 |

* 위 금액은 공식 기본 단가입니다. 실제 과금에는 API 키가 속한 그룹의 배율이 적용됩니다. 모델 마켓에 표시된 가격을 기준으로 하세요.
* 입력 토큰에는 `state`, 모든 질문 설명, 선택지, 단계 설명이 포함됩니다. 이미지가 있으면 이미지 토큰도 포함됩니다.
* 응답의 `output_tokens`는 참고용이며 현재 과금되지 않습니다.
* 긴 컨텍스트는 더 긴 입력을 허용할 뿐, 토큰당 단가는 바뀌지 않습니다.

**예시**: 위 여러 질문 요청에서 `input_tokens: 443`이 반환되면 비용은 443 / 1,000,000 × 0.042 ≈ **0.0000186 USD**이며, 같은 요청 10,000회는 약 0.19 USD입니다.

## 오류 처리

실패한 요청은 JSON 오류 객체를 반환합니다. 플랫폼이 업스트림 오류를 래핑할 수 있어 `message`에는 구체적인 이유 대신 `openai_error`만 들어갈 수도 있습니다. 이 필드만으로 원인을 단정하지 마세요. 오류 형식 예시는 다음과 같습니다.

```json theme={null}
{
  "error": {
    "message": "max_tokens_exceeded",
    "type": "bad_response_status_code",
    "param": "",
    "code": "bad_response_status_code"
  }
}
```

> [!NOTE]
>
> 공식 API의 매개변수 검증 실패는 422를 반환할 수 있지만, 게이트웨이는 400과 `error` 객체로 감싸 반환할 수 있습니다. HTTP 상태 코드를 먼저 확인하고 오류 필드를 읽으세요. 모든 게이트웨이가 공식 `detail` 구조나 구체적인 오류 메시지를 그대로 반환한다고 가정하지 마세요.

자주 발생하는 문제:

| 문제 | 해결 방법 |
| - | - |
| 잘못된 API 키 | `Authorization: Bearer ...` 확인 |
| `model` 누락 | JSON 본문 또는 multipart의 `request` 파트에 `model` 포함 |
| `state` / `questions` 누락 | 둘 다 필수. `questions`에 질문을 최소 1개 포함 |
| Choice 오류 | `criteria`를 선택지 1\~255개의 객체로 제공 |
| Score 오류 | `criteria`를 1\~10단계의 배열로 제공 |
| Noul 오류 | `instructions` 또는 `criteria` 중 하나 이상 제공 |
| 알 수 없는 질문 유형 | `type`은 `choice`, `score`, `noul`, `box` 중 하나여야 함 |
| 이미지 오류 | `TypeSafe-Danger-Zone-Images: true` 전송. 너비와 높이는 각각 280\~1568픽셀. 정지 PNG / JPEG를 사용하고 Base64에 `data:image/...;base64,` 접두사를 붙이지 마세요. [이미지 제한](#이미지-제한) 참고. |
| Box 오류 | `jev-1.14.0` 또는 현재 이를 가리키는 별칭을 사용하고 이미지 및 Images 헤더 포함 |
| `openai_error` | 구체적인 원인이 노출되지 않음. 이미지 크기, 모델과 유형의 호환성, 필수 필드, 컨텍스트 길이를 확인하세요. 필요하면 요청 시간과 요청 ID를 기록해 플랫폼에 문의하세요. |
| `max_tokens_exceeded` | `state`를 줄이거나 `TypeSafe-Danger-Zone-Long-Context: true` 전송 |
| `/v1/chat/completions` 호출 실패 | Jev는 대화 모델이 아님. `POST /v1/systemone` 사용 |

## 공식 참고 문서

* [System One API](https://docs.typesafe.ai/api/system-one)
* [모델, 별칭 및 컨텍스트 길이](https://docs.typesafe.ai/models)
* [이미지 업로드 및 제한](https://docs.typesafe.ai/images)
* [Box 질문 및 신뢰도](https://docs.typesafe.ai/primitives/box)
* [요청 규칙 및 오류 코드](https://docs.typesafe.ai/api/errors)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.