如何通过 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 型号指南。







