Grok Imagine 1.0 影片生成 API:端點、鑑權範圍與錯誤處理
目標型號:
grok-imagine-video-official、grok-imagine-video-1.5-official
推理介面:https://api.toapis.com/v1/videos/generations
相關閱讀:Grok Video 實作指南 · OpenAI 相容接入 · 官方 Imagine 生成 · 官方 Imagine 延長
1. 核心摘要與性能速覽 (TL;DR)
- 型號:標題裡的“Grok Imagine 1.0”需要落到 ToAPIs 實際公佈的字串。日期為 2026-11-10 的公共目錄快照列出了
grok-imagine-video-official與grok-imagine-video-1.5-official(這兩個型號同時出現在 image-generation 和openai-video下)。2026-11-17 檢查grok-imagine-1.0文件路徑時返回 HTTP 404。 - 鑑權:傳送
Authorization: Bearer $TOAPIS_API_KEY。官方頁面沒有為這些呼叫文件化 OAuth 範圍、細粒度許可權名,或範圍發現端點。 - 端點:用
POST /v1/videos/generations建立,用GET /v1/videos/generations/{id}輪詢。延長官方渠道輸出使用POST /v1/videos/{video_id}/extend;若只有公開影片 URL,則使用POST /v1/videos/extend並傳入video_urls。靜幀上傳走POST /v1/uploads/images。 - 能力:
grok-imagine-video-official覆蓋文生影片、圖生影片和多參考圖,解析度為480p或720p,時長 1–15 秒,並可延長 2–10 秒。grok-imagine-video-1.5-official僅支援首幀圖生影片,必須恰好 1 張image,允許1080p,並且不支援延長。 - 計費形態(參考頁沒有固定單價):輸出按解析度檔位按秒計費;每張輸入圖片按張計費;延長還會對源影片時長計費。請確認帳戶實時費率。
2. 端點、鑑權與型號約定
官方文件使用 https://toapis.com(中國大陸使用 https://toapis.cn)。本系列其他指南使用 https://api.toapis.com。請選定一個源站並保持一致。下列路徑都使用同一個 Bearer 請求頭。
| 操作 | 方法與路徑 | 型號說明 |
|---|---|---|
| 上傳靜幀 | POST /v1/uploads/images | Multipart file。JPEG、PNG、WebP 或 GIF,最大 30 MB。讀取 data.url |
| 建立影片 | POST /v1/videos/generations | 兩個官方 Imagine 型號都適用 |
| 查詢狀態 | GET /v1/videos/generations/{id} | 生成與延長任務使用同一路徑 |
| 基於先前任務延長 | POST /v1/videos/{video_id}/extend | 僅 grok-imagine-video-official。video_id 是上一次生成任務的 id |
| 基於公開 URL 延長 | POST /v1/videos/extend | 同一官方型號;沒有路徑 id 時必須提供 video_urls |
| 目錄型號 | 文件化任務 | 時長 | 解析度 | 圖片 | 延長 |
|---|---|---|---|---|---|
grok-imagine-video-official | 文生影片、首幀和多參考圖 | 1–15 秒(預設 8) | 480p、720p | 可選 image 加上 reference_images;合計最多 7 張 | 2–10 秒(duration 預設 6) |
grok-imagine-video-1.5-official | 僅首幀圖生影片 | 1–15 秒(預設 8) | 480p、720p、1080p | image 必填(恰好 1 張首幀)。額外的 reference_images 仍計入 7 張上限 | 不支援 |
官方 Imagine 參考中的寬高比包括 16:9、9:16、4:3、3:4、3:2、2:3 和 1:1。請傳送你已為該型號和渠道確認過的值。
文件中沒有用於分別申請“生成”“延長”或“上傳”的公開範圍字串。訪問許可權取決於 API Key、使用者組和渠道配置已經允許的範圍。若呼叫因許可權或可用性失敗,應檢查該金鑰的模型列表和 錯誤參考,而不是追加一個自造的 scope 查詢引數。

