模型端點
最後更新
已註冊模型、路由、tier、額度與音訊模型的端點。
| Method | 路徑 | 說明 |
|---|---|---|
GET | /v1/models | 列出已註冊模型（OpenAI {object:"list", data:[...]} 格式，含 auto），另以純名稱陣列 models 附上同一份清單 |
GET | /v1/models/*id | 讀取單一已註冊模型；未知 id 回 404 並帶 OpenAI 的 model_not_found 錯誤 |
POST DELETE | /v1/models · /v1/models/*name | local — POST {prefix, models} 設定單一 provider prefix 的完整模型清單（prefix 為 GET /v1/providers 中的 provider id 或自訂相容實例）：清單中尚未註冊的 ID 會加入，已註冊但不在清單中的 prefix@ 模型會移除，回傳 {ok, added, removed}；auto 為保留名稱（回 400）。DELETE /v1/models/<prefix>@<model> 移除單一模型（未知時回 404），dispatcher / summary 指向它時改成剩餘的第一個模型，並把釘選該模型的 session 重設為 auto |
GET POST | /v1/model | local — 模型路由集中在一個物件：dispatcher、summary、image、decision、stt、tts，讀取時另附 image_options、image_providers、decision_options 與 audio_providers。欄位分兩種值：dispatcher、summary、stt、tts 填模型名（prefix@model）—— 其中 stt 與 tts 取自 GET /v1/model/audio，不是 session 模型註冊表；image 自 v1.0.13 起填的是 provider@model 形式的圖像模型 —— image_options 改為對每個握有憑證的 provider（openai、grok、grok-oauth、gemini，v1.0.17 起另加 openrouter）以 image-only filter 探查模型清單，v1.0.18 起快取 15 分鐘，選的是模型而非端點。codex 為例外，仍以裸 provider 名稱呈現；舊版存下的裸 provider 名稱也仍然接受。image_providers 與 audio_providers 維持為完整 provider 清單（image_providers 為 openai、codex、grok、grok-oauth、gemini、openrouter；audio_providers 為 openai、gemini、openrouter）。decision（v1.3.1 起）以 typesafe@<model> 或 openrouter@<model> 指定 decision model，必須屬於 decision_options——向握有憑證的 TypeSafe 與 OpenRouter 即時列出的 decision 模型（快取 15 分鐘），其他值回 400。設定 decision model 後，每次需要路由的請求都會與 dispatcher 同時執行，採用先取得的有效回覆；"" 為關閉。dispatcher_beta（v1.0.18 新增）移除於 v1.3.2：GET 不再回傳，POST 會忽略。v1.0.18 的行為——直接交給 TypeSafe 路由，缺 TYPESAFE_API_KEY 時回 400 並帶 missing_key——移除於 v1.3.1。全域 auto_reasoning 開關已於 v1.1.0 移除——改把 session 的 reasoning 設為 auto，由模型選擇器依工作類型逐請求決定等級。POST 為部分更新——未帶到（或 null）的欄位不動，"" 清除，image 另接受 off 作為 "" 的別名。未註冊的模型、未知的 provider、或沒有憑證的 provider 一律拒絕且不寫入。GET 會先把 provider 已無法使用的 image 設定重設為關閉 |
GET | /v1/model/quota | local — v1.1.0 新增。?model=<prefix>@<model> 回傳 {quota}：該模型所屬 provider 的額度顯示字串（codex、grok-oauth、copilot、claude-code 為 "42%"，v1.1.3 起每個有回報的視窗各一個百分比、以 / 串接，例如 "37%/80%"；openrouter、deepseek 為 "$12.34"），provider 無額度資訊、沒有憑證或讀取失敗時為 ""。即時讀取（15 秒上限，不快取）。v1.1.0 起額度已從 completion 事件與頻道 footer 移除，改由 dashboard 在 completion 後另行查詢此端點 |
GET | /v1/model/audio | local — stt_options 與 tts_options：以目前已存憑證實際可用的 speech-to-text 與 text-to-speech 模型，向 OpenAI、Gemini 與 OpenRouter（v1.0.17 加入）查詢後以 provider@model 回傳；v1.0.18 起各 provider 的結果快取 15 分鐘，失效時機與 /v1/provider/:provider/models 相同。POST /v1/model 的 stt / tts 只接受這些值 |
GET POST | /v1/model/priority | local — 已註冊模型的 fallback 順序：被選中的模型失敗後，其餘模型由上而下嘗試。v1.1.0 起略過 pass tier 模型（v1.0.20 至 v1.0.27 仍會依其在順序中的位置嘗試）。GET 回傳 models（依序的模型名）、tiers（model_tag map，模型 → tier）與 tier_options（{tier, detail} 列，第一列為代表無 tier 的 ""）。POST {models} 把列出的模型依序移到最前，其餘接在後面；未知模型名回 400 |
POST | /v1/model/tier | local — {model, tier}。設定單一已註冊模型的 tier：S、A、B、C 或 pass（v1.1.0 起 auto routing 與 subagent 永不選用，即使請求指名也一樣，fallback 也會略過；設為 session 自身的模型時仍會執行）；"" 清除。未註冊的模型或未知 tier 回 400 |