Grok怎么用API生成视频？提交任务、轮询状态与临时链接下载核对

视频生成通常不是立即返回一个MP4文件。Grok视频API先创建任务，再通过状态查询取得结果。如果把请求已受理当成视频已完成，或者等待超时后不断重新提交，可能重复生成并增加费用。本教程以一段无人物、无文字的纸船场景为例，讲清提交、轮询、下载与验收，不展示虚构的生成样片。

第一步：确认API模型与输出要求

官方当前文本生成视频示例使用grok-imagine-video-1.5，可配置时长、比例和分辨率。需要独立API密钥和相应团队权限，费用按当前控制台与文档计价。本例先用5秒、16:9和720p测试，不从聊天会员名称推断API视频功能已经包含。

官方时长参数当前为1至15秒，默认8秒；不同模式和模型另有限制。文字生成视频与视频编辑、图片转视频不是同一模式，不应混用各自的时长或画幅规则。先做单个短任务，核对成功后再考虑更高分辨率或批量工作。

第二步：提交后保留任务编号

import os
import time
import requests

base = "https://api.x.ai/v1"
headers = {"Authorization": "Bearer " + os.environ["XAI_API_KEY"]}
r = requests.post(base + "/videos/generations", headers=headers, json={
    "model": "grok-imagine-video-1.5",
    "prompt": "一只纸船在雨后的浅水中缓缓漂动，固定镜头，柔和日光，无文字无人物。",
    "duration": 5, "aspect_ratio": "16:9", "resolution": "720p",
    "generate_audio": False,
}, timeout=60)
r.raise_for_status()
request_id = r.json()["request_id"]
print("request_id:", request_id)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(base + "/videos/" + request_id, headers=headers, timeout=30)
    result.raise_for_status()
    data = result.json()
    if data["status"] == "done":
        video = requests.get(data["video"]["url"], timeout=120)
        video.raise_for_status()
        with open("paper-boat-demo.mp4", "wb") as f:
            f.write(video.content)
        print("saved: paper-boat-demo.mp4")
        break
    if data["status"] == "failed":
        raise RuntimeError(str(data.get("error", {})))
    time.sleep(5)
else:
    raise TimeoutError("仍未完成；保留request_id，之后查询原任务，不自动重复提交。")

运行代码会调用付费生成接口，本教程仅做离线语法检查。密钥从环境变量读取，不写入文件或日志；本地输出文件名也应避免覆盖已有作品。任务编号可以用于后续查询，但不要把完整请求、密钥或私密素材一起公开到问题反馈中。

第三步：区分pending、done和failed

官方状态包括pending、done和failed。pending表示仍在生成，继续查询原任务；done时从video.url取临时地址；failed时查看error.code与message。程序等待期限到了，只能说明客户端没有在该时间内拿到完成结果，不能证明服务端已取消。

保存request_id后可以恢复查询，避免一超时就提交第二个相同视频。若首次POST本身网络中断，无法确定是否已经创建任务，要先检查当前可用任务记录和调用情况，不能声称一定没有产生费用。示例没有实现自动重复提交，也没有承诺完成耗时。

第四步：及时下载并实际播放

官方返回的是临时视频URL，需要长期保存时应及时下载或处理，不保证永久可访问。下载完成后实际打开MP4，检查能否播放、实际时长、画幅、清晰度和主体运动，确认没有意外文字或变形。文件名存在不等于内容是完整视频，也不要仅凭HTTP成功判断生成质量。

视频默认带音轨，本例明确generate_audio为false以请求静音。需要声音时重新按官方模式设置，并核对实际音轨。提示词要求是创作目标，不是输出保证；不满意时记录具体问题，先改一个因素再考虑新的付费任务，保留前后版本方便比较。

第五步：根据错误类别修正

invalid_argument要查参数与输入，permission_denied要查密钥所属团队和能力权限，failed_precondition要查模型与模式兼容；service_unavailable属于暂时服务负载问题。鉴权、模型不存在和限流也可能在任务创建前同步返回，不能都当作failed视频结果处理。

验收标准是任务编号可追踪、完成状态明确、结果已保存且能播放，错误与重试不会混成多份不明任务。内容质量仍需人工检查，本教程没有实际生成或宣称测得任何视频效果、等待时间或成本。

官方资料

资料核对日期：2026年10月31日。

• xAI：Video Generation参数、轮询与错误状态