上手 Grok-Video-3 API:關於 xAI 影片引擎,你需要先弄清的目前約定
目標型號:
grok-video-1.5、grok-video-1.0
推理介面:https://api.toapis.com/v1/videos/generations
相關閱讀:OpenAI 相容接入 · Grok Imagine 官方渠道 API · Hailuo 2.3 影片指南 · Grok Video 1.5 參考
1. 核心摘要與性能速覽 (TL;DR)
- 先看目錄:即便標題是 Grok Video 3 實作,接入也必須從 ToAPIs 實際公佈的型號開始。日期為 2026-11-10 的公共生產目錄快照,在
openai-video端點下列出的是grok-video-1.0與grok-video-1.5。2026-11-17 檢查grok-video-3的文件和型號指南 URL,返回的是 HTTP 404。 - 約定:向
POST /v1/videos/generations非同步提交,再輪詢GET /v1/videos/generations/{id},直到completed或failed。官方示例使用https://toapis.com(中國大陸使用https://toapis.cn)。本系列其他指南使用https://api.toapis.com。請選定一個源站並保持一致。 - 模式:
grok-video-1.5文件寫明text_to_video、first_frame_image_to_video和reference_images_to_video。請顯式填寫video_generation_mode,避免單張參考圖被當成舊版首幀請求。 - 媒體:只傳送可公開訪問的
http://或https://URL。本地檔案先透過POST /v1/uploads/images上傳,並使用返回的data.url。不要傳送 base64。 - 應丟棄的未核實表述:規劃稿裡的
grok-video-3型號、99.95% SLA、固定$0.030–$0.038每秒單價,或未來音訊上線日期,都不是目前 ToAPIs 文件內容。請在帳戶中確認實時費率和渠道是否開放。
2. 目前 Grok Video 型號與生成模式
在 model 欄位中使用公共型號名。不要替換成供應商原生名稱、URL slug,或尚未公佈的 grok-video-3 字串。
| 目錄型號 | 文件化任務 | 時長(文件) | 解析度 | 圖片輸入 |
|---|---|---|---|---|
grok-video-1.5 | 文生影片、首幀,或 1–7 張參考圖,由 video_generation_mode 指定 | 整數 1–15 秒 | 參考圖模式為 480p 或 720p;文生影片和首幀在渠道支援時可使用 1080p | 首幀:恰好 1 張 image 或 input_reference。參考圖模式:1–7 張 reference_images |
grok-video-1.0 | 文生影片與圖生影片 | 生成參考:1–15 秒(預設 8)。型號指南 / Playground:目前可用變體存在 6 秒 上限 | 480p、720p | 可選 image 加上 reference_images;合計最多 8 張 |
對於 grok-video-1.5,新接入應顯式指定模式:
video_generation_mode | 必填輸入 | 必須省略 |
|---|---|---|
text_to_video | 非空 prompt | 任何圖片欄位 |
first_frame_image_to_video | 在 image 或 input_reference 中恰好 1 張首幀 | 兩個別名傳了互相沖突的值;除非你的帳戶參考另有說明,否則不要同時再傳參考圖列表 |
reference_images_to_video | prompt 加上 1–7 張 reference_images(字串或 {"url":"..."} 物件) | 只傳一張 reference_images 卻不帶該模式——舊版單圖輸入仍會按首幀處理 |
報價成功並不保證生成渠道已經開放。模式只有在相容渠道啟用後才能使用;不支援的組合可能在建立任務之前就被拒絕。
Grok Video 參考中的常見寬高比為 16:9、9:16、3:2、2:3 和 1:1。具體是否可用仍取決於渠道,請傳送你已為該型號確認過的值。

