Jev API 키 발급 방법 (TypeSafe AI)

Jev는 TypeSafe AI의 의사 결정 모델입니다. 상태 조각과 유형화된 질문 세트를 전송하면 산문 대신 확률로 응답합니다. 이 가이드는 Jev API 키와 첫 번째 요청을 다룹니다. Jev가 무엇이고 텍스트 대신 숫자를 반환하는 이유에 대한 배경 지식은 먼저 Jev란 무엇인가를 읽어보세요. 검색 결과가 지저분하므로 명확히 하자면, 이것은 TypeSafe AI 모델인 Jev이며, 유튜버 FaZe Jev나 일본뇌염(JEV) 백신이 아닙니다.

Jev API 키는 다른 베어러 토큰과 마찬가지로 작동합니다. 이 패턴이 처음이라면 API 키란 무엇인가에서 기본 사항을 다룹니다. 직접 API 접근은 초기 액세스 중이므로, 첫 번째 단계는 대기 목록에서 벗어나는 것입니다. 그 후 키를 생성하고, 요청 형태를 학습하고, curl 및 Python SDK로 엔드포인트를 호출하고, 확률 필드를 읽고, 해당 확률에 대한 어설션을 사용하여 Apidog에 요청을 연결할 것입니다. 기다릴 수 없다면, 동일한 모델이 대기 목록 없이 Vercel AI Gateway에 나와 있으며, FAQ에서 해당 경로를 다룹니다.

1단계: 초기 액세스를 얻은 다음 키를 생성합니다

이 글을 쓰는 시점에서 Jev는 초기 액세스 상태입니다. TypeSafe의 출시 게시물에서는 "가능한 한 빨리 개발자들을 대기 목록에서 불러올 것"이라고 밝히고 있으므로, typesafe.ai에서 대기 목록에 가입하고 콘솔 초대장을 기다리십시오. 아직 셀프 서비스 가입은 없습니다. 콘솔 계정이 활성화되면 console.typesafe.ai/settings/keys로 이동하여 키를 생성합니다. 한 번 복사한 후 비밀번호처럼 다루십시오.

코드로 붙여넣는 대신 환경 변수로 내보내십시오:

export TYPESAFE_API_KEY="ts_..."

공식 curl 예제와 Python SDK 모두 환경에서 TYPESAFE_API_KEY를 읽으므로, 하나의 변수가 아래의 모든 예제를 커버합니다. 키가 커밋에 포함된 경우, 콘솔에서 키를 교체하고 저장소 전반에 걸쳐 API 키 누출 검사를 실행하십시오.

2단계: 요청 형태 이해

모든 Jev 호출은 세 개의 본문 필드를 가진 단일 POST https://api.typesafe.ai/v1/systemone이며, TypeSafe API 참조에 문서화되어 있습니다:

각 질문은 다음 세 가지 기본 요소 중 하나입니다:

응답에는 model 및 usage.input_tokens / usage.output_tokens도 포함됩니다. 다른 유형의 질문들은 하나의 상태를 공유하고 한 번의 왕복으로 다시 돌아올 수 있습니다.

3단계: curl을 사용하여 첫 번째 요청 만들기

이 요청은 하나의 지원 티켓에 대해 세 가지 기본 요소를 모두 실행합니다:

curl https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "My card was charged twice for one order and nobody has replied in three days.",
    "questions": {
      "needs_review": {
        "type": "noul",
        "instructions": "Does this ticket need a human agent?",
        "criteria": {
          "true": "money, legal, or an unanswered complaint",
          "false": "a routine question a bot can close"
        }
      },
      "route": {
        "type": "choice",
        "instructions": "Route this ticket to a team.",
        "criteria": {
          "billing": "payment or charge problems",
          "shipping": "delivery problems",
          "technical": "application bugs"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this ticket?",
        "criteria": ["low", "medium", "high"]
      }
    }
  }'

응답은 다음과 같습니다 (값은 예시입니다):

{
  "model": "jev-1.13.0",
  "answers": {
    "needs_review": { "type": "noul", "noul": 0.97 },
    "route": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.98,
      "probabilities": { "billing": 0.98, "shipping": 0.01, "technical": 0.01 }
    },
    "urgency": {
      "type": "score",
      "score": 1.6,
      "confidence": 0.62,
      "legend": { "0": "low", "1": "medium", "2": "high" },
      "probabilities": { "0": 0.02, "1": 0.36, "2": 0.62 }
    }
  },
  "usage": { "input_tokens": 190, "output_tokens": 0 }
}

