Jev AI API 활용방법: 초보도 바로 호출하는 시작하기

Jev AI API 활용방법. 키 발급부터 POST /v1/systemone 호출 예시, 결과 읽는 법, 초보가 바로 붙여 넣는 curl과 활용 팁까지 정리했습니다.

Jev AI API는 채팅 창이 아닙니다. 글(state)과 질문(questions)을 한 번에 보내면, 코드가 바로 읽을 선택·점수·확률만 돌려줍니다. 이번 글은 앞선 시작하기에 이어, 초보가 키를 받아 첫 호출까지 가는 Jev AI API 활용방법만 적습니다.

시작하기, API key 발급

1. 로그인으로 들어갑니다. 콘솔 루트는 비로그인 시 여기로만 넘어갑니다.
2. 로그인된 뒤 Keys에서 키를 만듭니다.
3. 서버 환경변수 TYPESAFE_API_KEY에만 넣습니다. 브라우저, 블로그, 메신저에 붙이지 마세요.

평가 주소는 하나입니다. POST https://api.typesafe.ai/v1/systemone. 스트리밍·배치 문서는 없습니다. 모델 목록은 GET /v1/models입니다. 헤더는 Authorization: Bearer …와 Content-Type: application/json이면 됩니다.

호출 기본 구조

터미널에 아래를 그대로 넣으면 됩니다. 키만 본인 값으로 바꿉니다.

export TYPESAFE_API_KEY="여기에_키"

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Hi, I have been trying to connect my Stripe account for 3 days and the integration keeps failing. I am losing sales. Please help ASAP.",
    "model": "jev-latest",
    "questions": {
      "is_urgent": {
        "type": "noul",
        "instructions": "Does this message express urgency?"
      }
    }
  }'

요청은 항상 세 덩어리입니다. state는 판단 대상, model은 누구한테 물을지, questions는 무엇을 물을지입니다. 질문 키(is_urgent)는 응답을 찾을 이름일 뿐 모델에 전달되지 않습니다. 실제 질문은 instructions에 쓰세요.

활용방법, 질문은 세 가지로 구성됩니다.

한 호출에 섞어 넣을 수 있습니다. 같은 state는 한 번만 내고, 질문은 병렬로 봅니다.

type	물을 때	응답에서 볼 값
noul	예/아니오	noul (0~1)
choice	닫힌 칸 중 하나	choice, probabilities, confidence
score	단계가 있는 점수	score, legend, probabilities, confidence

티켓 한 장을 부서·화남·긴급으로 나누는 예입니다. 공식 퀵스타트와 같은 모양입니다.

{
  "state": "Hi, I have been trying to connect my Stripe account for 3 days and the integration keeps failing. I am losing sales. Please help ASAP.",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this",
      "criteria": {
        "billing": "Payment or subscription issues",
        "technical": "Bugs or integration problems",
        "sales": "Pricing or account questions"
      }
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated the customer appears",
      "criteria": [
        "Calm, just stating facts",
        "Frustrated but civil",
        "Very angry, strong language"
      ]
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "The message conveys urgency or time-sensitivity"
    }
  }
}

Node 20+라면 SDK로 같은 요청을 이렇게 보냅니다.

npm install @typesafe-ai/sdk

import { choice, noul, score, TypeSafeClient } from "@typesafe-ai/sdk";

const client = new TypeSafeClient(); // TYPESAFE_API_KEY

export async function classifyTicket(ticket: string) {
  const response = await client.systemOne({
    model: "jev-1.13.0",
    state: ticket,
    questions: {
      department: choice("Which team should handle this", {
        billing: "Payment or subscription issues",
        technical: "Bugs or integration problems",
        sales: "Pricing or account questions",
      }),
      frustration: score("How frustrated the customer appears", [
        "Calm, just stating facts",
        "Frustrated but civil",
        "Very angry, strong language",
      ]),
      isUrgent: noul("The message conveys urgency or time-sensitivity"),
    },
  });

  const dept = response.answers.department;
  return {
    model: response.model,
    department: dept.choice,
    confidence: dept.confidence,
    queue: dept.confidence < 0.7 ? "human" : "auto",
    urgent: response.answers.isUrgent.noul,
  };
}

0.7은 시작점일 뿐입니다. 우리 글로 다시 잡으세요.

결과는 자연어가 아닌 숫자로 나타납니다.

문서 예시 형태는 아래와 같습니다. 숫자는 참고용이고, 내가 받은 값이 답입니다.

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "technical",
      "confidence": 0.78
    },
    "is_urgent": {
      "type": "noul",
      "noul": 1.0
    }
  }
}

• choice로 큐를 나눕니다.
• confidence가 낮으면 자동 처리하지 않습니다.
• Noul 0.5 근처는 “모르겠다”에 가깝습니다.
• 응답 model에 실제 버전이 찍힙니다. 별칭 jev-latest는 문서 기준 현재 jev-1.13.0입니다. 임계값을 걸면 버전을 고정하세요.

공식 문서의 오류 코드만 적습니다. 401은 키, 422는 요청 모양, 429는 한도, 529는 서버가 바쁠 때입니다. SDK는 재시도를 기본으로 한다고 문서에 적혀 있습니다. curl이면 바로 다시 보내지 말고 간격을 두세요.

API 활용 팁

1. 같은 글에 대한 질문은 한 요청에 모으세요. 호출을 쪼개면 state 토큰을 다시 냅니다.
2. “어떻게 답할까”를 한 질문에 넣지 마세요. 판단만 받고, 다음 행동은 코드가 합니다.
3. 키는 서버에만 둡니다. 프론트에서 직접 치면 키가 노출됩니다.
4. 한글 원문은 넣어도 됩니다. instructions는 영어가 문서 기준으로 더 잘 맞습니다.
5. 사진 파일은 못 넣습니다. 글이나 JSON만 됩니다.
6. 콘솔이 안 열리면 로그인과 상태 페이지를 보세요. 옛 대기열 주소는 404입니다.

최신 스펙은 API 문서와 Models를 보면 됩니다. 속도가 몇 배라는 숫자는 적지 않습니다.

자주 묻는 질문

Jev AI API 활용방법, 채팅 URL이 있나요?
없습니다. POST /v1/systemone이 전부입니다.

초보도 curl만으로 시작하기가 되나요?
됩니다. 키와 위의 명령이면 첫 답을 볼 수 있습니다.

질문을 여러 번 나눠 보내야 하나요?
같은 state면 한 번에 보내는 편이 맞습니다.

문서 예시 숫자와 내 결과가 다르면요?
내 응답이 기준입니다. 예시 값을 테스트 expected로 쓰지 마세요.

참고: API · Quick start · Models
확인 기준: 2026-09-23. 로그인 HTTP 200, POST /v1/systemone 허용 확인. 키를 넣은 실호출.

#JevAI #JevAIAPI #JevAIAPI활용방법 #JevAI시작하기 #JevAI초보