GPT-6 Sol·Claude Opus 5.5 출시GPT-6 Sol 요금은 5.6 Sol의 절반
블로그
API 설정

Jev API 사용법

Jev 고유 API로 타입별 판단을 앱에 연결하세요.

약 11분OmniaKey
Jev APIAPI 문서JSONPythonNode.js

Jev API는 애플리케이션이 정의한 질문에 따라 텍스트를 평가합니다. state, model, questions를 보내면 같은 질문 ID에 대응하는 타입별 판단이 answers에 돌아옵니다. 자유 형식의 채팅 답변에서 나중에 분류값을 추출하는 방식이 아닙니다.

이 글은 연동 절차를 다룹니다. 모델의 용도, 가격 배경과 한계는 Jev 모델 설명을 참고하세요.

확인일: 2026년 9월 28일. 요청과 응답은 TypeSafe 공식 문서, 게이트웨이 경로는 OmniaKey 구현과 대조했습니다. 예제는 오프라인으로 확인했으며 새로운 유료 성능 테스트는 진행하지 않았습니다. 공식 직결 가격과 한도가 게이트웨이에 자동 적용되지는 않습니다.

엔드포인트와 API 키부터 맞추기

서비스POST 엔드포인트인증 정보
OmniaKeyhttps://api.omniakey.com/v1/alpha/searchjev-latest에 접근 가능한 OmniaKey API 키
TypeSafe 직접 연결https://api.typesafe.ai/v1/systemoneTypeSafe API 키

두 경로 모두 Authorization: Bearer ...와 Jev 고유 요청 본문을 사용합니다. 다른 서비스의 키를 보내지 마세요. 게이트웨이 경로도 /v1/chat/completions가 아니며 state를 messages로 바꾸면 계약이 달라집니다.

권한을 제한한 키를 만든 뒤 현재 Jev 제공 경로를 확인하고 로컬 환경에 OMNIAKEY_API_KEY를 설정하세요. 키를 브라우저 코드, Git, 스크린샷에 넣지 마세요. 일반 절차는 API 빠른 시작(영문)에 있습니다.

완전한 JSON 요청 만들기

아래 내용을 jev-request.json으로 저장합니다. 같은 고객 문의에 대해 담당 부서, 불만 정도, 긴급성을 한 번에 판단합니다. TypeSafe는 현재 영어에서 가장 좋은 성능을 보인다고 설명하므로 예제 입력은 영어로 유지했습니다. 한국어 업무는 자체 표본으로 평가하세요.

json
{
  "model": "jev-latest",
  "state": "My payouts have failed for three days. Please help me resolve this today.",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this message?",
      "criteria": {
        "billing": "Payments, invoices, or refunds",
        "technical": "Bugs, outages, or integrations",
        "sales": "Pricing, upgrades, or new accounts"
      }
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": ["Calm", "Frustrated", "Very angry"]
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "Does the message express a time-sensitive need?"
    }
  }
}

질문 ID는 요청과 응답을 연결합니다. TypeSafe에 따르면 ID 자체는 추론에 사용되지 않으므로 실제 과제는 키 이름뿐 아니라 instructions에 적어야 합니다. state에는 텍스트를 담은 JSON 객체나 배열도 넣을 수 있습니다.

bash
curl --fail-with-body https://api.omniakey.com/v1/alpha/search \
  -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @jev-request.json

TypeSafe에 직접 연결하려면 URL을 https://api.typesafe.ai/v1/systemone, 키를 $TYPESAFE_API_KEY로 바꿉니다. JSON 형식은 유지하고 해당 계정에서 허용하는 모델 이름을 확인하세요.

Choice·Score·Noul 응답 읽기

유형정의할 내용반환 필드해석
choice선택지와 설명, 최대 255개choice, probabilities, confidence선택된 라벨과 전체 선택지의 확률 분포
score순서가 있는 2–10단계 기준score, legend, probabilities, confidence확률로 가중한 단계 값이며 소수일 수 있음
noul예/아니요 질문, true / false 기준은 선택 사항noul0~1 사이의 ‘예’ 확률이며 불리언이 아님

응답에는 model과 usage.input_tokens / usage.output_tokens도 있습니다. 현재 jev-latest는 jev-1.13.0을 가리키지만 별칭은 바뀔 수 있으므로 실제 응답 버전을 기록하세요.

3단계 기준에서 1.05는 단계 1보다 조금 높은 값이지 100점 만점의 1.05점이 아닙니다. legend를 함께 읽으세요. Noul 값 0.8만으로 환불 같은 동작을 승인해서도 안 됩니다. 라벨이 있는 업무 표본으로 임계값을 정해야 하며, 분포에서 계산되는 confidence가 판단의 정확성을 보장하지는 않습니다.

아래는 전체 응답 구조를 보여 주는 예시이며, 실제 API 호출로 얻은 결과가 아닙니다. 답변 값과 토큰 수는 설명용이므로 실제 결과와 다를 수 있습니다.

