Skip to main content
POST
grok-imagine-video-1.5 使用异步 OpenAI Videos 兼容协议。创建任务后保存公开 task_id,再查询任务状态和获取视频。
推荐模型名为 grok-imagine-video-1.5。兼容别名 grok-imagine-1.5-video 仅用于已有客户端,新接入不要使用别名。

接口概览

所有请求都需要以下鉴权头:

支持参数

请求必须使用 multipart/form-data。不要手动填写 multipart boundary,让 HTTP 客户端自动生成 Content-Type
当前渠道的参考图转发不稳定,图生视频可能返回 decode_input_reference_failed_at_index_0Uploaded file must be an image 或渠道熔断错误。文生视频不经过参考图解析链路,稳定性更高。生产环境接入图生视频前请先完成实际验证。

文生视频

图生视频

重复使用同一个 input_reference 字段可以提交多张参考图。不要使用 input_reference[]imageimages 代替该字段。
接口不直接接收参考视频或参考音频。需要基于视频生成时,请在客户端提取视频首个可解码画面,将其转换为 JPEG、PNG 或 WebP,再作为 input_reference 提交。视频首帧方案本质上仍是图生视频,并非直接的视频编辑。

创建响应

创建成功只表示任务已经进入异步队列。
客户端必须保存响应中的公开 task_id。后续查询和下载应继续使用创建任务时相同的 API Key。

查询任务

建议每 5 秒查询一次。视频生成时间可能超过 5 分钟,客户端建议保留至少 30 分钟的轮询窗口。
不要仅凭 progress: 100 判断任务成功。上游可能在进度达到 100 后仍返回 in_progress,只有 status: completed 且存在有效视频结果时才算成功。
成功响应可能直接包含临时视频地址:
结果 URL 是临时地址。下载后请保存到自己的持久存储,不要将其作为永久素材地址。

获取视频内容

如果查询响应没有直接返回结果 URL,或者你希望始终通过鉴权接口下载,可以使用:
浏览器不能把需要 Bearer Token 的 /content 地址直接写入 <video src>。请先使用带鉴权头的 fetch 下载 Blob,再用 URL.createObjectURL 播放。

JavaScript 完整示例

常见错误

重试与计费

  • 创建失败且没有返回 task_id 时,先检查错误和余额是否已经返还。
  • 创建请求超时后不要立即并发重试。请求可能已经到达上游,重复提交可能创建多个任务。
  • 已经获得 task_id 时,只查询原任务,不要再次创建。
  • 视频按实际站点价格和时长预扣费。请以模型广场或账户账单显示为准。
  • 失败任务的退款状态以账户账单为准。如发现未退款,请提供公开 task_id 和请求 ID 联系支持。

安全建议

  • 不要在公开仓库、浏览器日志或错误截图中暴露完整 API Key。
  • 服务端调用优先于公开网页内硬编码 API Key。
  • 保存任务日志时只记录公开 task_id、HTTP 状态和脱敏错误。
  • 临时结果下载完成后应转存到自己的持久存储。