# 模型端點

已註冊模型、路由、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`、`dispatcher_beta`、`summary`、`image`、`stt`、`tts`，讀取時另附 `image_options`、`image_providers` 與 `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`）。`dispatcher_beta` 為 v1.0.18 新增的布林欄位，改由 TypeSafe dispatcher 路由而非 `dispatcher`；keychain 沒有 `TYPESAFE_API_KEY` 時設為 `true` 會回 400 並帶 `missing_key`。全域 `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 |