跳轉到主要內容
本文將介紹 Grok Videos Generation API 的對接說明,它可以通過輸入文本提示詞、輸入圖片以及可選的參考圖片來生成 Grok Imagine(xAI)視頻。

申請流程

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

模型說明

可透過 model 選擇以下四個公開型號,具體功能與計費方式如下:
  • 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:視頻生成失敗或服務異常。