4단계: 확률 필드 읽기

숫자를 정확하게 읽으십시오:

• noul은 "예"의 확률입니다. 0.97은 Jev가 이 티켓에 사람이 필요하다고 97% 확신한다는 의미입니다.
• choice는 가장 확률이 높은 옵션이고, probabilities는 모든 옵션을 나열하며, confidence는 선택이 얼마나 결정적이었는지 알려줍니다. 0.98의 경로는 자동화하기에 안전하지만, 0.47의 차순위와 함께 0.51의 경로는 동전 던지기입니다.
• score는 정렬된 수준에 걸친 확률 가중치 위치이므로, 1.6은 "보통"(1)과 "높음"(2) 사이에 있습니다. legend는 각 인덱스를 해당 레이블에 매핑하고, probabilities는 전체 분포를 보여줍니다.

출력은 레이블이 아닌 분포이므로, 모델이 아닌 사용자가 임계값을 설정합니다. 이것이 6단계의 어설션이 숫자를 테스트하는 이유입니다.

5단계: Python SDK를 이용한 동일한 호출

SDK를 설치하십시오. 클라이언트는 환경에서 TYPESAFE_API_KEY를 가져옵니다:

pip install typesafe-sdk

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state="My card was charged twice for one order and nobody has replied in three days.",
        questions={
            "needs_review": Noul(
                instructions="Does this ticket need a human agent?",
                criteria={"true": "money, legal, or an unanswered complaint",
                          "false": "a routine question a bot can close"},
            ),
            "route": Choice(
                instructions="Route this ticket to a team.",
                criteria={"billing": "payment or charge problems",
                          "shipping": "delivery problems",
                          "technical": "application bugs"},
            ),
            "urgency": Score(
                instructions="How urgent is this ticket?",
                criteria=["low", "medium", "high"],
            ),
        },
    )

print(response.nouls["needs_review"].noul)
print(response.choices["route"].choice, response.choices["route"].probabilities)
print(response.scores["urgency"].score)

응답 객체의 질문들은 유형별로 그룹화됩니다(nouls, choices, scores). 동일한 형태의 JavaScript SDK도 있으며, Vercel AI Gateway를 이미 사용 중이라면 AI SDK 7의 experimental_evaluate는 typesafe-ai/jev로 모델을 호출합니다. 단 한 가지 차이점은 부울 질문 유형이 noul 대신 probability 필드를 반환한다는 것입니다.

6단계: Apidog에 Jev API 키 저장 및 테스트

Curl은 키가 한 번 작동한다는 것을 증명합니다. Apidog는 전체 팀을 위해 요청을 다시 실행하고, 어설션을 추가하고, 모의 테스트를 가능하게 합니다.

키를 비밀 변수로 저장하십시오. TypeSafe라는 환경을 생성하고 TYPESAFE_API_KEY를 비밀로 추가하여 해당 값이 UI에서 마스킹되고 내보내지지 않도록 하십시오. Apidog 환경 및 비밀 변수에서 설정 과정을 안내합니다. 요청의 인증을 Bearer Token으로 설정하고 값으로 {{TYPESAFE_API_KEY}}를 사용하십시오.

POST 요청을 구축하십시오. https://api.typesafe.ai/v1/systemone에 POST를 추가하고, 3단계의 JSON 본문을 붙여넣고, 전송하십시오. 응답 패널은 답변 트리를 렌더링하므로, 어설션을 작성하기 전에 확률을 확인할 수 있습니다.

산문이 아닌 확률에 대해 어설션을 하십시오. 시각적 어설션 빌더에서 관심 있는 필드를 JSONPath 표현식으로 지정하십시오:

• $.answers.needs_review.noul은 0.9보다 큽니다.
• $.answers.route.choice는 billing과 같습니다.
• $.answers.route.probabilities.billing은 0.8보다 큽니다.
• $.answers.urgency.score는 1보다 크거나 같습니다.
• $.usage.input_tokens는 1000보다 작습니다.

스크립트가 더 좋다면, 포스트 프로세서는 익숙한 pm API를 허용합니다:

const body = pm.response.json();
pm.test("ticket flagged for a human", () => {
  pm.expect(body.answers.needs_review.noul).to.be.above(0.9);
});
pm.test("routed to billing", () => {
  pm.expect(body.answers.route.choice).to.eql("billing");
});

