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 实操指南。







