Grok Imagine 视频 API 教程：用 Python 文生视频

Grok Imagine 视频 API 是异步接口：先提交提示词建一个任务，再按任务 ID 轮询，完成后下载 MP4。当前模型是 grok-imagine-video-1.5。2026 年 10 月 24 日，我们这条 6 秒 720p 的片子从发出请求到可以下载用了 46 秒，而且带音轨。

下面给出复制就能跑的脚本、真正影响结果的参数、一条片子的费用和耗时，以及常见报错。

先说结论

• 模型： grok-imagine-video-1.5。xAI 说 1.5 已结束预览，2026 年 6 月 16 日正式可用（xAI）。
• 参数： duration 4 到 15 秒，resolution 填 "720p"，ratio 例如 "16:9"。
• 费用： 按 xAI 标价，720p 每秒 0.14 美元，6 秒一条 0.84 美元（xAI 模型页，2026 年 10 月 24 日核对）。
• 耗时： 我们这条 6 秒 720p 的任务用了 46 秒。一小时内用同一个任务 ID 轮询并下载文件。

Grok Imagine 视频 API 怎么用？

三步：建任务、轮询、下载（xAI 视频生成指南，2026 年 10 月 24 日核对）。

在 xAI 自己的 API 上，你向 https://api.x.ai/v1/videos/generations 发一个 POST 请求，带上模型 ID 和提示词，会拿回 request_id。然后用 GET 轮询 https://api.x.ai/v1/videos/{request_id}，直到任务变成 done，再读 video.url（同一份指南）。

xAI 推荐简单视频用 grok-imagine-video-1.5-lite。需要参考图、声音、固定帧或原生 1080p 时，用 grok-imagine-video-1.5（视频概览，2026 年 10 月 24 日核对）。静态图可以看 Grok Imagine 图像 API 教程，那里讲了 xAI 的三个图像模型；想把 Grok 和其它视频 API 放在一起比，看 视频模型盘点。

OmniaKey 在卖 Grok Imagine Video 1.5 的接口，支持人民币充值，我们的例子就是通过它跑的。调用用 POST https://api.omniakey.com/v1/media/tasks，带 Idempotency-Key 头，返回 202 和一个 id；查状态用 GET /v1/media/tasks/{id}（OmniaKey 媒体概览，2026 年 10 月 24 日核对）。同样的建任务、轮询、下载流程也适用于 视频 API 文档 里的其它模型：Kling 3.0、Seedance、Wan 3.0、MiniMax H3 和 HappyHorse。下面的价格都是 xAI 自己的。

xAI 的字段名来自它的 Videos API 参考，OmniaKey 的字段名来自它的 视频 API 文档，都是 2026 年 10 月 24 日核对。

哪些参数可以设？

提示词加三个设置，决定了你拿到什么。

• duration 在 OmniaKey 上必填，也决定价格（OmniaKey 视频文档）。OmniaKey 这个模型最短 4 秒，xAI 最长 15 秒（视频生成指南），所以填 4 到 15。
• resolution 用小写 "720p"。OmniaKey 的 Grok 视频最高 720p（OmniaKey 媒体概览）。xAI 自己的 API 还有 480p（默认）和原生 1080p（生成指南）。
• ratio 有九个值：1:1、16:9、9:16、4:3、3:4、3:2、2:3、21:9 和 5:2，默认 16:9（视频生成指南）。我们跑的是 16:9。
• n 只能是 1（OmniaKey 视频文档）。
• 提示词：先写镜头、光线、相机运动，再加一行 Sound:。这行里写到的任何东西都可能出现在画面里：我们那行声音提示提到勺子，画面里就多了一把勺子和一只手。

Python 怎么把文字提示变成视频？

装好 requests，把 key 放进 OMNIAKEY_API_KEY，然后运行脚本。

pip install requests
export OMNIAKEY_API_KEY="your-key"

这是我们跑过的脚本，一字未改：

import os
import time
import uuid

import requests

API = "https://api.omniakey.com/v1/media/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}"}

PROMPT = (
    "Close-up of a white ceramic coffee cup on a wooden café table by a window, "
    "morning sunlight, steam curling up from the coffee, the camera slowly pushes in, "
    "shallow depth of field. Sound: quiet café chatter and a spoon clinking on a saucer."
)

# 1. 建任务。只有原样重试这个请求时，才复用同一个 Idempotency-Key。
job = requests.post(
    API,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json={
        "model": "grok-imagine-video-1.5",
        "type": "video",
        "operation": "text_to_video",
        "input": {"prompt": PROMPT},
        "parameters": {"duration": 6, "resolution": "720p", "ratio": "16:9"},
    },
    timeout=30,
)
job.raise_for_status()
task = job.json()
print("task:", task["id"], task["status"])

# 2. 轮询到任务结束。任务慢只是还没跑完：继续查同一个 id。
while True:
    task = requests.get(f"{API}/{task['id']}", headers=HEADERS, timeout=30).json()
    if task["status"] not in ("queued", "processing"):
        break
    time.sleep(5)

if task["status"] != "succeeded":
    raise SystemExit(f"job ended {task['status']}: {task.get('error')}")

# 3. 现在就下载：签名链接大约一小时过期。
asset = task["assets"][0]
with open("coffee.mp4", "wb") as f:
    f.write(requests.get(asset["url"], timeout=120).content)