圖 1:把提示詞(以及可選的公開圖片 URL)提交到 POST /v1/videos/generations,輪詢同一個任務 id,僅在 status 為 completed 後讀取 result.data[0].url。
若你需要官方渠道 Grok Imagine 的影片延長等能力,那是另一組型號,見 Imagine 官方渠道指南。若要對照另一套時長矩陣,見 Hailuo 2.3 指南。
3. 生產級實作:cURL 與 Python
本系列面向國際環境的示例使用 https://api.toapis.com。官方文件要求中國大陸使用者使用 https://toapis.cn。每個環境只保留一個源站。路徑、型號 ID 和 Bearer 請求頭保持不變。
步驟 1:使用 cURL 提交 grok-video-1.5
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-video-1.5",
"prompt": "A cinematic product shot with a slow camera push-in",
"video_generation_mode": "text_to_video",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
首幀任務使用同一路徑,將 "video_generation_mode": "first_frame_image_to_video" 與 image URL 一起傳送。參考圖任務設定 "video_generation_mode": "reference_images_to_video" 和 reference_images 列表,並把 resolution 保持在 480p 或 720p。
步驟 2:Python 提交與輪詢助手
下面的示例遵循文件中的任務狀態路徑,以及 queued / in_progress / completed / failed 狀態。上線前請對照你帳戶的 API 參考,確認 id、result.data[0].url 和響應結構。
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_grok_video(
prompt: str,
*,
model: str = "grok-video-1.5",
mode: str = "text_to_video",
duration: int = 8,
resolution: str = "720p",
aspect_ratio: str = "16:9",
image_url: str | None = None,
reference_images: list[str] | None = None,
) -> str:
if model == "grok-video-3":
raise ValueError("grok-video-3 is not a current public catalog ID")
if mode == "reference_images_to_video" and resolution not in {"480p", "720p"}:
raise ValueError("reference mode is documented as 480p or 720p")
payload = {
"model": model,
"prompt": prompt,
"duration": duration,
"resolution": resolution,
"aspect_ratio": aspect_ratio,
}
if model == "grok-video-1.5":
payload["video_generation_mode"] = mode
if mode == "text_to_video" and (image_url or reference_images):
raise ValueError("text_to_video rejects image fields")
if mode == "first_frame_image_to_video":
if not image_url:
raise ValueError("first-frame mode requires exactly one image URL")
payload["image"] = image_url
if mode == "reference_images_to_video":
refs = reference_images or []
if not (1 <= len(refs) <= 7):
raise ValueError("reference mode requires 1-7 image URLs")
payload["reference_images"] = refs
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 600) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 10.0
start = time.time()
time.sleep(5)
while time.time() - start < deadline_s:
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
time.sleep(interval)
interval = min(interval * 1.5, 30.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
task_id = dispatch_grok_video(
"A cinematic product shot with a slow camera push-in",
mode="text_to_video",
duration=8,
resolution="720p",
)
print("Task:", task_id)
print("Video:", poll_task(task_id))
請把提示詞模板版本與任務記錄一起儲存,以便區分型號/模式變化和措辭變化。在 expires_at 之前下載檔案;狀態參考寫明保留期為 30 天。
4. 錯誤處理與狀態碼對照
下表是排查起點,並不保證與 ToAPIs 錯誤碼完全一致。即便查詢介面返回 HTTP 成功,也必須讀取任務的 status。請求錯誤與 status: failed 的原因(如 content_policy_rejected、insufficient_user_balance、generation_timeout)見 錯誤參考。
| HTTP 或任務狀態 | 常見類別 | 建議操作 |
|---|---|---|
400 | 欄位無效、模式與媒體不匹配,或不支援的組合 | 核對精確目錄型號、video_generation_mode 是否與圖片欄位一致、參考圖模式是否保持 480p 或 720p,以及圖片值是否為公開 URL |
401 | 缺少或無效的 API Key | 在 ToAPIs 控制檯輪換金鑰,並確認 Authorization: Bearer 請求頭 |
429 | 速率或併發限制 | 若存在 Retry-After 則遵守;加入抖動後退避;僅在安全時重試 |
5xx 或用戶端逾時 | 閘道器或上游臨時問題 | 重新提交前先查詢已有任務 id |
status: queued 或 in_progress | 不是錯誤 | 等待並再次輪詢;不要建立第二個任務 |
status: failed | 生成未成功 | 讀取 error.code 和 error.message(如有則包括 error.reason)。不要原樣重試已被策略拒絕的請求體 |
5. 定價與 FinOps ROI
- 不要沿用規劃稿裡的單價。
grok-video-1.5的 API 參考寫明,定價以目前帳戶和 SKU 配置為準,該頁不保證固定的每秒價格。ToAPIs 定價頁上的官方廠商參考行僅供展示,未必等於帳戶實際扣費。 - 報價不是渠道保證。 1.5 參考明確指出:報價成功並不意味著生成渠道可用。
- 在提示詞層控制成本:先用
720p和 8 秒左右的中等時長打樣,保留版本化模板,一次只改一個變數;用戶端逾時後,先查任務狀態再決定是否重提。 - 官方廠商合同常帶年度承諾、席位配額和預付門檻。ToAPIs 計費通常是按量付費——請確認帳戶上的現行條款。
6. 常見問題
詳見 frontmatter 中的 FAQ。摘要:grok-video-3 不是目前公共目錄型號;請從 grok-video-1.5 或 grok-video-1.0 起步;把 1.0 的時長上限當作渠道相關檢查;同步音訊未經文件化;始終輪詢 generations 狀態路徑並持久化任務 id。
7. 行動清單
- 在 ToAPIs 開發者門戶 建立金鑰。
- 透過
GET /v1/models?type=video確認你的金鑰能看到grok-video-1.5或grok-video-1.0——除非該 ID 隨後同時出現在列表和 API 參考中,否則不要傳送grok-video-3。 - 用
video_generation_mode: "text_to_video"、duration: 8和resolution: "720p"冒煙測試上述 cURL 示例。 - 在有截止時間的前提下輪詢
GET /v1/videos/generations/{id},並在expires_at之前下載結果。 - 下一步:若要把現有客戶端指向 ToAPIs,請閱讀 OpenAI 相容接入指南;檢視 Grok Video 1.5 型號指南 瞭解目錄現狀;在 1.0 上依賴超過 6 秒的時長前,先核對 Grok Video 1.0 型號指南。







