跳到正文

API 參考

HopBase API 的 Base URL、依分組的密鑰驗證、請求 ID、錯誤結構與並行限制,以及全部端點一覽。

HopBase 是多模型 API 網關:對話、圖片、影片、語音都透過同一個網域 https://api.hop-base.com 呼叫,協定沿用 OpenAI 與 Anthropic 的官方格式,現有 SDK 只需換 Base URL 和密鑰。本節每個端點一頁,參數表與範例都從 OpenAPI 描述產生。

端點一覽

Base URL

協定Base URL用於
OpenAI 相容https://api.hop-base.com/v1對話、Responses、圖片、影片、語音、/v1/models、/v1/usage
Anthropichttps://api.hop-base.comClaude 模型的 /v1/messages(SDK 裡不帶 /v1)

協定由用戶端和模型類型共同決定,不由密鑰格式決定。完整的情境對照(Claude Code、Codex CLI、各模型種類)見 Base URL 與協定。萬相 / 快樂馬使用原生影片路徑 /api/v1/services/aigc/video-generation/video-synthesis,掛在網域根下。

驗證

所有端點用主控台「API 密鑰」裡建立的 sk- 密鑰驗證,兩種請求標頭任選其一:

Authorization: Bearer sk-你的密鑰
x-api-key: sk-你的密鑰

Gemini 原生協議(/v1beta/models/{model}:generateContent)另接受 x-goog-api-key: sk-你的密鑰 與 URL 參數 ?key=。GET /v1/usage 只認 Authorization: Bearer。

密鑰能呼叫它所含分組的模型:

建立或編輯密鑰時可以選一個或多個分組(例如「Codex Pro」「Claude Max 企業版」「GPT Image 全系」),可以跨平台。密鑰只能呼叫這些分組提供的模型,而且每個請求都要走該模型支援的端點:Claude 模型可用 /v1/messages 與 /v1/chat/completions,但不支援 /v1/responses,所以只含 Claude 分組的密鑰呼叫 /v1/responses 回傳 404「目前平台不支援此 API 路徑」;模型不在密鑰任何一個分組裡則回傳 404 model_not_found。同一個專案既要對話又要生圖時,把兩個分組加進同一把密鑰(或編輯已有密鑰追加分組)即可。模型有重疊的分組不能放進同一把密鑰,訂閱類分組只能單獨成一把密鑰。每次請求只由涵蓋所請求模型的那一個分組服務並按它計費,不會悄悄換到別的分組。唯一例外是「GPT 官方直連(Azure)」與 Codex Plus 或 Codex Pro 其中之一、或與「GPT Image 全系」混用:兩組都有的型號優先走 Azure,Azure 在還沒輸出任何內容前失敗時自動切到另一個分組,按實際服務的分組計費並在使用記錄中顯示(見分組怎麼選)。可用模型以這把密鑰呼叫 GET /v1/models 的回傳為準,即所有已綁分組模型的聯集。

請透過環境變數或部署平台注入密鑰,不要寫進原始碼或提交到 Git。

請求 ID

每個回應都帶回應標頭 x-request-id,它是定位這一筆請求的唯一識別碼。回報問題時請附上 x-request-id、發生時間(含時區)、模型 ID 與完整的錯誤原文——伺服器端故障在主控台不顯示原文,排查以 x-request-id 為準。

curl -i https://api.hop-base.com/v1/models \
  -H "Authorization: Bearer $HOPBASE_API_KEY"
# HTTP/2 200
# x-request-id: …

部分模型回應會帶有自身的限流標頭(x-ratelimit-*、anthropic-ratelimit-*),它們描述的不是你帳戶或密鑰的上限,不要據此限流。

錯誤

OpenAI 協定的端點回傳 {"error": {"message", "type", "code"}};/v1/messages 回傳 Anthropic 結構 {"type": "error", "error": {"type", "message"}},沒有 code。文案語言依 Accept-Language 回傳,未指定時為英文——程式裡請依 HTTP 狀態碼和 code 判斷,不要比對文案。

狀態碼含義能否重試
400 / 413參數不合規 / 請求體超過 60 MB否,先改請求
401沒帶密鑰、密鑰無效或已過期否
402餘額或額度用完;影片提交時餘額不足以涵蓋在途預留儲值後
403帳戶或成員被停用、無權使用該分組否
404這把密鑰的所有分組都不提供該模型或路徑否
429帳戶或密鑰並行已達上限,或服務繁忙依 Retry-After 重試
502 / 503 / 504服務暫時無法使用或逾時退避後重試

串流請求一旦開始輸出,HTTP 狀態已是 200,之後的錯誤以事件傳送,見串流事件。完整錯誤碼清單與重試規則見錯誤碼與重試。

並行與限流

HopBase 依同時在途的請求數限流,而不是依每分鐘請求數:帳戶預設同時在途 5 個請求;持續觸頂時會依餘額自動暫時調高,長期調高可申請;單把密鑰可在主控台另設上限,兩者取小。超限的請求立即回傳 429(user_concurrency_limit / apikey_concurrency_limit,帶 Retry-After: 1 與 Retry-After-Ms),不會在伺服器端排隊。

對話、生圖、影片提交、/v1/messages/count_tokens 佔並行;輪詢任務與 GET /v1/models 不佔。逾時口徑與用戶端讀取逾時建議見並行、逾時與計費。

計費

請求成功依模型計價單位計費(token / 張 / 秒 / 字元);失敗原則上不計費,串流中斷依已產出部分計費;非同步任務失敗不計費。查餘額用 GET /v1/usage,官方牌價見公開目錄 GET /api/v1/models/pricing(欄位說明)。

機器可讀描述

  • /openapi.json:本節全部端點的 OpenAPI 3.1 描述,可匯入 Postman、Apifox 或 SDK 產生器。
  • /spec/models/index.json:每個生圖模型一份請求體 JSON Schema,數字取自網關校驗程式碼。
  • 請求建構器:在瀏覽器裡依模型組出合法的生圖請求並產生程式碼。