Jev API 문서

개요

Jev는 전달한 하나의 state—고객 문의, 채팅 로그, 도구 호출, 텍스트나 JSON—를 타입 있는 질문들로 평가하고 코드가 분기할 수 있는 구조화된 답을 반환합니다. 텍스트를 생성하지 않습니다.

한 번의 요청으로 최대 8개 질문을 물을 수 있으며, 함께 평가되어 state 입력 비용을 공유합니다. 요청 본문은 TypeSafe SystemOne API와 동일한 형태입니다—기존 통합을 옮기려면 base URL과 Bearer 키만 바꾸면 됩니다.

• POST https://jevmodel.org/v1/systemone — 유일한 결정 엔드포인트.
• CORS 개방(access-control-allow-origin: *)으로 어떤 오리진에서도 응답합니다. 그래도 키는 서버에 두세요.
• 플레이그라운드는 브라우저 세션으로 동일한 요청을 보냅니다—미리보기가 곧 전송 내용입니다.

인증

모든 API 호출에 jevmodel.org API 키가 필요합니다. 대시보드 → API keys에서 생성하세요. 키는 sk-로 시작하며 생성 시 한 번만 표시됩니다. JEVMODEL_API_KEY 같은 환경 변수로 저장하세요.

Authorization: Bearer $JEVMODEL_API_KEY

키는 계정 토큰 잔액에 귀속되며 대시보드에서 폐기할 수 있습니다. 클라이언트 코드에 넣거나 저장소에 커밋하지 마세요—유출 시 폐기 후 재발급. 플레이그라운드는 로그인된 브라우저 세션으로 인증하므로 키가 필요 없습니다.

HTTP 엔드포인트

Bearer 인증과 함께 JSON 본문을 평가 엔드포인트로 전송합니다:

POST /v1/systemone HTTP/1.1
Host: jevmodel.org
Authorization: Bearer $JEVMODEL_API_KEY
Content-Type: application/json
Idempotency-Key: ticket-4821-run-1   # optional

Idempotency-Key는 선택 사항(최대 100자). 같은 키로 재시도하면 원래 과금 레코드를 재사용하므로 같은 입력이 이중 과금되지 않습니다.

curl -X POST https://jevmodel.org/v1/systemone \
  -H "Authorization: Bearer $JEVMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "The customer has been billed twice and wants a refund today.",
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Which queue should own this ticket?",
        "criteria": {
          "billing": "Payments, refunds, invoices",
          "technical": "Product errors and usage problems",
          "sales": "Pricing, upgrades, new business"
        }
      },
      "escalate": {
        "type": "noul",
        "instructions": "Does this need a human right now?"
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this for the customer?",
        "criteria": ["routine", "soon", "urgent", "critical"]
      }
    }
  }'

요청 본문

state와 questions 맵을 가진 하나의 JSON 객체:

{
  "model": "jev-latest",
  "state": "The customer has been billed twice and wants a refund today.",
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Which queue should own this ticket?",
      "criteria": {
        "billing": "Payments, refunds, invoices",
        "technical": "Product errors and usage problems",
        "sales": "Pricing, upgrades, new business"
      }
    },
    "escalate": {
      "type": "noul",
      "instructions": "Does this need a human right now?"
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this for the customer?",
      "criteria": ["routine", "soon", "urgent", "critical"]
    }
  }
}

각 질문에는 type과 instructions(최대 1,800자)이 필요하며 무엇을 판단할지 지시합니다. criteria가 답 공간을 제공—choice·score는 필수, noul은 선택.

질문 유형

애플리케이션이 활용할 수 있는 답 형태를 고르세요.

직렬화된 criteria는 질문당 최대 2,000자. 검증 실패는 토큰 예약 전 422를 반환합니다—잘못된 요청은 과금되지 않습니다.

응답 JSON

