Grok Imagine视频API初学者教程
Grok视频API允许开发者根据文本提示生成视频，对于支持的工作流程，还可以使用起始图像或其他参考。与同步文本响应不同，视频生成是异步的：首次请求返回一个任务ID，您的应用程序需轮询直到结果准备就绪。
本教程解释了架构并提供了一个极简的Python示例。如果你想在编写代码前评估视觉质量，可以在Elser AI的Grok Imagine工作区测试提示词，然后将成功的镜头规格迁移到API中。
你需要什么
- 一个 xAI 开发者账户；
- 一个安全存储的API密钥；
- Python 3.10 或更新版本；
requests包；- 已完成视频文件的持久存储；
- 预算和重试策略。
切勿将API密钥硬编码在源代码中或在浏览器端JavaScript中暴露。
API 工作流如何运作
- 向
/v1/videos/generations发送生成请求。 - 接收一个
request_id。 - 轮询
/v1/videos/{request_id}。 - 当状态变为
done或发生终端故障时停止。 - 请及时下载返回的视频，因为生成的URL是临时的。
- 保存元数据、提示词、模型、设置和成本，用于审计和可复现性。
最小文本转视频示例
import os
import time
from pathlib import Path
import requests
API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai/v1"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "grok-imagine-video-1.5",
"prompt": (
一个哑光黑色的产品盒在反光表面上打开。
柔和的珊瑚色灯光在相机运作时照亮产品
"缓慢推近。高级影棚灯光，真实动态，无文字。"
),
"duration": 6,
"resolution": "720p",
}
create = requests.post(
f"{BASE_URL}/videos/generations"
headers=HEADERS,
json=负载,
timeout=60,
)
create.raise_for_status()
request_id = create.json()["request_id"]
deadline = time.time() + 15 * 60
while time.time() < deadline:
status_response = requests.get(
f"{BASE_URL}/videos/{request_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=60，
)
status_response.raise_for_status()
result = status_response.json()
如果结果["状态"] == "已完成":
video_url = 结果["视频"]["url"]
video_response = requests.get(video_url, timeout=180)
video_response.raise_for_status()
Path("output.mp4").write_bytes(video_response.content)
print("已保存 output.mp4")
中断
如果结果["状态"] 在 {"expired", "failed", "cancelled"} 中：
raise RuntimeError(f"生成结束，状态：{result['status']}")
time.sleep(5)
else:
引发超时错误（"视频生成未在截止时间前完成"）
在部署前，请检查 xAI 当前的 API 架构。模型名称、支持的参数和响应状态可能会发生变化。
图像转视频
xAI 的文档支持使用公共图片 URL 或 base64 数据 URI 进行以图片为主导的生成。从概念上讲，请求会添加一个图片对象：
payload = {
"model": "grok-imagine-video-1.5",
"prompt": (
"保留主体、服装和背景。"
"主体转向窗户，同时镜头缓慢推进。"
),
"图片": {"url": "https://example.com/source-image.png"},
"duration": 6,
"resolution": "720p",
}
如果输入是私有的，请使用短期有效的签名URL。不要仅仅为了满足API要求而公开暴露客户的媒体内容。
生产环境错误处理
生产环境客户端应处理：
- 身份验证失败；
- 验证错误；
- 审核拒绝；
- 速率限制；
- 网络超时；
- 已过期的职位或结果链接；
- 重复提交；
- 部分存储故障；
- 账户预算耗尽。
对于可重试的错误，使用带有抖动的指数退避策略。不要无限重试验证或审核失败。附加一个幂等键或维护你自己的任务记录，以免网络重试导致意外的重复视频。
成本控制
xAI 按生成的秒数对视频定价，费率因模型和分辨率而异。媒体输入也可能产生费用。存储每个作业的模型、分辨率、时长和返回的使用数据。
有用的安全措施包括：
- 每次请求的最大时长；
- 每位用户的每日支出上限；
- 低分辨率草稿模式；
- 高分辨率重新渲染前需获得批准；
- 自动重试次数限制；
- 异常生成量警报；
- 每个已批准片段成本报告。
队列与并发设计
视频任务应进入队列。工作节点提交请求，负责任地轮询，并将完成的文件传输到持久化对象存储。您的应用数据库应跟踪：
- 内部职位ID；
- xAI 请求 ID；
- 用户和项目；
- 提示和输入引用；
- 状态与进度；
- 时间戳；
- 模型和设置；
- 输出存储URL；
- 成本与审核结果。
遵守当前账户层级的速率限制。如果过多的并行操作导致限流或成本失控，则并无益处。
安全与隐私
验证用户对上传图片的权限以及可识别人员的许可。使系统拒绝明显试图创建非自愿亲密图像、欺骗性冒充、剥削或非法内容的行为。仅保留服务所需的媒体和日志，并发布明确的删除政策。
不得移除提供者的水印或来源标识。对于高传播度、政治、医疗、金融或身份敏感的内容，需包含人工审核。
在API集成前进行无代码评估
当创意规格已经验证后，API项目会更容易实施。使用Elser AI上的Grok Imagine Video来测试提示词、参考图像的适用性、宽高比以及镜头验收标准。一旦团队能够可靠地描述出可用的镜头，就可以将重复部分自动化。
启动检查清单
- API 密钥存储在密钥管理器中。
- 当前模型及参数已根据 xAI 文档验证。
- 队列、超时、重试和幂等性逻辑已测试。
- 从临时URL传输的输出。
- 已启用每位用户和全局消费限制。
- 审核失败处理，不进行盲目重试。
- 来源权利和同意已确认。
- 日志排除敏感媒体和凭据。
- 水印和AI披露规则已记录在案。
