API 參考
HopBase API 的 Base URL、依分組的密鑰驗證、請求 ID、錯誤結構與並行限制,以及全部端點一覽。
HopBase 是多模型 API 網關:對話、圖片、影片、語音都透過同一個網域 https://api.hop-base.com 呼叫,協定沿用 OpenAI 與 Anthropic 的官方格式,現有 SDK 只需換 Base URL 和密鑰。本節每個端點一頁,參數表與範例都從 OpenAPI 描述產生。
端點一覽
/v1/video/generate提交影片任務GET/v1/video/tasks/{task_id}查詢影片任務GET/v1/video/tasks列出影片任務POST/v1/kling/subjects建立自訂主體GET/v1/kling/subjects查詢自訂主體POST/v1/kling/faces對口型人臉辨識Base URL
| 協定 | Base URL | 用於 |
|---|---|---|
| OpenAI 相容 | https://api.hop-base.com/v1 | 對話、Responses、圖片、影片、語音、/v1/models、/v1/usage |
| Anthropic | https://api.hop-base.com | Claude 模型的 /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,數字取自網關校驗程式碼。- 請求建構器:在瀏覽器裡依模型組出合法的生圖請求並產生程式碼。