Skip to main content
本文將介紹 Grok Videos Generation API 的對接說明,它可以通過輸入文本提示詞、輸入圖片以及可選的參考圖片來生成 Grok Imagine(xAI)視頻。

申請流程

要使用 Grok Videos Generation API,首先到 Ace Data Cloud 控制台 獲取您的 API Token,留作備用。 如果你尚未登錄或註冊,會自動跳轉到登錄頁面邀請你註冊和登錄,完成後會自動返回當前頁面。 一個 API Token 即可調用平台所有服務,無需為每個服務單獨申請。 首次申請會贈送免費額度,可免費體驗;額度不足時可在 控制台 充值通用餘額。
📘 完整文檔:Grok Videos Generation API →

模型說明

本 API 通過模型名的後綴選擇上游端點::reverse 走快速/標準端點(更便宜),:official 走官方端點(畫質更高,按輸出秒數計費)。共支持四個模型:
  • grok-imagine-video-1.5-fast:reverse(默認):支持文生視頻(僅傳 prompt)和圖生視頻(傳 image_url),時長 6–30 秒,按時長分檔計費,最便宜。
  • grok-imagine-video:reverse:支持文生與圖生視頻,時長 1–15 秒,按輸出秒數計費。
  • grok-imagine-video:official:官方端點,支持文生與圖生視頻,時長 1–15 秒,按輸出秒數計費,畫質更高。
  • grok-imagine-video-1.5:official:官方端點,僅支持圖生視頻,必須傳入 image_url,時長 1–15 秒,支持最高 1080p,按輸出秒數計費。

基本使用

首先了解下基本的使用方式,輸入提示詞 prompt、模型 model 等參數,便可生成對應的視頻。 可以看到這裡我們設置了 Request Headers,包括:
  • accept:想要接收怎樣格式的響應結果,這裡填寫為 application/json,即 JSON 格式。
  • authorization:調用 API 的密鑰,申請之後可以直接下拉選擇。
另外設置了 Request Body,包括:
  • prompt:描述想要生成視頻內容的文本提示詞。做文生視頻時必填;傳入 image_url 時可選。
  • model:生成視頻的模型,可選 grok-imagine-video-1.5-fast:reverse(默認)、grok-imagine-video:reverse、grok-imagine-video:official 或 grok-imagine-video-1.5:official。
  • image_url:圖生視頻的輸入圖片鏈接。當 model 為 grok-imagine-video-1.5:official 時必填。
  • reference_image_urls:可選的參考圖片鏈接數組,用於引導視頻的風格或內容。
  • aspect_ratio:生成視頻的寬高比,可選 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3。
  • resolution:輸出分辨率,可選 480p(默認)、720p 或 1080p。
  • duration:生成視頻的時長(秒)。grok-imagine-video-1.5-fast:reverse 取值範圍 6–30,其餘模型取值範圍 1–15,默認 6。推薦使用 6 秒或 10 秒,這兩個標準時長相對穩定。
  • callback_url:異步回調地址,設置後 API 會立即返回 task_id,任務完成時將結果 POST 到該地址。
  • async:可選,設為 true 時接口立即返回 task_id,無需提供 callback_url,隨後通過對應的任務查詢接口輪詢獲取結果。
點擊「Try」按鈕即可進行測試,得到的結果類似如下:
返回結果一共有多個字段,介紹如下:
  • success:本次視頻生成請求是否成功。
  • task_id:本次視頻生成任務的 ID。
  • trace_id:本次請求的跟蹤 ID,用於排查問題。
  • data:生成的視頻結果列表。
    • id:生成視頻的唯一標識。
    • video_url:生成視頻的鏈接地址。
    • state:視頻生成任務的狀態,可選 pending / succeeded / failed。
我們只需要根據結果中 data 的 video_url 鏈接地址獲取生成的視頻即可。 對應的 CURL 代碼如下:
對應的 Python 代碼如下:

圖生視頻

如果想基於一張輸入圖片生成視頻,可以傳入 image_url。使用 grok-imagine-video-1.5:official 時必須提供該字段:

參考圖引導

如果想用一張或多張參考圖引導生成視頻的風格或內容,可以在 reference_image_urls 中傳入圖片鏈接數組:

異步回調

視頻生成需要一定的處理時間。如果不希望保持長連接等待,可以傳入 callback_url,此時 API 會立即返回 task_id,任務完成後會將最終結果 POST 到該地址:
立即返回的結果如下:

查詢任務結果

如果使用了異步回調或希望主動查詢任務狀態,可以通過 Grok Tasks API(POST https://api.acedata.cloud/grok/tasks)根據 task_id 查詢任務的最新狀態與結果。

計費說明

本服務的計費方式由 model 決定:
  • grok-imagine-video-1.5-fast:reverse:按時長分檔計費,與分辨率無關——6–10 秒、11–20 秒、21–30 秒分別對應不同檔位價格。
  • grok-imagine-video:reverse:按「輸出秒數」計費,總價 = 單價 × duration。
  • grok-imagine-video:official 與 grok-imagine-video-1.5:official:官方端點,按「輸出秒數」計費,分辨率越高單價越高;官方模型即使內容審核失敗也會計費。
具體單價以定價頁為準。失敗的請求不計費,也不佔用免費額度。

錯誤處理

當請求出現問題時,API 會返回對應的錯誤碼與說明,常見的如下:
  • 400:請求參數有誤,例如文生視頻缺少 prompt,或 grok-imagine-video-1.5:official 缺少 image_url,或 duration 超出範圍(grok-imagine-video-1.5-fast:reverse 為 6–30,其餘模型為 1–15)。
  • 401:鑑權失敗,token 無效或與 API 不匹配。
  • 403:餘額不足,或提示詞命中內容審核被拒絕。
  • 429:請求過於頻繁,請稍後重試。
  • 500:視頻生成失敗或服務異常。