메인 콘텐츠로 건너뛰기
POST
Jev

소개

Jev는 TypeSafe의 System One 의사결정 모델입니다. 텍스트를 생성하지 않고, 제공된 내용(state)에 대해 답변 범위가 정해진 질문(questions)을 평가하여 코드에서 바로 사용할 수 있는 구조화된 결과를 반환합니다.
  • 선택 (choice): 정의한 선택지 중 하나를 고릅니다. 예: 이 문의를 어느 부서로 전달할지 판단합니다.
  • 점수 (score): 정의한 단계에 따라 평가합니다. 예: 고객의 분노 수준을 0 차분함 / 1 불만 / 2 분노로 평가합니다.
  • 예/아니요 (noul): 예일 확률을 반환합니다. 예: 고객이 환불을 요청하는지 판단합니다.
  • 경계 상자 (box): 이미지에서 설명한 대상을 찾아 상하좌우 경계를 반환합니다. 예: 차량의 흠집을 찾습니다.
한 요청에서 여러 질문을 할 수 있습니다. 내용은 한 번 읽고 각 질문은 독립적으로 평가합니다. Choice, Score, Box 답변에는 신뢰도가, Noul 답변에는 확률이 포함됩니다. 문의 분류, 콘텐츠 검토, 감정 평가, 의도 파악, 에이전트 도구 호출 검증, 모델 라우팅 등 빠른 판단이 필요한 작업에 활용할 수 있습니다.
요청 구조와 성공 응답의 필드는 TypeSafe 공식 System One API를 따릅니다. 오류 응답은 플랫폼에서 래핑할 수 있습니다. 오류 처리를 참고하세요.
Jev는 OpenAI의 /v1/chat/completions, /v1/responses 등 대화 인터페이스를 지원하지 않습니다. 아래의 /v1/systemone으로 호출하세요. 답변 문장이나 코드를 작성하거나 추론 과정을 설명하지 않습니다.

인증

string
필수
Bearer Token, 예: Bearer sk-xxxxxxxxxx
string
필수
application/json. multipart 이미지 업로드에는 multipart/form-data를 사용합니다. multipart 이미지 업로드를 참고하세요.
string
true로 설정합니다. 공식 규격상 이미지(assets)나 Box 질문(box)이 포함된 요청에는 필수입니다.
string
true로 설정하면 긴 컨텍스트 모드가 활성화되어 한도가 64k에서 262k로 늘어납니다. 컨텍스트 길이를 참고하세요.
플랫폼의 API 키 페이지에서 키를 생성하세요. 프런트엔드 코드, 공개 저장소 또는 클라이언트 설치 패키지에 API 키를 포함하지 마세요.

모델 정보

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

엔드포인트

요청 매개변수

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

state

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

questions

질문 모음입니다. 직접 지정한 질문 이름이 키가 되며, 응답의 answers에서도 같은 이름으로 답변이 반환됩니다. 각 값은 질문 정의입니다.
  • 질문은 서로 독립적입니다. 각 질문은 state만 평가하며 다른 질문의 답변을 보지 않습니다.
  • 선택지와 단계 설명이 구체적일수록 판단이 안정적입니다. 선택지의 의미가 겹치지 않도록 작성하세요.

assets

이미지 모음입니다. 키는 직접 지정한 자리표시자이며 이미지마다 새 UUID 사용을 권장합니다. 자리표시자가 state, 질문의 instructions 또는 criteria 내 문자열에 나타나면 해당 이미지로 대체됩니다. 다음 예제는 흰 배경에 빨간 직사각형이 있는 280 × 280 PNG를 사용합니다. 아래 이미지 판단 및 경계 상자 예제에서도 사용합니다. 최소 크기보다 작은 자리표시자 이미지로 바꾸지 마세요.
공식 규격상 assets가 포함된 요청에는 TypeSafe-Danger-Zone-Images: true 헤더가 필수입니다. 이미지 입력과 Box 질문은 초기 기능이므로 버전에 따라 요청 형식, 답변, 제한이 바뀔 수 있습니다.

이미지 제한

이미지는 다음 공식 제한을 모두 충족해야 합니다. 크기가 맞지 않으면 자동 조정되지 않으며 요청 전체가 실패합니다. 모든 asset은 state, instructions 또는 criteria에서 참조되어야 합니다. 너무 작은 이미지, 잘못된 형식, 참조되지 않은 asset 등은 보통 400을 반환합니다. 파일, 이미지 크기 또는 요청 크기 상한 초과 시 413을 반환할 수 있습니다.

multipart 이미지 업로드

이미지가 크거나 여러 장이면 Base64 대신 multipart/form-data로 원본 파일을 업로드할 수 있습니다.
  • 첫 번째 파트의 이름은 request이며 JSON 요청 본문을 담습니다(Content-Type: application/json).
  • 이후 이미지마다 별도 파트를 사용합니다. 파트 이름은 고유하고 비어 있지 않아야 하며 asset의 part에서 참조해야 합니다.

컨텍스트 길이

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

호출 예제

성공 응답

Box 답변

응답 필드

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

과금 안내

계산식: 요청당 비용 = usage.input_tokens / 1,000,000 × 입력 단가
  • 위 금액은 공식 기본 단가입니다. 실제 과금에는 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만 들어갈 수도 있습니다. 이 필드만으로 원인을 단정하지 마세요. 오류 형식 예시는 다음과 같습니다.
공식 API의 매개변수 검증 실패는 422를 반환할 수 있지만, 게이트웨이는 400과 error 객체로 감싸 반환할 수 있습니다. HTTP 상태 코드를 먼저 확인하고 오류 필드를 읽으세요. 모든 게이트웨이가 공식 detail 구조나 구체적인 오류 메시지를 그대로 반환한다고 가정하지 마세요.
자주 발생하는 문제:

공식 참고 문서