帳戶與目錄 API

GET /v1/models、GET /v1/usage 與公開的 GET /api/v1/models/pricing：驗證方式、範例回應、欄位型別與單位，以及 HopBase 設定的回應標頭。

三個唯讀端點分別告訴你的程式：這把金鑰能呼叫哪些模型、還能花多少、各模型的牌價是多少。三者都不計費，也都不要求餘額為正。

端點	驗證	回傳內容
`GET /v1/models`	金鑰：`Authorization: Bearer sk-…` 或 `x-api-key: sk-…`	這把金鑰所在分組提供的模型
`GET /v1/usage`	金鑰：只認 `Authorization: Bearer sk-…`	這把金鑰還能花多少，以及它的額度
`GET /api/v1/models/pricing`	無需驗證	附牌價的公開模型目錄

列出模型

curl https://api.hop-base.com/v1/models \
  -H "Authorization: Bearer sk-your-key"

清單只包含金鑰所綁定分組的模型，一次回傳完整清單（不分頁）。OpenAI 相容分組的金鑰拿到 OpenAI 格式的清單：

{
  "object": "list",
  "data": [
    {
      "id": "gpt-6-astra",
      "object": "model",
      "created": 1790222400,
      "owned_by": "hopbase",
      "capabilities": ["chat", "reasoning"],
      "context_window": 1050000,
      "context_length": 1050000,
      "max_input_tokens": 1050000,
      "max_output_tokens": 128000
    }
  ]
}

Claude 分組的金鑰拿到 Anthropic 格式：

{
  "object": "list",
  "data": [
    {
      "id": "claude-opus-5-5",
      "object": "model",
      "type": "model",
      "display_name": "Claude Opus 5.5",
      "created_at": "2026-09-22T00:00:00Z"
    }
  ],
  "has_more": false,
  "first_id": "claude-opus-5-5",
  "last_id": "claude-haiku-4-5-20251001"
}

欄位	型別	含義
`data[].id`	string	請求裡要傳的模型 ID，也是唯一應該依賴的欄位
`data[].capabilities`	string[]	例如 `chat`、`reasoning`、`image_generation`
`data[].image_only`	boolean	圖片模型為 `true`，其他模型不回傳
`data[].context_window`、`context_length`、`max_input_tokens`	integer，Token	同一個值的三種寫法，照顧不同用戶端；未公布時不回傳
`data[].max_output_tokens`	integer，Token	未公布時不回傳
`data[].created`	integer，Unix 秒	本次回應的時間，不是發布日期
`data[].display_name`、`created_at`	string	僅 Claude 分組；`created_at` 是模型發布日期（RFC 3339）

has_more、first_id、last_id 只為相容 SDK 保留：清單從不分頁，不要拿它們翻頁。除 id 外，部分模型可能缺少其他欄位；遇到不認識的欄位按選填處理。

餘額與額度

curl https://api.hop-base.com/v1/usage \
  -H "Authorization: Bearer sk-your-key"

{
  "is_active": true,
  "balance": 125.4,
  "remaining": 125.4,
  "unit": "USD",
  "quota": {
    "remaining": 125.4,
    "api_key_remaining": 125.4,
    "total": 0,
    "used": 3.12,
    "unlimited": true
  }
}

欄位	型別	含義
`balance`	number	這把金鑰此刻還能花的額度。金鑰沒設額度：即帳戶餘額。金鑰設了額度：即金鑰剩餘額度。團隊成員與部門的金鑰還會再按成員、部門本期剩餘額度封頂
`remaining`	number	與 `balance` 相同
`is_active`	boolean	`balance` 大於 0 時為 `true`
`unit`	string	恆為 `"USD"`，並不代表幣別，見下方說明
`quota.remaining`	number	與 `balance` 相同
`quota.api_key_remaining`	number	這把金鑰的剩餘額度；金鑰沒設額度時等於帳戶餘額
`quota.total`	number	金鑰額度；`0` 表示金鑰沒設額度
`quota.used`	number	這把金鑰累計已扣費金額
`quota.unlimited`	boolean	金鑰沒設額度時為 `true`

金額單位是你的餘額幣別

所有金額都以帳戶餘額的記帳幣別計——與主控台餘額和「使用記錄」裡顯示的數字一致。不要根據 unit 判斷幣別。

設了額度的金鑰仍然從帳戶餘額裡扣費：帳戶餘額先用完時，即使這裡的 balance 顯示還有額度，請求也會回傳 402。