print("saved coffee.mp4", asset["mime_type"], asset["byte_size"], "bytes")

2026 年 10 月 24 日它输出的最后一行：

saved coffee.mp4 video/mp4 2659230 bytes

脚本第一行会打印任务 ID 和状态。记住这个 ID：脚本中断时靠它找回任务。

一条 6 秒 720p 的任务返回这些：

片子和提示词对得上：白色陶瓷杯装黑咖啡，白色杯碟，放在窗边木桌上，热气往上飘，后面的咖啡馆是虚的。镜头稳定推进，杯子从大约占画面三分之一宽长到一半。4.5 秒时一把勺子从右边进来。音频是一段安静的轨道，4.8 秒有一个尖峰，正好是勺子碰到碟子的那一刻。

一条片子多少钱，要等多久？

xAI 按秒计费，单价看模型和分辨率。它的模型页（2026 年 10 月 24 日核对）按分辨率列出价格；价格页上那个统一的每秒 0.080 美元是 480p 的价。

按这些标价算：

• 1.5 跑 720p 6 秒：6 × 0.14 = 0.84 美元。
• 1.5 跑 480p 8 秒（默认长度）：8 × 0.08 = 0.64 美元。
• 1.5 跑 1080p 15 秒：15 × 0.25 = 3.75 美元。
• 1.5 Lite 跑 720p 6 秒：6 × 0.03 = 0.18 美元。

xAI 只公布每秒的视频价格（价格页，2026 年 10 月 24 日核对）。

在 OmniaKey 上，费用是你请求的时长乘以每秒单价，建任务时从余额里扣，任务失败会自动退回（OmniaKey 视频文档，2026 年 10 月 24 日核对）。我们请求 6 秒，拿到 6.04 秒的文件，按 6 秒计费。当前价格见 Grok Imagine Video 1.5 页面。

我们这个任务从请求到 succeeded 用了 46 秒。xAI 说生成「通常最多几分钟」，它自己的 SDK 最多等 10 分钟（生成指南）。每隔几秒轮询一次。如果要给循环加超时，时间留足；超时之后就按任务 ID 再查一次，别再发新请求。

签名链接大约一小时有效，我们那条正好在任务完成一小时后过期。任务记录保留 24 小时，所以可以再查一次拿新链接（OmniaKey 媒体概览，2026 年 10 月 24 日核对）。

会碰到哪些报错？

大多数错误在建任务之前就返回，不花钱。任务建好之后失败的，以 failed 结束，费用退回。OmniaKey 的媒体文档（2026 年 10 月 24 日核对）列了这些：

2026 年 10 月 24 日，我们故意触发了前两个。不带 Idempotency-Key 头返回 HTTP 400：

{"error":{"code":"missing_idempotency_key","message":"Idempotency-Key is required and must be at most 255 characters"}}

用这个任务的 key 换掉提示词再发一次，返回 HTTP 409：

{"error":{"code":"idempotency_key_reused","message":"Idempotency-Key was already used with a different request"}}

• 任务慢就当它还在跑。继续轮询同一个任务 ID；换个新的 Idempotency-Key 重发，会再开一个任务，也再收一次钱。
• 重放的请求返回 200 和原来的任务，但没有 assets 列表。所以脚本先取任务，再读 assets。

常见问题

Grok Imagine Video API 免费吗？

不免费。xAI 只按秒标价，最便宜的是 1.5 Lite 480p，每秒 0.02 美元（模型页，2026 年 10 月 24 日核对）。

Grok Imagine 的视频能有多长？

xAI 的 API 是 1 到 15 秒，默认 8 秒（视频生成指南）。通过 OmniaKey 用 4 到 15 秒：OmniaKey 这个模型最短 4 秒（OmniaKey 视频文档，2026 年 10 月 24 日核对），xAI 最长 15 秒。

Grok Imagine Video 有声音吗？

有，默认带音轨，音效、环境声和人声跟着画面一起生成（视频生成指南；xAI 公告）。我们那条是立体声 AAC 音轨。xAI 的 API 传 generate_audio: false 可以要无声视频；要从下载好的文件里去掉音轨，运行：

ffmpeg -i coffee.mp4 -an -c:v copy coffee-silent.mp4

Grok Imagine 能把图片变成视频吗？

能，在 xAI 的 API 里：图片用 image 传（公开 URL、base64 data URI 或 Files API 的 file_id；JPEG、PNG 或 WebP），它成为第一帧，提示词可以不给，片子沿用图片的比例（图生视频指南；Videos API 参考）。等 OmniaKey 上的图生视频例子端到端验证过，会补在这里。

Grok Imagine Video 1.5 和 1.5 Lite 有什么区别？

Lite 每秒最便宜。它支持文生视频和图生视频，带对口型语音，1080p 是从 720p 放大得到的。它没有参考图、声音参考和关键帧（视频概览；Lite 模型页）。例子用的是 1.5，在 OmniaKey 上就是 Grok Imagine Video 1.5。

grok-imagine-video-1.5-preview 还能用吗？

xAI 还把它列为别名，但 1.5 已结束预览，2026 年 6 月 16 日正式可用（模型页；xAI 公告）。用 grok-imagine-video-1.5。