TypeSafe API 호출

HTTP 평가 엔드포인트

요청 본문에는 최상위 필드가 세 개 있습니다. state는 필수이며 문자열, 객체 또는 텍스트 배열을 사용할 수 있습니다. model도 필수이며 문서 예시에서는 jev-latest을 사용합니다. questions는 형식이 지정된 Question 객체의 맵입니다. 각 키는 직접 정하며, 해당 답변은 같은 id 아래에 반환됩니다. 키는 기반 모델로 전송되지 않고 추론에도 사용되지 않습니다.

최소 Noul는 {"state": "도와주세요! 3일째 지급 처리가 실패하고 있습니다.", "model": "jev-latest", "questions": {"is_urgent": {"type": "noul", "instructions": "긴급함이 드러나나요?"}}} 형태입니다. Choice에는 옵션 이름과 설명을 연결하는 criteria 맵이 추가됩니다. Score에는 수준을 순서대로 나열한 criteria 배열이 추가됩니다. 세 형식 모두 type과 instructions를 공유하며, 각자 다른 형태의 criteria를 사용합니다.

https://console.typesafe.ai/settings/keys.에서 API 키를 발급받으세요. HTTP를 직접 호출한다면 retry-after에 따라 429를 처리하세요. Jev 1.13의 속도 제한은 초당 250,000토큰과 분당 1,200회 요청이며 사전 고지 없이 바뀔 수 있습니다. SDK는 기본적으로 백오프를 적용해 재시도합니다. 같은 Bearer 토큰으로 GET /v1/models를 호출하면 모델 목록을 볼 수 있습니다.

공식 SDK

Python: pip install typesafe-sdk. typesafe_sdk에서 TypeSafeClient을 가져옵니다. TypeSafeClient()을 클라이언트로 사용해 client.system_one(state, questions)를 호출합니다. Noul, Choice, Score 같은 생성자는 패키지에 포함되어 있으므로 JSON type 필드를 직접 작성할 필요가 없습니다. 기본 모델은 jev-latest입니다. Python 3.10 이상이 필요합니다.

JavaScript: npm install @typesafe-ai/sdk. "@typesafe-ai/sdk"에서 { TypeSafeClient }를 가져옵니다. 클라이언트는 동일한 엔드포인트와 통신합니다. 런타임은 Node.js 20+입니다. 저장소는 https://github.com/typesafe-ai/typesafe-sdk-js. 두 SDK 모두 별칭 목록을 조회하는 models.list()를 제공합니다.

https://console.typesafe.ai/playground의 플레이그라운드는 로그인해야 하는 콘솔이며 공개 임베드가 아닙니다. 텍스트를 state로 붙여 넣고 "이 메시지에서 긴급함이 드러나나요?" 같은 Noul를 추가한 뒤, 한 번의 호출에 질문을 더 섞어 보세요. 프로덕션 키를 연결하기 전에 병렬 평가를 가장 빠르게 체감할 수 있는 방법입니다.

첫 curl 요청

Authorization: Bearer $TYPESAFE_API_KEY와 Content-Type: application/json을 지정해 curl -X POST https://api.typesafe.ai/v1/systemone을 호출합니다. 본문에는 Stripe-connect 실패 메시지를 담은 state, model jev-latest, 그리고 type이 noul이고 instructions가 "이 메시지에서 긴급함이 드러나나요?"인 questions.urgency를 넣습니다. 이것이 빠른 시작 예시입니다. 두 번째 왕복 호출 없이 billing / technical / sales 기준을 둔 department라는 Choice와 순서가 있는 수준을 둔 frustration이라는 Score를 추가할 수 있습니다.

문제가 생기면 지침에 설명을 더 붙이기 전에 jaggedness을 읽으세요. 문자 그대로 판독하려면 지침과 기준에 정확한 조건을 명시해야 합니다. 계산은 코드로 해야 합니다. 생성 작업에는 다른 모델이 필요합니다. 연쇄된 Choice으로 Jev에 문단 작성을 요청해도 API는 형식화된 페이로드를 반환하지만, 느리고 결과도 좋지 않습니다. 정규식이나 생성 모델로 선택지를 만든 다음 Jev이 고르게 하세요.

Cloudflare Workers AI에는 typesafe/jev가 카탈로그 이름으로 등록되어 있습니다. 이는 서드 파티 등록 항목이지 api.typesafe.ai를 대체하지 않습니다. Steam에는 Jev 앱이 없습니다. 키는 TypeSafe의 콘솔에서 관리하고, Awesome Jev의 커뮤니티 SDK는 github.com/typesafe-ai 조직을 추적하지 않는 한 비공식으로 간주하세요.

오류, 재시도 및 ID

초당 토큰 또는 분당 요청 제한을 넘으면 문서에 명시된 429 Too Many Requests 응답이 반환됩니다. retry-after를 따르세요. 공식 SDK에는 이미 백오프가 적용되어 있습니다. HTTP를 직접 래핑한다면 429 발생 시 엔드포인트를 계속 호출하지 마세요. 같은 제한 시간대에 계속 걸리게 됩니다.

질문 ID는 추적용이며 추론에 절대 들어가지 않습니다. 루프에서 item_0부터 item_n까지 생성해도 각각 하나의 Noul을 받을 수 있습니다. 한 요청 안에서는 키를 고유하게 유지하세요. 키를 재사용하면 맵에서 기존 질문을 경고 없이 덮어씁니다.

인증에는 대시보드에서 발급한 Bearer TypeSafe API 키를 사용합니다. api.typesafe.ai에는 쿠키 세션이 없습니다. 키 교체는 이 위키에 이메일을 보내는 대신 콘솔에서 진행하세요. 플레이그라운드의 로그인 장벽은 별개입니다. 이는 브라우저 콘솔이지 대체 HTTP API가 아닙니다.

빠른 시작 curl을 한 번 복사해 실행한 뒤 저장소에서는 삭제하고 SDK로 전환하세요. SDK가 재시도와 형식별 생성자를 처리합니다. 원시 HTTP는 공식 클라이언트가 없는 언어용입니다. 어느 방식을 쓰든 Bearer 키와 동일한 JSON 본문을 POST /v1/systemone으로 전송합니다.

GET /v1/models는 계정에서 전송할 수 있는 별칭을 나열합니다. POST /v1/systemone에서 jev-1.13.0 ID가 작동하더라도 목록에는 없을 수 있습니다. 이 목록을 버전 지정 ID의 허용 목록으로 간주하지 마세요. 별칭 카탈로그로만 사용하고 버전 지정 ID는 자체 설정에 보관하세요.

TYPESAFE_API_KEY를 절대 커밋하지 마세요. 유출되면 대시보드에서 교체하세요. 유출된 비밀 키를 contact@jevai.wiki로 보내면 안 됩니다. TypeSafe의 공식 문의 채널을 이용하세요.

문서에 명시된 최소 버전은 Python 3.10과 Node.js 20입니다. 이전 런타임은 공식 클라이언트 지원 범위 밖입니다.