這個端點不使用標準錯誤結構，出錯時回傳如下：

情況	狀態碼	回應內容
沒傳金鑰，或不是 `sk-` 開頭的金鑰	401	`{"is_active": false, "balance": 0, "message": "missing or invalid api key"}`
金鑰不存在或已停用	401	`"message": "invalid api key"`
金鑰已過期	200	`"is_active": false`，`"message": "api key expired"`
團隊成員已停用	200	`"is_active": false`，`"message": "member disabled"`

請以 is_active 判斷，不要只看 HTTP 狀態碼。逐筆扣費明細請在主控台「使用記錄」查看。

公開模型目錄

curl https://api.hop-base.com/api/v1/models/pricing

無需金鑰。回應允許任意網站跨來源讀取，最多快取 5 分鐘（Cache-Control: public, max-age=300）。價格是未乘分組倍率的美元牌價；各模型你實際支付的價格見登入後的模型廣場。

{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "platform": "openai",
      "models": [
        {
          "id": "gpt-6-astra",
          "name": "GPT-6 Astra",
          "context_window": 1050000,
          "capabilities": ["chat", "reasoning"],
          "vendor": "openai",
          "category": "chat",
          "input": 10,
          "cached_input": 1,
          "output": 50,
          "long_context": {
            "threshold": 272000,
            "input_multiplier": 2,
            "cached_multiplier": 2,
            "output_multiplier": 1.5
          },
          "price_unit": "token"
        }
      ]
    },
    {
      "platform": "minimax",
      "models": [
        {
          "id": "speech-2.8-hd",
          "name": "MiniMax Speech 2.8 HD",
          "capabilities": ["tts"],
          "vendor": "minimax",
          "series": "minimax-speech",
          "category": "audio",
          "input": 100,
          "output": 0,
          "price_unit": "character"
        }
      ]
    }
  ]
}

欄位	型別	含義
`code`	integer	成功為 `0`
`data[].platform`	string	模型接入所屬的協定族（例如 `openai`、`claude`、`gemini`、`kling`），不是模型廠商——廠商看 `vendor`
`models[].id`	string	要傳的模型 ID
`models[].name`	string	顯示名稱
`models[].vendor`	string	模型廠商，例如 `openai`、`google`；可能不回傳
`models[].series`	string	主控台裡把多個版本歸為一組所用的系列；可能不回傳
`models[].category`	string	`chat`、`image`、`video`、`audio` 或 `embedding`
`models[].capabilities`	string[]	例如 `chat`、`reasoning`、`image_generation`、`image_edit`、`video_generation`、`tts`
`models[].context_window`	integer，Token	未公布時不回傳
`models[].price_unit`	string	本條目所有價格的計量單位：`token` = 每百萬 Token，`second` = 每秒影片，`image` = 每張圖，`character` = 每百萬計費字元
`models[].input`、`cached_input`、`output`	number，美元 / `price_unit`	不適用快取時不回傳 `cached_input`；語音模型只用 `input`
`models[].long_context`	object	有長上下文檔位時回傳：輸入 Token 超過 `threshold` 時，整筆請求按 `input_multiplier` / `cached_multiplier` / `output_multiplier` 計費
`models[].image`	object	按解析度檔位的每張價格，例如 `{"1k": …, "2k": …, "4k": …}`
`models[].video_tokens`	object	按檔位（解析度、有無聲音、有無參考素材）的影片價格。單位跟隨 `price_unit`：`token` 為每百萬影片 Token，`second` 為每秒。鍵名是歷史沿用

同一模型透過多個分組提供時，可能出現在多個 platform 下。今後可能新增欄位，不認識的欄位請忽略。

回應標頭

回應標頭	何時回傳	含義
`x-request-id`	每個回應	本次請求的 ID，回報問題時請附上
`Retry-After`	並行上限觸發的 429；已知等待時間的 429 與 503	重試前需等待的秒數
`Retry-After-Ms`	並行上限觸發的 429，以及其他已知等待時間的 429	同一等待時間，單位毫秒

HopBase 不會在回應標頭裡回傳你的並行上限、在途請求數或剩餘餘額。餘額請用 GET /v1/usage 查詢，上限見並行、逾時與計費。部分模型回應會帶有自身的限流標頭（x-ratelimit-*、anthropic-ratelimit-*），它們描述的不是你帳戶或金鑰的上限，不要據此限流。

列出模型

餘額與額度

公開模型目錄

回應標頭

本頁目錄