HopBase 文檔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-你的金鑰不支援 x-goog-api-key 與 URL 參數 ?key=。GET /v1/usage 只認 Authorization: Bearer。
每把金鑰綁定一個分組（例如「Codex Pro」「Claude Max (官號滿血版)」「GPT Image 全系」），只能呼叫該分組提供的模型和該分組協定的端點：Claude 金鑰呼叫 /v1/chat/completions 回傳 404「當前平臺不支持該 API 路徑」，對話分組的金鑰呼叫圖片模型回傳 404 model_not_found。同一個專案既要對話又要生圖時，請建兩把金鑰分別放進不同的環境變數。可用模型以這把金鑰呼叫 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，數字取自網關校驗程式碼。- 請求建構器：在瀏覽器裡依模型組出合法的生圖請求並產生程式碼。