萬相 / 快樂馬：影片生成 API

萬相 3.0 與快樂馬 1.1 按官方原始路徑提交非同步影片任務,輪詢 HopBase 任務 ID 取得成片。

HopBase 按官方介面格式提供萬相與快樂馬影片生成,並保持原始路徑。用官方 SDK 或 HTTP 寫好的程式碼遷移過來只需改 base URL 和密鑰——請求體、回應結構、路徑都不用動。

可用型號

萬相 3.0 的時長也可以傳 -1 表示自動。它的參考組最多 10 張參考圖、5 段參考影片、5 段參考音訊、1 個文件、1 個網頁連結。

請使用上表中的精確 ID。未登記任何別名,未知模型名會被拒絕。wan3.0-video-prime、happyhorse-1.1-video-edit 以及快樂馬 1.0 系列均未上架。

wan3.0-video 與 happyhorse-1.1-* 分屬兩個分組——萬相 3.0 官方直連與快樂馬 1.1 官方直連,密鑰須包含模型所在的分組才能調用;一把密鑰可以同時包含兩個分組。請在發起付費任務前用 GET /v1/models 確認密鑰能呼叫哪些模型。

分檔價與完整規格見模型卡:wan3.0-video、happyhorse-1.1-t2v、happyhorse-1.1-i2v、happyhorse-1.1-r2v。

請求參數

所有請求使用 Authorization: Bearer sk-your-key 與 Content-Type: application/json。你不需要額外送出非同步請求標頭,任務始終非同步執行。

{
  "model": "wan3.0-video",
  "input": { "prompt": "...", "media": [{ "type": "first_frame", "url": "..." }] },
  "parameters": { "resolution": "1080P", "duration": 5 }
}

快樂馬的中文 prompt 在 2,501-5,000 字之間不報錯,但會被截斷到約 2,500 字。

input.media

file 接受的格式:docx / doc / xlsx / xls / pptx / ppt / pdf / txt / key / pages / numbers / md。

對萬相 3.0,首尾幀輸入與參考組(reference_*、file、link)在同一次請求中互斥。

url 接受絕對的公網 http(s) 位址或 data: 內嵌(base64)。oss:// 會被拒絕——該物件歸屬你自己的雲端帳號,閘道無法代取。

類型、數量與組合在提交時校驗;檔案大小、尺寸、編碼、時長與頁數由服務在執行時校驗。整個 JSON 請求體上限 128 MiB(含 base64 體積),大素材請用 URL。

parameters

模型不支援的參數回傳 400,不會被忽略。閘道總會送出 resolution 與 duration(預設值見上表);其他沒傳的欄位不會送出,由服務預設值生效。

圖生影片範例:

{
  "model": "happyhorse-1.1-i2v",
  "input": {
    "prompt": "鏡頭緩緩推進,光影在場景中流動",
    "media": [{ "type": "first_frame", "url": "data:image/jpeg;base64,..." }]
  },
  "parameters": { "resolution": "720P", "duration": 5, "watermark": false }
}

回傳結果

提交回應

提交成功回傳 200,HopBase 任務 ID 在官方回應結構的 output.task_id(形如 blt…):

{
  "output": {
    "task_id": "blt60x4115010d-d361-4bfc-b131-a382f1c400a5",
    "task_status": "PENDING"
  },
  "request_id": "..."
}

任務查詢欄位

輪詢 GET /api/v1/tasks/{task_id}。

output.task_status(大寫)依序經過 PENDING → RUNNING → SUCCEEDED | FAILED,只有後兩者是終態,其他任何值都按進行中處理。一條片子通常 1-5 分鐘完成,萬相 3.0 的長片更久。建議約 15 秒輪詢一次。

進行中

{
  "output": {
    "task_id": "blt60x4115010d-d361-4bfc-b131-a382f1c400a5",
    "task_status": "RUNNING"
  },
  "model": "wan3.0-video"
}

成功

成功時回應在 output.video_url 攜帶成片位址:

{
  "output": {
    "task_id": "blt60x4115010d-d361-4bfc-b131-a382f1c400a5",
    "task_status": "SUCCEEDED",
    "video_url": "https://api.hop-base.com/...",
    "orig_prompt": "..."
  },
  "usage": { "video_count": 1, "duration": 5, "SR": 1080, "output_video_duration": 5, "input_video_duration": 0, "ratio": "16:9", "billed_seconds": 5, "billing_bucket": "1080p", "cost": 4.08, "cost_usd": 0.6, "currency": "CNY" }
}

失敗

失敗任務不計費。code 恆為 TaskFailed,只能看 output.message 區分原因(非同步任務失敗):

{ "output": { "task_id": "blt60x...", "task_status": "FAILED", "code": "TaskFailed", "message": "..." } }

最小範例

BASE=https://api.hop-base.com
# 1. 提交
curl "$BASE/api/v1/services/aigc/video-generation/video-synthesis" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "input": {
      "prompt": "日出時分空拍雲海之上的雪山"
    },
    "parameters": {
      "resolution": "1080P",
      "duration": 5,
      "ratio": "16:9"
    }
  }'

# 2. 用回傳的 output.task_id 輪詢,約 15 秒一次
curl "$BASE/api/v1/tasks/blt你的任務ID" \
  -H "Authorization: Bearer sk-your-key"

注意事項

• 未知欄位與第二個 JSON 值會在請求送出前就被拒絕。這是刻意的。
• 參考素材由官方側下載,而不是 HopBase 下載。屏蔽機房 IP 的圖床(很多免費圖床都會)會讓任務在提交幾分鐘後失敗,建議用 data: 內嵌或你自己的物件儲存 / CDN。
• 輪詢 GET /api/v1/tasks/{task_id}。注意這個路徑前面不帶 /v1,和其他頁面的影片查詢介面不同。沒有列表介面,任務 ID 需要自行留存。
• 建立超過 2 小時仍未結束的任務會被自動判為失敗,這兩個系列的任務都不支援取消。
• output.video_url 是 api.hop-base.com 網域下的簽名位址,自任務完成起 24 小時有效。
• 再次查詢返回同一位址、不會延長,過期存取回傳 410,請在有效期內下載保存。
• usage.ratio 回報的是成片實際比例,可能是原始尺寸(如 1632:937)而不是請求裡的列舉值。

常見報錯 → 改法

請求錯誤回傳 {"code":…,"message":…}。

413 與 404 的 message 原文:

request body exceeds the 128 MiB limit (received N bytes)
invalid task ID format
task not found            # 用其他使用者的密鑰查詢也是這條

其他欄位(OpenAI 的 size / n / image、萬相 2.x 的 img_url / negative_prompt / shot_type、media 元素裡的多餘鍵)一律回傳 400:

400 {"code":"InvalidParameter","message":"request body does not match the JSON contract: json: unknown field \"size\""}

任務失敗時按 output.message 處理:

計費

提交任務時按「可用餘額 − 進行中任務的預估費用 − 本次預估費用」判斷,不足回傳 402,code 為 insufficient_balance,任務結束後預估自動釋放。影片任務通用規則詳見影片總覽。失敗任務不計費。

兩個系列都按影片秒數計費,單價隨解析度檔位不同,不按 token 計量:

本次扣費 = usage.billed_seconds × usage.billing_bucket 檔的單價

檔位由 usage.SR(成片的解析度檔位,480 / 720 / 1080)決定;同一檔位下兩個系列單價不同。

兩者的計費時長口徑不同:

• 萬相 3.0 官方寫明輸入影片與輸出影片都計費,計費時長 = 輸入影片時長 + 輸出影片時長,所以 usage.input_video_duration 也計入計費秒數——無影片輸入時它是 0.0。
• 快樂馬 1.1 三個模型只計輸出,其中參考生影片的 input_video_duration 官方文件寫明固定為 0。

任務結束後,查詢回應根物件的 usage 還會帶 cost_usd（本任務從餘額實際扣除的美元金額，未扣費的失敗為 0）、cost（同一筆的人民幣金額）與 currency（恆為 CNY）。

官方牌價見價格頁。你的實際單價以登入後的模型廣場為準,每次請求的實際扣費見用量記錄。

下一步

• 影片總覽——所有影片模型共用的餘額預占、逾時與結果位址規則
• MiniMax 海螺 H3 影片 API
• 錯誤碼與重試——含非同步任務失敗
• 並行、逾時與計費