跳到正文
HopBase 文檔
登入控制台

Grok Imagine 影片 API

用 Grok Imagine 生成影片：型號、參數、任務輪詢、回應結果與報錯。

grok-imagine-video-1.5 從文字生成影片，可加參考圖：提交任務後輪詢任務 ID，完成後下載成片。

項目值
Base URLhttps://api.hop-base.com/v1
提交任務POST /v1/video/generate
查詢任務GET /v1/video/tasks/{task_id}
密鑰分組「Grok 視頻」

Grok Imagine 生圖走同步的 OpenAI Images 介面，參數與影片不通用，見 Grok Imagine 生圖。

可用型號

模型 ID解析度時長（秒）官方價
grok-imagine-video-1.5480p / 720p / 1080p1–15$0.08起/ 秒

grok-imagine-video-1.5 是文生影片加可選參考圖：沒有首尾幀，不接受參考影片與參考音訊。

生圖與對話由Grok 全系分組提供，影片由Grok 視頻分組提供，這是兩個分組：密鑰須包含 Grok 視頻分組才能調影片模型，一把密鑰可以同時包含兩個分組。請用實際要使用的密鑰調 GET /v1/models 確認。

各解析度檔與參考圖的官方價見模型卡：grok-imagine-video-1.5。影片請求的全部欄位見 API 參考提交影片任務。

請求參數

參數必填取值預設值
model必填grok-imagine-video-1.5—
prompt / content二選一文字—
resolution必填480p / 720p / 1080p—
duration選填整數 1–15（秒）5
aspect_ratio選填1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:316:9
reference_images選填{ "url": "https://..." } 陣列—
  • model 精確匹配。
  • content 是只含 text 元素的陣列，文字不能為空，不接受圖片、影片、音訊元素。
  • resolution 按該檔位每秒計費；帶 reference_images 時僅 480p / 720p。
  • duration 與 aspect_ratio 的預設值由服務端填，按成片 duration_seconds 計費。
  • 畫幅請用 aspect_ratio，傳 ratio 會被拒絕。
  • reference_images 是頂層陣列，僅公網可直達的 HTTP(S)，不接受 Data URL / asset://；每張參考圖另計一筆。

ratio、frames、seed、camera_fixed、draft、draft_task、service_tier、generate_audio、watermark、return_last_frame 會被拒絕。其他未列欄位（如頂層 image）閘道不校驗，也不會當作參考圖。

回傳結果

影片沿用 Seedance 的 task 包裝，不要按可靈的頂層 id 讀取。

提交回應

提交成功返回 200，任務 ID 在 task.id（形如 vt…）：

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "grok-imagine-video-1.5",
    "status": "pending",
    "outputs": []
  }
}

任務查詢欄位

用 task.id 輪詢 GET /v1/video/tasks/{task_id}。

欄位說明
task.idHopBase 任務 ID，vt…
task.statuspending / processing / completed / failed
task.outputs影片位址，字串陣列
task.duration_seconds成片秒數，按它計費
task.error.message失敗原因
usage.cost / usage.cost_usd / usage.currency任務結束後的實際扣費，見影片總覽；cost_usd 為從餘額扣除的美元金額，cost 為同一筆的人民幣金額

終態只有 completed 與 failed，其他值都按進行中處理。

進行中

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "grok-imagine-video-1.5",
    "status": "processing",
    "outputs": [],
    "error": null
  }
}

成功

完成後返回 duration_seconds 與 outputs 裡的影片位址：

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "grok-imagine-video-1.5",
    "status": "completed",
    "duration_seconds": 5,
    "outputs": [
      "https://api.hop-base.com/example-signed-video.mp4"
    ],
    "error": null
  },
  "usage": { "cost": 1.02, "cost_usd": 0.15, "currency": "CNY" }
}

失敗

執行失敗時 HTTP 仍為 200，檢查 task.status 和 task.error.message：

{
  "task": {
    "id": "vtEXAMPLE",
    "model": "grok-imagine-video-1.5",
    "status": "failed",
    "outputs": [],
    "error": { "message": "<English failure reason>" }
  }
}

最小範例

# 1. 提交
curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "一隻橘貓奔跑穿過陽光下的草地，鏡頭跟隨",
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

# 2. 用返回的 task.id 輪詢
curl https://api.hop-base.com/v1/video/tasks/vt你的任務ID \
  -H "Authorization: Bearer sk-your-key"

注意事項

  • outputs 自任務完成起 24 小時有效，再次查詢不會續期，過期存取返回 410。請及時下載保存。
  • 提示詞觸發內容審核時任務會 failed，error.message 含 content-moderated。
  • 帶 reference_images 時解析度只能選 480p / 720p。
  • 參考圖只接受公網 HTTP(S) 位址，最大張數尚未驗證。
  • 影片與生圖、對話不在同一分組；要調影片，請給密鑰加上 Grok 視頻分組。

常見報錯 → 改法

提交階段的報錯為 400，只有 error.message，沒有 code。

報錯開頭改法
... requires resolution傳 resolution
... does not support resolution 4k改用列出的解析度
... duration must be an integer in 1-15傳 1–15 的整數
... does not support ratio改用 aspect_ratio
aspect_ratio must be one of ...從列出的比例中選
... does not support parameter generate_audio刪掉該欄位
... only supports text segments in content參考圖放進 reference_images
reference_images[0] must be a {"url": "..."} object每項寫成 {"url": …}
reference_images[0].url must be a publicly reachable http(s) address改用公網 HTTP(S) 位址
... reference-to-video supports up to 720p去掉參考圖，或選 480p / 720p
任務失敗，error.message 含 content-moderated改寫提示詞

報錯原文：

grok-imagine-video-1.5 requires resolution: 480p / 720p / 1080p
model grok-imagine-video-1.5 does not support resolution 4k
grok-imagine-video-1.5 duration must be an integer in 1-15, got 20
grok-imagine-video-1.5 uses aspect_ratio for the frame ratio and does not support ratio
aspect_ratio must be one of 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3, got 21:9
grok-imagine-video-1.5 does not support parameter generate_audio
grok-imagine-video-1.5 only supports text segments in content; use reference_images for reference images
reference_images[0] must be a {"url": "..."} object
reference_images[0].url must be a publicly reachable http(s) address
grok-imagine-video-1.5 reference-to-video supports up to 720p; remove the reference images or choose 480p/720p
priority must be within 0-9, got 12
execution_expires_after must be within 3600-259200 seconds
callback_url must be a valid http(s) URL
safety_identifier must be an ASCII string of 1-64 characters

計費

按成片秒數計費，單價隨 resolution 檔位不同；每張參考圖另計一筆。失敗的任務不計費。

任務結束後，查詢回應根物件的 usage 還會帶 cost_usd（本任務從餘額實際扣除的美元金額，未扣費的失敗為 0）、cost（同一筆的人民幣金額）與 currency（恆為 CNY）。提交前的餘額判斷（不足返回 402）等所有影片任務通用的規則見影片總覽。

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

下一步

  • Grok Imagine 生圖：生成與編輯圖片
  • 影片總覽：各影片系列對比與共用的任務流程
  • Grok：Grok 對話與推理模型，含長上下文加價、推理 Token 計費與服務端工具收費
  • 錯誤碼與重試：各錯誤碼的含義以及是否該重試

本頁目錄

可用型號請求參數回傳結果提交回應任務查詢欄位進行中成功失敗最小範例注意事項常見報錯 → 改法計費下一步