json
{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": {
        "billing": 0.88,
        "technical": 0.12,
        "sales": 0.0
      },
      "confidence": 0.81
    },
    "frustration": {
      "type": "score",
      "score": 1.05,
      "legend": {
        "0": "Calm",
        "1": "Frustrated",
        "2": "Very angry"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.95,
        "2": 0.05
      },
      "confidence": 0.92
    },
    "is_urgent": {
      "type": "noul",
      "noul": 0.8
    }
  },
  "usage": {
    "input_tokens": 320,
    "output_tokens": 72
  }
}

Python과 Node.js 호출 예제

아래 예제는 jev-request.json을 읽고 한 번 요청합니다. OpenAI 형태의 choices를 가정하지 않고 원래 응답을 출력합니다. 운영용 클라이언트에는 뒤에서 설명하는 제한된 재시도 정책을 추가하세요.

python
import json
import os
import urllib.error
import urllib.request
from pathlib import Path

request = urllib.request.Request(
    "https://api.omniakey.com/v1/alpha/search",
    data=Path("jev-request.json").read_bytes(),
    headers={
        "Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise SystemExit(f"Jev request failed: HTTP {error.code}") from None

print(result["model"])
print(json.dumps(result["answers"], indent=2))
javascript
import { readFile } from 'node:fs/promises';

const key = process.env.OMNIAKEY_API_KEY;
if (!key) throw new Error('Set OMNIAKEY_API_KEY first');

const response = await fetch('https://api.omniakey.com/v1/alpha/search', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${key}`,
    'Content-Type': 'application/json',
  },
  body: await readFile('jev-request.json', 'utf8'),
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error(`Jev request failed: HTTP ${response.status}`);

const result = await response.json();
console.log(result.model);
console.log(result.answers);

Python 3 또는 내장 fetch와 AbortSignal.timeout이 있는 Node.js를 사용합니다. HTTP 예제일 뿐 OpenAI SDK가 Jev 스키마를 직접 지원한다는 뜻은 아닙니다. TypeSafe 자체 SDK는 공식 문서를 확인하세요.

컨텍스트 길이, 호출 제한과 비용

두 조건을 동시에 지켜야 합니다. 전체 요청은 64K 토큰, state와 가장 긴 질문 하나의 합은 32K 토큰 이하여야 합니다. 무관한 정보를 줄이고 같은 상태가 필요한 질문만 묶으세요.

TypeSafe는 초당 250,000 토큰, 분당 1,200회 요청을 게시하며 초기 제공 기간에는 바뀔 수 있다고 설명합니다. 계정의 처리량 제한이지 한 요청의 속도나 OmniaKey 계정에 대한 보장이 아닙니다. 게이트웨이에 별도 제한이 있을 수 있습니다.

확인된 공식 직결 가격은 입력 100만 토큰당 $0.042, 출력 토큰 무료입니다. 출력 사용량은 계속 반환됩니다. API 전체가 무료이거나 게이트웨이의 과금 단위가 같다는 뜻은 아닙니다. 현재 모델 견적과 사용 기록을 확인하고 Jev 가격·제한 설명을 참고하세요.

OmniaKey의 현재 Jev 요금은 요청 건수 기준입니다. 게이트웨이 비용을 계산하기 전에 최신 모델 가격과 대시보드 사용 기록을 확인하세요.

인증 오류와 재시도 처리

TypeSafe 직결 상태먼저 확인할 것처리
401키가 해당 서비스용인지, Bearer 헤더가 맞는지인증을 수정하고 같은 잘못된 키로 반복하지 않기
422필수 필드, 질문 유형, criteria 구조오류가 지목한 필드 수정
429요청 수 또는 토큰 한도있으면 Retry-After 준수, 상한 있는 지수 백오프와 지터 사용
529일시적인 과부하시도 횟수와 총 대기 시간을 제한해 재시도

이는 공식 직결 문서의 상태 의미입니다. 게이트웨이는 인증·검증·상위 공급자 오류를 다른 형식으로 반환할 수 있습니다. 사용할 수 없는 경로라면 URL과 정확한 model ID도 확인하세요. 공유하는 진단에 키나 비공개 요청 본문을 넣지 마세요.

평가와 후속 업무 동작은 분리해야 합니다. 분류 재시도가 이메일 두 번 발송이나 중복 환불을 일으켜서는 안 됩니다. 계속 실패하면 명시적인 오류나 검토 절차로 보내고, 확정적인 기본 판단으로 조용히 바꾸지 마세요.

자주 묻는 질문

이 글이 Jev 공식 API 문서인가요?

OmniaKey 연동 가이드입니다. 직결 스키마는 TypeSafe API 레퍼런스, 가격과 한도는 공식 모델 페이지가 기준입니다. 위 표는 두 연결 경로를 구분합니다.

이미지를 보내거나 글을 쓰게 할 수 있나요?

Jev 1.13은 텍스트를 받아 타입별 결정을 반환합니다. 텍스트가 아닌 자료는 먼저 텍스트나 필드로 변환하세요. 설명문, 이미지, 영상 생성에는 다른 모델 또는 처리 단계가 필요합니다.

별칭과 고정 버전 중 무엇을 써야 하나요?

탐색 단계에는 별칭이 편합니다. 임계값이 있는 운영 흐름에서는 지원되는 고정 버전을 평가하고 model을 기록하며, 버전 변경 전에 임계값을 다시 검증하세요. 제공 모델은 경로마다 다를 수 있습니다.

참고 자료