Grok Imagine 系列
- 文生视频与图生视频
- 时长 6 到 15 秒，分辨率 480p 或 720p
- 画幅支持 16:9、9:16、1:1、3:2、2:3
认证
All endpoints authenticate with a Bearer token.
Get an API key: open the console and create one.
Add it to the request header:
Authorization: Bearer YOUR_OAIRoute_KEY请求参数
提交成功只返回任务 ID，不含视频本身。拿成片用 task_id 轮询获取任务状态，成片地址在 result.videos[0].url，该地址约 24 小时后过期，请及时转存。
取值 grok-imagine-1.5-video-ext。
画面描述，中英文均可。
时长，单位秒，取值 6 到 15，默认 6。
必须传数字，传字符串会报错。
取值 480p、720p，默认 480p。
输出画幅，取值 16:9、9:16、1:1、3:2、2:3，默认 16:9。
带参考图时比例跟随图片，该字段失效。
参考图，最多 7 张，必须是公网可访问地址。
不接受 Base64，需要先上传到可访问的存储。
为 true 时先做内容审查，默认 false。
A successful submission returns only the task ID, not the video itself. Poll Get task status with the task_id; the video URL is at result.videos[0].url, expires after about 24 hours, so copy it promptly.
Always grok-imagine-1.5-video-ext.
The scene description, in Chinese or English.
Duration in seconds, 6 to 15, default 6.
Must be a number; passing a string errors out.
480p or 720p, default 480p.
Output framing: 16:9, 9:16, 1:1, 3:2, or 2:3, default 16:9.
With a reference image the ratio follows the image and this field has no effect.
Reference images, up to 7, and each must be a publicly reachable URL.
Base64 isn't accepted; upload to accessible storage first.
When true, runs a content check first. Defaults to false.
模式判定
没有模式字段，按传入的字段判定。
只有 prompt 是文生视频。
传 image_urls 是图生视频，输出比例自动继承参考图。
There's no mode field; the mode is inferred from the fields you pass.
Only prompt means text to video.
Passing image_urls means image to video, and the output ratio inherits the reference image's.
支持的模型列表
| 模型 ID | 定位 |
|---|---|
grok-imagine-1.5-video-ext | 当前唯一可用版本，新请求请一律使用这个名字 |
| Model ID | Positioning |
|---|---|
grok-imagine-1.5-video-ext | Currently the only available version; use this name for all new requests |
使用限制
duration必须是数字，不能是字符串- 参考图必须是公网 URL，不接受 Base64
- 参考图最多 7 张
durationmust be a number, not a string- Reference images must be public URLs; Base64 isn't accepted
- At most 7 reference images
响应
提交成功返回统一的受理结构：
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}状态码，200 表示任务已受理。
本次提交的任务列表，逐项提交时按顺序排列。
受理状态，提交成功时为 submitted。
任务 ID，用它轮询结果。
A successful submission returns the standard accepted structure:
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}The status code; 200 means the task was accepted.
The list of tasks submitted this time, in order when submitting item by item.
The acceptance status; submitted on success.
The task ID; use it to poll for the result.
错误
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 请求参数无效，或参数组合冲突 |
| 401 | authentication_error | 身份验证失败，需检查 API Key |
| 402 | payment_required | 账户余额不足，需先充值 |
| 429 | rate_limit_error | 调用频率过高，稍后重试 |
参数错误在提交阶段同步返回，不创建任务、不扣费。
| HTTP | type | Notes |
|---|---|---|
| 400 | invalid_request_error | Invalid parameters, or a conflicting combination |
| 401 | authentication_error | Authentication failed; check the API key |
| 402 | payment_required | Insufficient account balance; top up first |
| 429 | rate_limit_error | Too many calls; retry later |
Parameter errors are returned synchronously at submission, creating no task and charging nothing.
For more status codes and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.
查询任务
GET /v1/tasks/{task_id} 返回任务进度与结果，status 为 completed 时成片地址在 result.videos[0].url，元素带 expires_at 过期时间戳。
建议每 5 到 10 秒轮询一次，客户端总超时设为 10 到 15 分钟。status 取值 pending、processing、completed、failed、cancelled，以状态判定完成，不要依赖 progress。
失败任务自动退回费用，error.message 给出原因。
GET /v1/tasks/{task_id} returns task progress and results; once status is completed, the video URL is at result.videos[0].url, with an expires_at timestamp on the element.
Poll every 5 to 10 seconds, with a 10 to 15 minute client timeout. status is one of pending, processing, completed, failed, cancelled; judge completion by status, not by progress.
Failed tasks are refunded automatically, with the reason in error.message.