新手入門：Grok Imagine 影片 API 教學
Grok 影片 API 讓開發者能根據文字提示生成影片，並在支援的工作流程中，使用起始圖片或其他參考資料。與同步的文字回應不同，影片生成是非同步的：首次請求會回傳一個任務 ID，你的應用程式需持續輪詢，直到結果準備就緒。
本教學說明架構並提供一個簡潔的 Python 範例。若想在撰寫程式碼前先評估視覺品質，請在 Elser AI 的 Grok Imagine 工作區 測試提示詞，再將成功的鏡頭規格移至 API。
您需要準備什麼
- 一個 xAI 開發者帳戶；
- 安全儲存的 API 金鑰；
- Python 3.10 或更新版本;
requests套件；- 已完成影片檔案的持久儲存；
- 預算與重試策略。
切勿在原始碼控制中硬編碼 API 金鑰，或將其暴露於瀏覽器端的 JavaScript 中。
API 工作流程如何運作
- 向
/v1/videos/generations發送生成請求。 - 接收一個
request_id。 - 輪詢
/v1/videos/{request_id}。 - 當狀態為
done或發生終止性失敗時停止。 - 請及時下載回傳的影片，因為生成的 URL 是暫時性的。
- 儲存元數據、提示、模型、設定和成本，以供稽核與可重現性使用。
最小文字轉影片範例
import os
import time
from pathlib import Path
import requests
API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai/v1"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "grok-imagine-video-1.5",
"prompt": (
一個霧面黑色的產品盒在反光表面上打開。
柔和的珊瑚色燈光在相機運作時照亮產品
"緩慢推近。高級棚拍燈光，逼真動態，無文字。"
),
"duration": 6,
"resolution": "720p",
}
create = requests.post(
f"{BASE_URL}/videos/generations"
headers=HEADERS,
json=payload,
timeout=60,
)
create.raise_for_status()
request_id = create.json()["request_id"]
deadline = time.time() + 15 * 60
while time.time() < deadline:
status_response = requests.get(
f"{BASE_URL}/videos/{request_id}"
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=60,
)
status_response.raise_for_status()
result = status_response.json()
如果結果["狀態"] == "完成":
video_url = result["影片"]["網址"]
video_response = requests.get(video_url, timeout=180)
video_response.raise_for_status()
Path("output.mp4").write_bytes(video_response.content)
print("已儲存 output.mp4")
中斷
如果結果["狀態"] 在 {"expired", "failed", "cancelled"} 中：
raise RuntimeError(f"生成結束，狀態：{result['status']}")
time.sleep(5)
否則：
raise TimeoutError("影片生成未在截止時間前完成")
部署前請先查閱 xAI 目前的 API 架構。模型名稱、支援的參數及回應狀態碼皆可能變動。
影像轉影片
xAI 的文件支援公開圖片網址或 base64 資料 URI 來進行以圖片為主的生成。概念上，請求會加入一個圖片物件：
payload = {
"model": "grok-imagine-video-1.5",
"prompt": (
"保留主體、服裝和背景。"
「主體轉向窗戶，同時攝影機緩慢推進。」
),
"圖片": {"url": "https://example.com/source-image.png"},
"duration": 6,
"resolution": "720p",
}
若輸入內容為私有，請使用短期有效的簽署 URL。請勿僅為了滿足 API 需求而公開客戶媒體。
生產環境錯誤處理
正式上線的客戶端應處理：
- 認證失敗；
- 驗證錯誤；
- 審核拒絕；
- 速率限制；
- 網路超時；
- 已過期的職缺或結果網址；
- 重複提交；
- 部分儲存故障；
- 帳戶預算耗盡。
對可重試的錯誤使用帶抖動的指數退避策略。不要無限期重試驗證或審核失敗的情況。附加冪等鍵或維護您自己的工作記錄，以避免網路重試導致意外產生重複影片。
成本控制
xAI 根據生成的秒數對影片定價，費率因模型和解析度而異。媒體輸入也可能產生費用。請儲存每個作業的模型、解析度、時長及回傳的使用量資料。
有用的安全措施包括：
- 每次請求的最大持續時間；
- 每位用戶的每日支出上限；
- 低解析度草稿模式；
- 高解析度重新渲染前的審核；
- 自動重試次數限制；
- 異常生成量的警報；
- 每個已核准片段報告的成本。
佇列與並行設計
影片作業應進入佇列。工作者提交請求、負責任地輪詢，並將完成的檔案傳輸至持久化物件儲存。您的應用程式資料庫應追蹤：
- 內部工作ID；
- xAI 請求 ID；
- 使用者與專案；
- 提示與輸入參考；
- 狀態與進度；
- 時間戳記；
- 模型與設定；
- 輸出儲存 URL；
- 成本與審核結果。
尊重當前帳戶層級的速率限制。若造成節流或無法控制的成本，更多的並行處理並無助益。
安全與隱私
驗證使用者對上傳圖片擁有權利，且已取得可辨識人物的許可。讓系統拒絕明顯試圖建立未經同意之親密影像、欺騙性冒用身分、剝削或非法內容的行為。僅保留服務所需之媒體與紀錄，並公布明確的刪除政策。
不得移除提供者浮水印或來源標記。對於高觸及率、政治、醫療、財務或身分敏感內容，應納入人工審核。
在API整合前進行無程式碼評估
當創意規格已經驗證後，API 專案會更容易進行。使用 Elser AI 上的 Grok Imagine Video 來測試提示詞、參考圖片的適用性、畫面比例以及鏡頭接受標準。一旦團隊能夠可靠地描述出可用的鏡頭，就可以將重複的部分自動化。
啟動檢查清單
- API 金鑰儲存在密碼管理器中。
- 當前模型與參數已根據 xAI 文件驗證。
- 已測試佇列、超時、重試及冪等性邏輯。
- 從臨時 URL 傳輸的輸出。
- 已啟用每位使用者及全域支出上限。
- 審核失敗處理時不進行盲目重試。
- 來源權利與同意已確認。
- 日誌排除敏感媒體和憑證。
- 浮水印與AI揭露規則已記錄。