200 응답은 모델 출력 자체입니다: 확정된 모델, 질문명별 답, usage. 아래 수치는 예시입니다—실제 출력은 실제 요청으로 확인하세요.

{
  "model": "jev-latest",
  "answers": {
    "route": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.93, "technical": 0.05, "sales": 0.02 },
      "confidence": 0.93
    },
    "escalate": {
      "type": "noul",
      "noul": 0.12
    },
    "urgency": {
      "type": "score",
      "score": 1.4,
      "confidence": 0.88
    }
  },
  "usage": { "input_tokens": 136, "output_tokens": 18 }
}

• answers는 질문명을 키로 합니다—물은 필드만 읽으면 됩니다.
• choice는 선택된 레이블로 분기하고 전체 분포가 필요하면 probabilities를 확인합니다.
• noul은 P(yes)—임계값은 코드가 정합니다.
• usage.input_tokens가 이번 호출의 실제 과금량입니다. 출력 토큰은 무료.

과금

API는 입력 토큰만 과금합니다—출력은 무료. 각 호출은 추정치를 먼저 예약한 뒤 모델이 보고한 실제 usage.input_tokens로 정산합니다. 업스트림 실패 시 예약분은 자동 전액 환불됩니다.

• 로그인하면 100,000 입력 토큰 무료. 유료 팩은 $9.90부터, 만료 없음.
• 잔액 부족 시 Jev 호출 전 402 반환.
• 모든 200 응답의 X-Tokens-Remaining이 정산 후 잔액.
• 직접 추정: ceil(JSON.stringify({state, questions}).length / 4).

모델과 한도

jev-latest가 기본이며 현재 제공되는 모델입니다—model 필드는 선택. 플레이그라운드의 Laya 변형은 곧 출시 예정이며 이 엔드포인트에는 아직 없습니다.

위 수치는 API 검증기 기준이며 업스트림 모델에 별도의 컨텍스트 한도가 있을 수 있습니다.

오류와 재시도

오류는 기계 판독용 type과 사람용 message를 가진 JSON으로 반환됩니다:

{
  "error": {
    "type": "invalid_request_error",
    "message": "At most 8 questions per request."
  }
}

429와 502는 지수 백오프로 재시도—레이트 창은 분 단위라 짧은 대기면 보통 충분합니다. 재시도 시 Idempotency-Key를 보내 같은 과금 레코드로 정산되게 하세요.

에이전트용 MCP 서버

jevmodel.org는 https://jevmodel.org/mcp에서 Streamable HTTP 원격 MCP 서버도 운영합니다. 4개 도구—jev_decide(state+questions 전체 계약), jev_noul, jev_choice, jev_score—을 제공해 Claude Code, Cursor, Cline 같은 코딩 에이전트가 HTTP 없이 Jev를 호출할 수 있습니다.

claude mcp add --transport http jev https://jevmodel.org/mcp \
  --header "Authorization: Bearer $JEVMODEL_API_KEY"

• 이 API와 같은 Authorization: Bearer sk-… 키와 같은 토큰 잔액—tools/call은 입력 토큰만 과금.
• initialize, ping, tools/list는 인증 불필요. tools/call만 키를 사용.
• GET /mcp는 에이전트와 사람용 JSON 디스커버리 카드를 반환.

Claude Code·Cursor 설정 명령과 맞춤 agent skill(판단 플레이북)은 에이전트 도구 페이지에 있습니다.

에이전트 도구 가이드 →

플레이그라운드에서 API로

먼저 플레이그라운드에서 시나리오를 만드세요—요청 미리보기가 앱이 보낼 정확한 JSON을 보여주고 Copy API example이 대응 cURL을 줍니다. 답이 만족스러우면 대시보드에서 키를 만들어 브라우저 세션을 Bearer 인증으로 교체합니다.

더 읽기: Jev 사용법이 첫 호출을 끝까지 안내하고, Jev API 예제에 각 질문 유형의 프로덕션 패턴이 있습니다.