TypeSafe 的 API
呼叫 POST /v1/systemone，或安裝官方 SDK。
針對一組以對應表整理的型別化問題評估一個 state，並取得每題一個的結構化答案。評估端點為 POST https://api.typesafe.ai/v1/systemone，使用 Bearer API 金鑰。官方用戶端包括適用於 Python 3.10+ 的 typesafe-sdk，以及適用於 Node.js 20+ 的 @typesafe-ai/sdk。登入後可在 console.typesafe.ai 使用測試介面與金鑰儀表板。問題 ID 只留在程式碼中，絕不會傳給模型。
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，遇到 429 時請依 retry-after 重試。Jev 1.13 的速率限制為每秒 250,000 個權杖及每分鐘 1,200 次請求，且可能隨時變更。SDK 預設會採退避策略重試。列出模型時，使用相同的 Bearer 權杖呼叫 GET /v1/models。
TypeSafe Python 軟體開發套件
- package
- typesafe-sdk
- install
- pip install typesafe-sdk
- python
- >=3.10
- 預設模型
- jev-latest
TypeSafe JavaScript 開發套件
- package
- @typesafe-ai/sdk
- install
- npm install @typesafe-ai/sdk
- runtime
- Node.js 20+
- repo
- https://github.com/typesafe-ai/typesafe-sdk-js
官方 SDK
Python：pip install typesafe-sdk。從 typesafe_sdk 匯入 TypeSafeClient。以 TypeSafeClient() 作為 client：client.system_one(state, questions)。套件內提供 Noul、Choice、Score 等建構函式，因此不必手寫 JSON 類型欄位。預設模型為 jev-latest。需要 Python 3.10 或更新版本。
JavaScript：npm install @typesafe-ai/sdk。從「@typesafe-ai/sdk」匯入 { TypeSafeClient }。client 會連至同一端點。執行環境需為 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。本文內容：將 state 設為 Stripe-connect 失敗訊息、model 設為 jev-latest，並將 questions.urgency 設為 type noul，instructions 為「這則訊息是否表達急迫性？」。這就是快速入門範例。不必再次往返，即可加入名為 department 的 Choice，其 criteria 為 billing / technical / sales；再加入名為 frustration 的 Score，並設定有序層級。
發生問題時，先閱讀 jaggedness，不要急著在指示中加入更多敘述。若要逐字判讀，就必須在指示與準則中明確寫出條件；數學運算應交由程式碼計算；內容生成則應改用其他模型。即使你透過串接的 Choice 要求 Jev 撰寫一段文字，API 仍會回傳具型別的酬載，但速度慢且品質不佳。請用 regex 或生成式模型提出選項，再交給 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 不使用 Cookie 工作階段。請在主控台輪替金鑰，不要寄信給本 Wiki。測試介面的登入牆是另一回事：它是瀏覽器主控台，不是替代的 HTTP API。
複製一次快速入門 curl 後，就從程式庫刪除並改用 SDK。SDK 會處理重試和具型別建構函式。原始 HTTP 僅供沒有官方用戶端的語言使用。無論哪種方式，都會將 Bearer 金鑰及相同 JSON 本文傳送至 POST /v1/systemone。
GET /v1/models 會列出帳號可送出的別名。即使 jev-1.13.0 可用於 POST /v1/systemone，清單中也可能沒有它。不要把這份清單當作版本化 ID 的允許清單；應將其視為別名目錄，並在自己的設定中保留版本化 ID。
絕對不要提交 TYPESAFE_API_KEY。若金鑰外洩，請在儀表板中輪替。contact@jevai.wiki 不是處理密鑰外洩的信箱，請使用 TypeSafe 自有的聯絡管道。
文件規定的最低版本為 Python 3.10 與 Node.js 20。官方用戶端不支援更舊的執行環境。
來源