圖 1:一把 Bearer API Key 即可授權上傳、生成或延長,以及狀態輪詢;官方 1.5 型號不會增加延長分支。
非官方的 Grok Video 家族(grok-video-1.0 / grok-video-1.5)見 Grok Video 實作指南。那些型號是另一套約定,並不繼承本頁的延長路徑。
3. 生產級實作:cURL 與 Python
步驟 1:cURL — 官方渠道文生影片
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video-official",
"prompt": "A golden retriever running on a green field in sunny weather",
"duration": 10,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
在 grok-imagine-video-1.5-official 上做首幀任務時使用同一路徑,必須提供 "image": "https://example.com/portrait.jpg",並可將 "resolution": "1080p"。請把示例 URL 換成可訪問的公開地址——若檔案在本地,請先上傳:
curl -X POST "https://api.toapis.com/v1/uploads/images" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-F "file=@/path/to/first-frame.jpg"
步驟 2:Python — 生成、輪詢與可選延長
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_imagine(
prompt: str,
*,
model: str = "grok-imagine-video-official",
duration: int = 10,
resolution: str = "720p",
aspect_ratio: str = "16:9",
image_url: str | None = None,
reference_images: list[str] | None = None,
) -> str:
if model == "grok-imagine-video-1.5-official" and not image_url:
raise ValueError("grok-imagine-video-1.5-official requires exactly one first-frame image")
payload = {
"model": model,
"prompt": prompt,
"duration": duration,
"resolution": resolution,
"aspect_ratio": aspect_ratio,
}
if image_url:
payload["image"] = image_url
if reference_images:
payload["reference_images"] = reference_images
res = requests.post(
f"{BASE}/v1/videos/generations",
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) -> dict:
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={"Authorization": f"Bearer {API_KEY}"}, 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
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")
def extend_official(source_task_id: str, prompt: str, duration: int = 6) -> str:
if not (2 <= duration <= 10):
raise ValueError("official extend duration is documented as 2-10 seconds")
res = requests.post(
f"{BASE}/v1/videos/{source_task_id}/extend",
headers=HEADERS,
json={
"model": "grok-imagine-video-official",
"prompt": prompt,
"duration": duration,
},
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 extend envelope: {data}")
return task_id
if __name__ == "__main__":
task_id = dispatch_imagine(
"A golden retriever running on a green field in sunny weather",
duration=10,
resolution="720p",
)
print("Task:", task_id)
result = poll_task(task_id)
print("Video:", result["result"]["data"][0]["url"])
若要從公開 MP4 而不是任務 id 延長,請對 POST /v1/videos/extend 傳送同一官方型號、提示詞、duration 以及 video_urls 列表。不要用 grok-imagine-video-1.5-official 呼叫延長。
4. 錯誤處理與狀態碼對照
下表是排查起點,並不保證與 ToAPIs 錯誤碼完全一致。即便查詢介面返回 HTTP 成功,也必須讀取任務的 status。錯誤參考 區分了請求錯誤、失敗任務的 error.reason,以及 Webhook 載荷。
| HTTP 或任務狀態 | 常見類別 | 建議操作 |
|---|---|---|
400 | 欄位無效、1.5-official 缺少必填 image、圖片數量超限,或對不支援延長的型號呼叫了延長 | 核對精確官方型號、時長(生成 1–15 秒,延長 2–10 秒)、解析度(1080p 僅適用於 1.5-official),以及所有媒體值是否為公開 URL |
401 | 缺少或無效的 API Key | 輪換金鑰並確認 Authorization: Bearer。不要把未文件化的 scope 引數當作變通辦法 |
429 | 速率或併發限制 | 若存在 Retry-After 則遵守,並加入抖動後退避 |
5xx 或用戶端逾時 | 閘道器或上游臨時問題 | 重新提交前先查詢已有任務 id |
status: queued 或 in_progress | 不是錯誤 | 等待並再次輪詢 |
status: failed 且原因為 content_policy_rejected | 安全或版權稽核 | 檢查提示詞和每一份參考素材;合規輸入仍可能得到被拒絕的輸出 |
status: failed 且原因為 insufficient_user_balance 或 token_quota_exceeded | 餘額或 Token 額度 | 同時檢查餘額和週期性限額 |
status: failed 且原因為 generation_timeout、model_unavailable 或 service_busy | 上游超時或可用性 | 先查詢已有 id;僅在任務已結束後再按退避重試 |
5. 定價與 FinOps ROI
官方 Imagine 生成與延長頁面描述的是計費形態,而不是固定的公開單價:
請使用帳戶和 SKU 返回的費率,而不是稿件中的數字。
grok-imagine-video-1.5-official始終包含一次輸入圖片費用,因為首幀圖片是必填項。- 延長不是免費續寫。 官方延長計費包括生成的延長秒數以及源影片時長。因此迴圈疊加延長時,會再次對不斷變長的源片計費——在編寫迴圈前請先對照實時報價確認這一行為。
- 不要沿用規劃稿裡的單價或 SLA 數字。 ToAPIs 定價頁上的官方廠商參考行僅供展示,未必等於帳戶扣費。
- 先用
720p和中等時長打樣,一次只改一個變數;用戶端逾時後,在查清任務狀態前不要重提。
6. 常見問題
詳見 frontmatter 中的 FAQ。摘要:傳送 grok-imagine-video-official 或 grok-imagine-video-1.5-official,而不是 grok-imagine-1.0;鑑權是 Bearer API Key,沒有公開的 OAuth 範圍矩陣;1.5-official 僅支援首幀且不能延長;延長時長為 2–10 秒,並且會對源片時長計費;始終區分 HTTP 錯誤與 status: failed。
7. 行動清單
- 在 ToAPIs 開發者門戶 建立金鑰。
- 透過
GET /v1/models?type=video確認你的金鑰能看到grok-imagine-video-official或grok-imagine-video-1.5-official。 - 冒煙測試一次
720p官方渠道生成,輪詢GET /v1/videos/generations/{id},並在expires_at之前下載檔案。 - 若需要續寫,僅使用
grok-imagine-video-official和 2–10 秒的duration做延長,並確認報價包含源時長計費。 - 下一步:檢視 官方 Imagine 型號指南 與 官方 Imagine 1.5 型號指南 瞭解目錄現狀;若你實際要接的是非官方
grok-video-*家族,請改讀 Grok Video 實作指南。







