# Provider 端點

供應商目錄、登入、憑證、額度與模型清單的端點。

| Method | 路徑 | 說明 |
|---|---|---|
| `GET` | `/v1/providers` | **local** — 列出 provider 與其可用的認證方式。每筆另帶 `logged_in`，僅在 OAuth provider（`codex`、`copilot`、`grok-oauth`）目前持有 token、或 `claude-code` 已啟用時為 true；`hidden`（v1.1.0）對 `claude-code` 為 true，除非 daemon 以 `agen --enable-claude-code` 啟動（需先停止 daemon，`agen stop`）；v1.0.22 起另帶 `console`，為 `/v1/provider/:provider/console` 對該 provider 可用的頁面名稱（API key 類為 `key` / `billing`，訂閱制為 `plan`，`compat` 為空），已排序 |
| `GET` | `/v1/providers/quota` | **local** — `codex`、`grok-oauth`、`copilot`、`claude-code`（v1.1.0 起）、`openrouter` 與 `deepseek` 的剩餘額度，以 provider 為 key 放在 `quota` 下回傳。`ollama-cloud` 已不再追蹤額度，請至 ollama.com 查看用量（移除於 v1.2.0）。v1.1.3 起每筆帶 `remaining`，只含該 provider 有回報的欄位：`five_hour`、`week`、`total`（各視窗剩餘百分比）或 `balance`（美元餘額）；v1.1.3 之前為單一 `kind`（`percent`／`balance`）加 `value`。並行查詢、10 秒上限。v0.35.3 起由 `/v1/providers/usage` 更名而來。成功的讀取在 ToriiDB 快取 3 分鐘並標記 `cached:true`；`?refresh=1` 丟棄快取重讀，儲存 key 或完成 OAuth 登入也會自動清掉該 provider 的快取。沒有憑證的 provider 回 `error` 而非 `remaining`，且不快取 |
| `POST` | `/v1/provider/:provider/key` | **local** — `{api_key, account_id?, gateway_id?}`。把 `<PROVIDER>_API_KEY` 存入 keychain；`cloudflare` 必須帶 `account_id`，沒有 API key 認證方式的 provider 回 400。`compat` 改收 `{name, url, api_key?}`，新增或更新一個自訂相容實例（key 存為 `COMPAT_<NAME>_API_KEY`） |
| `GET` | `/v1/provider/:provider/oauth` | **local** — SSE 登入流程。只有 `copilot` 是 device-code 流程（`{url, user_code}`）；`codex` 與 `grok-oauth` 送出 `{url}` 供瀏覽器登入；`claude-code` 只檢查 `claude` CLI 是否已安裝。串流以 `{done, ok, error?}` 結束；不支援 OAuth 的 provider 回 400。登入期間保留既有 token，因此中途放棄或失敗的重新登入不會把該 provider 登出 |
| `DELETE` | `/v1/provider/:provider/oauth` | **local** — 清除已儲存的 provider 登入（`codex`、`copilot`、`grok-oauth`）。token key 屬於 OAuth 函式庫，因此走它們自己的 `ClearToken` 而非 `DELETE /v1/key` |
| `GET` | `/v1/provider/:provider/models` | **local** — `{models, windows}`：以已存憑證向該 provider 自身 API 取得的文字模型清單；自訂相容實例則探查其 `/models` 端點。provider 不支援列出模型時回 400，取得失敗回 502。自 v1.0.15 起另回傳 `windows`，為 `{model: {in, out}}` 的 context window 大小對照；window 表沒有該模型時就不會出現在這個 map 裡。自 v1.0.18 起，各 provider 的清單在 ToriiDB 快取 15 分鐘，並於該 provider 設定金鑰、完成 OAuth 或清除登入時立即失效 |
| `GET` | `/v1/provider/:provider/console` | **local** — v1.0.22 新增。以 `302` 轉址到該供應商的 console 頁面；`?page=` 為 `key`、`billing` 或 `plan`，訂閱制供應商預設 `plan`，其餘預設 `key`。供應商沒有該頁面時回 404。TUI（`/model add` 中按 `o`）與儀表板的 Console / Plans 連結都經由此端點，網址只維護在一張表（`handler/providers.go` 的 `providerConsole`） |