# 模型端點

已註冊模型、路由、tier、額度與音訊模型的端點。

| Method | 路徑 | 說明 |
|---|---|---|
| `GET` | `/v1/models` | 列出已註冊模型（OpenAI `{data:[...]}` 格式，含 `auto`） |
| `GET` | `/v1/models/*id` | 讀取單一已註冊模型 |
| `POST` `DELETE` | `/v1/models` · `/v1/models/*name` | **local** — 新增 / 移除模型 |
| `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` | `/v1/model/quota` | **local** — v1.1.0 新增。`?model=<prefix>@<model>` 回傳 `{quota}`：該模型所屬 provider 的額度顯示字串（`codex`、`grok-oauth`、`copilot`、`ollama-cloud`、`claude-code` 為 `"42%"`；`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 |