上手 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 型号指南。







