Skip to content
EASYJEV

POST /v1/systemone

判定端點的完整參考:model/state/questions 欄位、三種題型(noul、choice、score)、處理語義、回應結構與上游錯誤透傳。

請求欄位

欄位型別必填說明
modelstring是模型名,取 GET /v1/models 回傳值,如 typesafe/jev-latest。存量裸名(jev-latest、jev-1.13.0)經別名歸一化仍可調用。
statestring / object / array是被評估的內容。形態自由:一個問題、一張工單、一條商品記錄——只要能被 questions 引用。
questionsobject是{問題id: 問題定義} 映射,至少一項;問題 id 會在回應中原樣帶回。
(其他)任意否未知欄位原樣透傳上游(保持前向相容)。
JSON · request body
{
  "model": "typesafe/jev-latest",
  "state": "User asks: can I get a refund for order #1024?",
  "questions": {
    "refund": {"type": "noul", "instructions": "Is this a refund request?"},
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this?",
      "criteria": ["low", "normal", "high"]
    }
  }
}

題型定義

題型type必填欄位回傳
是非題noul—「是」的概率,區間 [0,1];criteria.true/false 可選描述。
選擇題choicecriteria選項名→描述映射(≤255 項,描述可 null);返回選中項與各選項 probabilities。
評分題scorecriteria有序層級陣列(2–10 個);返回可在層級間插值的分數。

每種題型的 instructions 均可選,接受字串、物件或陣列。圖片可經 assets 附帶——見 圖片與多模態資產。

處理語義(按順序)

  1. 1. 請求體大小限制(單個媒體 50 MB;總量:multipart 60 MB / 純 JSON 70 MB)→ 413
  2. 2. 最小結構校驗——缺 model/state/questions → 422
  3. 3. 模型白名單(先做別名歸一化)——未知模型 → 404,不轉發
  4. 4. 按 key 限流(預設 600 RPM / 4,500,000 TPM)→ 429
  5. 5. 餘額預檢——零或負餘額 → 402(本次調用允許扣至負數,下次攔截)
  6. 6. 上游轉發與故障轉移:最多嘗試 3 組「渠道+key」(401 自動停用 key,429 冷卻,5xx/網路錯誤切換)
  7. 7. 僅 200 計費:輸入 token × 輸入單價 + 輸出 token × 輸出單價,按上游 usage 精確結算;失敗調用不扣費
  8. 8. 每次調用(無論成敗)都寫日誌,request_id 經回應標頭返回

成功回應

200 回應體為上游回應原樣透傳(含未知欄位)。usage 是計費口徑:只透出 input_tokens / output_tokens / cost(上游返回時才有)三個欄位。

JSON · 200 OK
{
  "model": "typesafe/jev-latest",
  "answers": {
    "refund": {
      "type": "noul",
      "noul": 0.97,
      "confidence": 0.93
    },
    "urgency": {
      "type": "score",
      "score": 1.4,
      "confidence": 0.88
    }
  },
  "usage": {"input_tokens": 1234, "output_tokens": 0}
}

回應標頭

每個回應(成功或失敗)都帶同值的 X-Request-Id 與 x-typesafe-request-id——用於對帳與聯絡支援;官方 SDK 也以 resp.request_id 暴露它。

上游錯誤透傳

上游校驗失敗(400 / 404 / 413 / 422)原樣透傳——回應體是上游的錯誤 JSON 而非閘道錯誤體——且不計費。其餘失敗走 閘道統一錯誤結構。