POST /v1/systemone
判定端點的完整參考:model/state/questions 欄位、三種題型(noul、choice、score)、處理語義、回應結構與上游錯誤透傳。
請求欄位
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
| model | string | 是 | 模型名,取 GET /v1/models 回傳值,如 typesafe/jev-latest。存量裸名(jev-latest、jev-1.13.0)經別名歸一化仍可調用。 |
| state | string / object / array | 是 | 被評估的內容。形態自由:一個問題、一張工單、一條商品記錄——只要能被 questions 引用。 |
| questions | object | 是 | {問題id: 問題定義} 映射,至少一項;問題 id 會在回應中原樣帶回。 |
| (其他) | 任意 | 否 | 未知欄位原樣透傳上游(保持前向相容)。 |
{
"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 可選描述。 |
| 選擇題 | choice | criteria | 選項名→描述映射(≤255 項,描述可 null);返回選中項與各選項 probabilities。 |
| 評分題 | score | criteria | 有序層級陣列(2–10 個);返回可在層級間插值的分數。 |
每種題型的 instructions 均可選,接受字串、物件或陣列。圖片可經 assets 附帶——見 圖片與多模態資產。
處理語義(按順序)
- 1. 請求體大小限制(單個媒體 50 MB;總量:multipart 60 MB / 純 JSON 70 MB)→ 413
- 2. 最小結構校驗——缺 model/state/questions → 422
- 3. 模型白名單(先做別名歸一化)——未知模型 → 404,不轉發
- 4. 按 key 限流(預設 600 RPM / 4,500,000 TPM)→ 429
- 5. 餘額預檢——零或負餘額 → 402(本次調用允許扣至負數,下次攔截)
- 6. 上游轉發與故障轉移:最多嘗試 3 組「渠道+key」(401 自動停用 key,429 冷卻,5xx/網路錯誤切換)
- 7. 僅 200 計費:輸入 token × 輸入單價 + 輸出 token × 輸出單價,按上游 usage 精確結算;失敗調用不扣費
- 8. 每次調用(無論成敗)都寫日誌,request_id 經回應標頭返回
成功回應
200 回應體為上游回應原樣透傳(含未知欄位)。usage 是計費口徑:只透出 input_tokens / output_tokens / cost(上游返回時才有)三個欄位。
{
"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 而非閘道錯誤體——且不計費。其餘失敗走 閘道統一錯誤結構。