如何透過 OpenAI 相容介面呼叫 Grok Video 3 API
目標型號:
grok-video-1.5、grok-video-1.0
推理介面:https://api.toapis.com/v1/videos/generations
相關閱讀:Grok Video 實作指南 · Grok Imagine 官方渠道 API · Chatbox OpenAI 相容配置 · 列出模型
1. 核心摘要與性能速覽 (TL;DR)
- 這裡的“OpenAI 相容”指什麼:ToAPIs 文件提供統一的
/v1源站、Bearer 鑑權,以及 OpenAI 風格的模型列表和聊天補全介面。公共 Grok Video 型號登記在目錄的openai-video端點家族中。這並不表示未公佈的grok-video-3可以使用,也不等於已經文件化了 OpenAI Videos SDK 方法。 - 型號:在
GET /v1/models?type=video確認你的金鑰可見後,使用grok-video-1.5或grok-video-1.0。日期為 2026-11-10 的公共目錄快照未列出grok-video-3。 - 影片路徑:用
POST /v1/videos/generations建立,用GET /v1/videos/generations/{id}輪詢。官方示例使用https://toapis.com(中國大陸使用https://toapis.cn)。本系列也使用https://api.toapis.com。 - 共享鑑權:在
Authorization: Bearer中使用同一把 API Key。這些影片呼叫沒有單獨的公開 OAuth 範圍文件。 - 客戶端選擇:可以把 OpenAI SDK 的
base_url="https://api.toapis.com/v1"用於聊天,以及熟悉的金鑰/源站配置。對於 Grok Video,本指南使用已文件化的 REST JSON 請求體,以便顯式保留video_generation_mode和圖片 URL 欄位。
2. 相容源站、模型列表與影片路徑
請把源站、/v1 字首和金鑰放在一起使用。把 ToAPIs 金鑰配到 https://api.openai.com/v1,或把 ToAPIs 源站配到供應商原生 Grok 路徑,都屬於另一套——而且未經文件化的——做法。
| 步驟 | 文件化路徑 | 說明 |
|---|---|---|
| 列出模型 | GET /v1/models?type=video | 預設 GET /v1/models 只返回文字型號。請使用 type=video 或 type=all |
| 上傳本地圖片 | POST /v1/uploads/images(multipart file) | 讀取 data.url。不要在生成請求中傳送 base64 |
| 建立 Grok Video 任務 | POST /v1/videos/generations | 請求體包含 model、prompt 以及 1.5 的模式/媒體欄位 |
| 輪詢狀態 | GET /v1/videos/generations/{id} | 終態為 completed 和 failed |
| 聊天(不是影片) | POST /v1/chat/completions | 僅共享源站和金鑰 |
在 grok-video-1.5 上,將 video_generation_mode 設為 text_to_video、first_frame_image_to_video 或 reference_images_to_video,使 JSON 與實際傳送的媒體一致。欄位級約定見 Grok Video 實作指南 和 Grok Video 1.5 API 參考。