이를 테스트 시나리오로 저장하십시오. 요청을 작은 티켓 CSV와 예상 경로가 포함된 테스트 시나리오에 넣고, 지침이나 기준이 변경될 때마다 실행하십시오. 프롬프트 편집은 코드 변경입니다. 10행 시나리오는 0.95를 0.6으로 조용히 이동시키는 편집을 잡아냅니다. 동일한 시나리오는 Apidog CLI를 통해 CI에서 실행되므로, 회귀는 병합을 차단합니다.

선언된 응답 형태를 모의하십시오. 엔드포인트에 응답 스키마를 정의하고(세 가지 답변 객체와 usage), Apidog의 스마트 모의는 즉시 현실적인 가짜 확률을 제공합니다. 프론트엔드는 백엔드가 배송되기 전에 모의를 기반으로 "검토 필요" 배지 및 라우팅 UI를 구축할 수 있으며, 이후 환경 변경 한 번으로 모의 URL을 실제 엔드포인트로 교체할 수 있습니다.

좌석 계획: Apidog의 무료 플랜은 4명의 사용자를 포함하며, 유료 등급은 좌석당 요금입니다.

코드 내 임계값

어설션이 통과되면, 동일한 숫자들이 프로덕션 로직을 구동합니다. 임계값을 한곳에 유지하고 이름을 지정하십시오:

REVIEW_THRESHOLD = 0.9
AUTO_ROUTE_CONFIDENCE = 0.85

needs_review = response.nouls["needs_review"].noul >= REVIEW_THRESHOLD
route = response.choices["route"]

if route.confidence >= AUTO_ROUTE_CONFIDENCE and not needs_review:
    assign(ticket, team=route.choice)
else:
    queue_for_human(ticket, suggested=route.choice)

모든 결정에 대해 전체 probabilities 맵을 기록하여 나중에 실제 데이터를 통해 임계값을 조정할 수 있도록 하고, 신뢰도가 낮을 때는 수동 검토를 기본으로 설정하십시오. 모델이 확신하지 못한다는 것을 알려주는 것입니다.

제한, 가격 및 모델

TypeSafe 모델 페이지에서 직접 가져온 정보입니다:

이 가격으로 백만 건의 짧은 티켓을 실행하는 데 10달러 미만이 듭니다. TypeSafe는 또한 Jev가 고객 요청이나 응답을 기반으로 학습되지 않는다고 밝힙니다.

일반적인 오류 및 해결 방법

반복 작업 중에는 422 오류가 가장 많이 발생할 것입니다. 6단계의 엔드포인트 스키마는 요청이 기기를 떠나기 전에 대부분의 오류를 잡아냅니다.

FAQ

Jev API 무료 티어가 있습니까? 공개 문서에는 토큰당 가격만 나열되어 있으며 무료 티어나 초기 크레딧에 대한 설명은 없으며, 현재 액세스 자체도 대기 목록에 있습니다. 초대장을 받으면 콘솔에서 현재 제공 사항을 확인하고, 다른 곳에서 본 수치는 비공식적인 것으로 간주하십시오.

하나의 요청으로 여러 답변을 받을 수 있습니까? 예. questions는 맵이므로, noul, choice, score 모두 하나의 상태에 대해 단일 호출로 실행될 수 있습니다. 세 번의 요청보다 저렴하며, 하나의 입력을 공유하므로 답변의 일관성을 유지합니다.

이것이 채팅 모델의 구조화된 출력과 어떻게 다릅니까? 구조화된 출력은 언어 모델이 유효한 JSON을 내보내도록 강제하지만, 내부 값은 여전히 생성된 토큰이며, "신뢰도" 필드는 모델이 자신에 대해 작성한 텍스트입니다. Jev는 측정된 확률을 기본 출력으로 반환하므로, noul > 0.9를 어설션하고 비교를 신뢰할 수 있습니다.

Vercel을 사용 중이라면 TypeSafe의 SDK가 필요합니까? 아니요. Vercel AI SDK는 모델 ID typesafe-ai/jev를 통해 experimental_evaluate로 Jev를 노출합니다. TypeSafe 키 대신 AI Gateway 키로 인증하며, 부울 답변은 probability로 반환됩니다.

다음 단계

이제 Jev API 키, curl 및 Python에서 작동하는 요청, 그리고 noul, choice, score에 대한 명확한 이해를 갖게 되었습니다. 요청을 Apidog에 넣고, 확률 어설션을 추가하고, 프롬프트 편집이 코드처럼 테스트되도록 테스트 시나리오를 저장하십시오. 따라하려면 Apidog를 다운로드하십시오.