影片總覽

影片生成是非同步任務：提交後拿到任務 ID，輪詢到完成，再在有效期內下載成片。

# 1. 提交任務，記下返回的 task.id（形如 vt…）
curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-你的密鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5-260628",
    "content": [
      {
        "type": "text",
        "text": "一隻橘貓在陽光下的草地上奔跑，鏡頭跟隨"
      }
    ]
  }'

# 2. 每 5 秒查詢一次，直到 task.status 為 completed
#    成片位址在 task.outputs
curl https://api.hop-base.com/v1/video/tasks/vt你的任務ID \
  -H "Authorization: Bearer sk-你的密鑰"

選擇系列

HopBase 在售六個影片模型系列，都走下方同一套非同步流程：提交 → 輪詢 → 下載。

官方價列是該系列最低的一檔起價，完整分檔見各系列頁與模型卡；可靈對口型等特殊模式另行計價。實際單價以登入後的模型廣場為準。

模型 ID 與分組

每個系列屬於不同的分組，請用包含該分組的密鑰調用。

可靈另有動作控制、數字人與對口型型號，見可靈頁。各系列的最小請求與結果位置如下：

MiniMax 純文生影片另需 ratio。可靈的特殊模式見可靈頁。Seedance 的 content[] 常用 text 與 image_url 元素。

任務流程：提交 → 輪詢 → 下載

所有影片模型都按這三步調用。

提交

HopBase 按請求的 model 與密鑰所含分組交給對應系列處理。請求體與狀態值各系列不同，以各自文檔為準。各系列提交成功的狀態碼不同，客戶端以 2xx 判斷提交成功。

密鑰只能調通它所含分組的系列，一把密鑰可以包含多個影片分組。請用實際要使用的密鑰調 GET /v1/models，從返回結果裡取完整模型 ID。模型 ID 精確匹配，寫錯會被直接拒絕，不會就近路由。

輪詢

用提交返回的任務 ID 查詢狀態，直到任務成功或失敗。Seedance、Grok Imagine、MiniMax 與可靈還有任務列表：

GET /v1/video/tasks?page=1&limit=20

萬相與快樂馬沒有列表介面，任務 ID 需要自行留存。

下載

成片位址是 api.hop-base.com 網域下的簽名位址，有效期自任務完成起計算：

再次查詢返回同一位址、不會續期，過期存取返回 410。請及時下載保存。

餘額與計費

提交影片任務時按「可用餘額 − 進行中任務的預估費用 − 本次預估費用」判斷。不足返回 402，code 為 insufficient_balance。任務結束後預估自動釋放。

Insufficient balance: available $X, reserved in flight $Y, this request estimated $Z
Insufficient quota: …    # 設有額度的企業成員額度不足時，message 以此開頭

可靈對口型無法預估，不做預留。

失敗的影片任務一律不計費。任務結束後，單任務查詢回應的根物件還會帶 usage：

失敗且未扣費的任務為 0。任務進行中不返回該欄位，且單查時只對建立任務的那把密鑰返回；範例中的金額僅作示意。任務列表（不帶任務 ID 的 GET /v1/video/tasks）裡每個終態任務的 usage 也帶同樣的 cost、cost_usd 與 currency，列表按帳戶列出，同一帳戶其他密鑰建立的任務同樣帶金額。

官方牌價見價格頁。你的實際單價以登入後的模型廣場為準，每次請求的實際扣費見控制台「使用記錄」。

失敗、逾時與取消

提交返回 2xx 只表示已受理。生成失敗時查詢仍返回 HTTP 200，狀態為失敗，原因是英文說明，沒有穩定的錯誤碼。

Seedance 讀 task.error.message，其他系列見各自頁面。控制台「使用記錄」會顯示失敗分類與處理建議，詳見錯誤說明。

進行中任務的逾時上限各系列不同，見各自頁面。Seedance 任務建立超過 24 小時仍未結束會被自動判為失敗，message 為：

The task did not finish within 24 hours and was terminated automatically

影片任務不支援取消。

參考素材對比

各模型接受的參考素材數量：

• Seedance 首尾幀最多 2 圖；2.0 的首尾幀不能混參考模式。
• MiniMax-H3 的首尾幀與參考模式互斥；H3-Max 不接受任何 reference_*。
• 萬相 3.0 的文件、網頁各 ≤1 且互斥，首尾幀與參考組互斥。
• 可靈的 usage 與特殊模式逐型號見可靈頁。
• Grok Imagine 的 content 只放 text。

各模型接受的編碼形式：

Seedance 2.0 上傳素材庫的 URL 僅支援 HTTP(S)。MiniMax-H3-Max 不能借 Data URL 繞過參考類型限制。快樂馬不支援影片/音訊參考。

Data URL 是 data:媒體MIME;base64,編碼內容，不能只給裸 base64。

下一步

• Seedance：Seedance 2.0 / 2.5 參數、返回結果與報錯
• 可靈：可靈影片參數與任務模式
• API 參考：提交影片任務：各系列完整請求欄位
• 並行、逾時與計費：並行上限、逾時與計費規則
• 錯誤碼與重試：各錯誤碼的含義以及是否該重試