圖 1:把客戶端指向 ToAPIs 的 /v1 源站,用模型列表發現 grok-video-1.5 或 grok-video-1.0,然後在 /v1/videos/generations 上提交併輪詢——不要走 chat/completions。
若你配置的是桌面客戶端而不是應用程式碼,Chatbox 設定指南 介紹了聊天場景下的 Host 欄位寫法。不要指望同一條聊天路徑會返回影片檔案。
3. 生產級實作:cURL 與 Python
本系列面向國際環境的示例使用 https://api.toapis.com。官方文件要求中國大陸使用者使用 https://toapis.cn。每個環境只保留一個源站。
步驟 1:先發現型號,再用 cURL 提交
curl -sS "https://api.toapis.com/v1/models?type=video" \
-H "Authorization: Bearer $TOAPIS_API_KEY"
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"
}'
硬編碼之前,先檢查模型列表中的精確 id 字串。如果沒有 grok-video-3,就不要傳送它。
步驟 2:Python — 共用源站,REST 呼叫影片介面
這裡的 OpenAI SDK 僅用於共享 base_url 和 API Key。影片的建立與輪詢仍走已文件化的 generations 路徑,以免 1.5 的請求體欄位在非官方客戶端對映中丟失。
import os
import time
import requests
from openai import OpenAI
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
# Shared origin and key. Use this client for chat completions; do not assume
# a videos.create mapping unless your account docs define one.
client = OpenAI(base_url=f"{BASE}/v1", api_key=API_KEY)
def list_video_model_ids() -> list[str]:
res = requests.get(
f"{BASE}/v1/models",
headers=HEADERS,
params={"type": "video"},
timeout=30,
)
res.raise_for_status()
data = res.json()
items = data.get("data") or data.get("models") or []
return [item.get("id") or item.get("name") for item in items if item]
def dispatch_grok_video(prompt: str, model: str = "grok-video-1.5") -> str:
available = set(list_video_model_ids())
if available and model not in available:
raise ValueError(f"{model} is not in this key's video model list")
res = requests.post(
f"{BASE}/v1/videos/generations",
headers=HEADERS,
json={
"model": model,
"prompt": prompt,
"video_generation_mode": "text_to_video",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9",
},
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__":
print("Video models (excerpt):", list_video_model_ids()[:20])
task_id = dispatch_grok_video("A cinematic product shot with a slow camera push-in")
print("Task:", task_id)
print("Video:", poll_task(task_id))
如果列表介面的響應結構與預期不符,請記錄原始 JSON,並對照你帳戶的 列出模型 頁面調整解析邏輯。當 ID 不存在時,不要發明一個回退邏輯去傳送 grok-video-3。
4. 錯誤處理與狀態碼對照
下表是排查起點,並不保證與 ToAPIs 錯誤碼完全一致。即便查詢介面返回 HTTP 成功,也必須讀取任務的 status。詳見 錯誤參考。
| HTTP 或任務狀態 | 常見類別 | 建議操作 |
|---|---|---|
400 | 未知型號、模式與媒體不匹配,或把影片請求體發到了聊天路徑 | 用 GET /v1/models?type=video 確認型號,確認釋出到 /v1/videos/generations,並且 1.5 任務設定了匹配的 video_generation_mode |
401 | 缺少或無效的 API Key | 使用 ToAPIs 金鑰,而不是 OpenAI 平臺金鑰,並確認 Bearer 請求頭 |
404 | 源站錯誤、缺少 /v1,或使用了 /videos/tasks/{id} 這類自造路徑 | 在提交時使用的同一源站上改為 GET /v1/videos/generations/{id} |
429 | 速率或併發限制 | 若存在 Retry-After 則遵守,並加入抖動後退避 |
5xx 或用戶端逾時 | 閘道器或上游臨時問題 | 重新提交前先查詢已有任務 id |
status: failed | 生成未成功 | 讀取 error.code 和 error.message。不要原樣重試已被策略拒絕的請求體 |
5. 定價與 FinOps ROI
- 相容性不會改變計費 SKU。 計費依據是你傳送的目錄型號(
grok-video-1.5或grok-video-1.0),而不是“使用了 OpenAI SDK”。 - 不要沿用規劃稿裡的單價。 Grok Video 1.5 參考並不保證固定的每秒價格。ToAPIs 定價頁上的官方廠商參考行僅供展示,未必等於帳戶扣費。
- 發現型號成本低,重複生成成本高。 可以短時快取模型列表,但用戶端逾時後務必先查任務狀態,再建立新任務。
- ToAPIs 計費通常是按量付費——請確認帳戶上的現行條款。
6. 常見問題
詳見 frontmatter 中的 FAQ。摘要:相容源站並不會解鎖 grok-video-3;/v1 只加一次;輪詢 /v1/videos/generations/{id};不要假定存在 SDK 的 videos.create 助手;聊天補全不會返回 MP4。
7. 行動清單
- 在 ToAPIs 開發者門戶 建立金鑰。
- 把客戶端指向
https://api.toapis.com/v1(中國大陸使用https://toapis.cn/v1),並帶上Authorization: Bearer。 - 呼叫
GET /v1/models?type=video,記錄該金鑰可見的精確 Grok Video 型號。 - 用
grok-video-1.5和video_generation_mode: "text_to_video"冒煙測試POST /v1/videos/generations,然後輪詢同一個 id。 - 下一步:欄位與模式細節見 Grok Video 實作指南,目錄現狀見 Grok Video 1.5 型號指南。







