帳戶與目錄 API

三個端點都不計費，也都不要求餘額為正。

列出模型

GET /v1/models 接受 Authorization: Bearer sk-… 或 x-api-key: sk-…；GET /v1/usage 只認 Authorization: Bearer sk-…。

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-sonnet-5-5",
      "object": "model",
      "type": "model",
      "display_name": "Claude Sonnet 5.5",
      "created_at": "2026-09-28T00:00:00Z"
    }
  ],
  "has_more": false,
  "first_id": "claude-sonnet-5-5",
  "last_id": "claude-haiku-4-5-20251001"
}

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

餘額與計價幣種：USD

自 2026-10-01 起，帳戶餘額、密鑰額度、扣費與使用記錄一律以美元（USD）計價：模型按官方美元價乘以分組倍率扣費，主控台與 GET /v1/usage 顯示的都是美元金額。

• 既有餘額：切換時已按固定比例換算為美元，可用量不變；分組價格與密鑰都不變。
• 單次扣費：為相容已接入的程式，回應裡的 cost 與 X-HopBase-Cost 仍是同一筆扣費的人民幣金額（最多 6 位小數），currency 恆為 CNY；實際從餘額扣除的美元金額讀 cost_usd 與 X-HopBase-Cost-USD，與「使用記錄」一致。見扣費。
• 增值：付款幣別、手續費與到帳金額以「增值」頁付款前顯示的為準，手續費單獨列出、不計入到帳金額；人民幣對公轉帳或線下增值的到帳美元金額以客服確認為準。

餘額與額度

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

下例是一把額度為 $10、已用 $2 的密鑰：

{
  "is_active": true,
  "balance": 8,
  "remaining": 8,
  "unit": "USD",
  "ledger_currency": "USD",
  "balance_cny": 54.4,
  "balance_usd": 8,
  "quota": {
    "remaining": 8,
    "api_key_remaining": 8,
    "total": 10,
    "used": 2,
    "unlimited": false,
    "remaining_cny": 54.4,
    "remaining_usd": 8,
    "api_key_remaining_cny": 54.4,
    "api_key_remaining_usd": 8,
    "total_cny": 68,
    "total_usd": 10,
    "used_cny": 13.6,
    "used_usd": 2
  }
}

balance 的取值規則：

• 密鑰沒設額度：即帳戶餘額。
• 密鑰設了額度：即密鑰剩餘額度。
• 團隊成員與部門的密鑰還會再按成員、部門本期剩餘額度封頂。

不帶後綴的金額指 balance、remaining、quota.remaining、quota.api_key_remaining、quota.total、quota.used。

每個金額都另有人民幣與美元兩個帶後綴的欄位：

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

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

第一種 401 的完整回應內容：

{"is_active": false, "balance": 0, "message": "missing or invalid api key"}

這兩種 200 回應同樣帶 ledger_currency 和 balance_cny / balance_usd（皆為 0）。

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

單次請求、單個任務與單筆記錄的扣費

同步請求與非同步任務的每筆扣費都給出兩種幣別：cost_usd 是實際從餘額扣除的美元金額，與主控台「使用記錄」裡這一筆相同；cost 是同一筆扣費的人民幣金額，為相容已接入的程式恆為人民幣，因此 currency 恆為 CNY。cost_usd 最多 8 位小數，cost 取 6 位。

同步請求（對話、生圖、語音）

計費的同步請求在三個回應標頭裡回傳本次實際扣費：

非串流的 JSON 回應還會在根物件的 usage 裡帶同樣的 cost、cost_usd 與 currency：

{
  "id": "chatcmpl-abc",
  "object": "chat.completion",
  "model": "gpt-5.6-sol",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "ok" }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 9, "completion_tokens": 1, "total_tokens": 10, "cost": 0.001197, "cost_usd": 0.000176, "currency": "CNY" }
}

• 回應原本沒有 usage 時會新增一個，例如語音合成 POST /v1/t2a_v2 的 JSON 回應。usage 裡原有的欄位（如 xAI 的 cost_in_usd_ticks）保持不變。
• usage 已經帶有 cost、cost_usd 或 currency、或者不是物件時，回應主體保持原樣，請讀回應標頭。
• 二進位回應（如語音合成回傳的音訊）只有回應標頭。
• 串流（SSE）回應都不帶：回應標頭在生成開始前已經送出，最後的用量事件原樣下發。串流請求的扣費請在主控台「使用記錄」查看。
• 生圖耗時超過約 40 秒時，伺服器會先送出 200 回應標頭再寫保活空白，此時回應標頭裡沒有扣費，請讀回應主體的 usage.cost / usage.cost_usd。
• 沒有扣費的回應（如模型列表、未計費的錯誤）都不帶。失敗的請求仍產生扣費時，錯誤回應帶回應標頭，錯誤主體保持原樣。
• HopBase 自動重試時只對最終完成的那一次計費，回傳的就是這一次的金額。多分組密鑰按實際服務的分組計價。
• 設定了銷售倍率的密鑰，回傳的是從你餘額實際扣除的金額，不含加價。
• 用戶端在回應到達前中斷連線時，本次仍按實際用量計費，可在「使用記錄」查看。

非同步任務查詢（圖片與影片）

任務結束後，根物件的 usage 帶 cost_usd（本任務實際從餘額扣除的美元金額）、cost（同一筆扣費的人民幣金額）與 currency（cost 的幣別，恆為 CNY）。0 表示失敗且未扣費；單查任務時只有建立任務的密鑰能看到這些欄位。

{
  "id": "vt-1",
  "status": "completed",
  "usage": { "cost": 3.4, "cost_usd": 0.5, "currency": "CNY" }
}

任務列表（如不帶任務 ID 的 GET /v1/video/tasks）裡，每個終態任務的 usage 也帶同樣的 cost、cost_usd 與 currency。列表按帳戶列出，同一帳戶其他密鑰建立的任務同樣帶金額。

主控台使用記錄

「使用記錄」頁面讀取 GET /api/v1/user/usage 與 GET /api/v1/user/usage/stats（主控台登入驗證，不接受 sk- 密鑰）。

每筆記錄帶 ledger_currency（2026-10-01 起為 USD）、cost_cny、cost_usd，即這筆記錄扣費的人民幣與美元金額；頁面按美元顯示。

統計結果帶 ledger_currency、total_charged_cny、total_charged_usd，by_model、by_key、by_group、by_department、by_member 的每一項帶 cost_cny / cost_usd。

統計裡原有的 total_cost 是乘分組倍率之前的官方美元原價，不是你的扣費；扣費請看 total_charged_*。

公開模型目錄

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"
        }
      ]
    }
  ]
}

platform 例如 openai、claude、gemini、kling；模型廠商看 vendor。

輸入 Token 超過 threshold 時，整筆請求按 input_multiplier / cached_multiplier / output_multiplier 計費。

video_tokens 按解析度、有無聲音、有無參考素材分檔。price_unit 為 token 時是每百萬影片 Token，為 second 時是每秒。鍵名是歷史沿用。

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

回應標頭

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

下一步

• 並行、逾時與計費：並行上限、逾時與計費規則
• 錯誤碼與重試：各錯誤碼的含義以及是否該重試
• 可用模型：查看密鑰可用的模型 ID