原生透传层

生成视频

提交一个视频生成任务，立刻拿到 request_id，再轮询到完成为止。请求体原样转发给 Grok，报错是官方原文。

POST/xai/v1/videos/generations

端点与完整链路

http

POST /xai/v1/videos/generations      # 提交任务
GET  /xai/v1/videos/{request_id}     # 轮询（见「查询视频任务」）

视频是异步的，链路固定三步：

① POST 提交  →  拿到 request_id
② GET  轮询  →  直到 status 变成 done / failed / expired
③ 取 video.url → 下载 mp4

同一能力在 OpenAI 兼容层的写法见生成视频（OpenAI 兼容）。两层的任务 ID 不通用，选一层就一路用到底。

请求

bash

curl -X POST https://api.wxiai.com/xai/v1/videos/generations \
  -H "Authorization: Bearer $WXIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "一只橘猫在雨中的霓虹街道上慢步走过，电影感，浅景深",
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

四种生成模式

同一个端点，按你传了哪些字段自动进入不同模式：

模式	要传的字段	说明
文生视频	只有 `prompt`	纯文字生成，`prompt` 必填
图生视频	`prompt` + `image`	把这张图当首帧动起来
参考图 / 参考音	`prompt` + `reference_images` / `reference_audios`	用参考素材控制风格、主体、声音
首尾帧	`image` + `last_frame`（可只给 `last_frame`）	钉死首帧和/或尾帧

prompt 只有文生视频必填。带了 image、reference_images、reference_audios 或 last_frame 时就可以省略。四种模式的完整参数见视频生成总览。

image / last_frame 对象里放什么

只有 url（公网 URL 或 base64 data URI）和 file_id（xAI 文件服务 ID）两个字段，二选一。官方示例里出现的 "type": "image_url" 不在 API schema 中，写上不起作用。

请求参数

参数	必填	说明
`model`	是	如 `grok-imagine-video-1.5`、`grok-imagine-video`
`prompt`	否	文生视频必填；其余模式可选
`duration`	否	时长（秒），1–15，默认 `8`
`resolution`	否	`480p`（默认）/ `720p` / `1080p`
`aspect_ratio`	否	`1:1`、`16:9`（默认）、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`
`image`	否	首帧图，格式 `{"url": ...}` 或 `{"file_id": ...}`
`last_frame`	否	尾帧图，仅 `grok-imagine-video-1.5`
`reference_images`	否	参考图数组
`reference_audios`	否	参考音数组，最多 3 条，每条用 `voice_id` 或 `url`
`storage_options`	否	把产物存进 xAI 文件服务，见总览
`user`	否	你自己终端用户的标识

原生路径没有 OpenAI 的别名

seconds 和 size 只在兼容层被识别。原生层不做换算，写它们会被原样丢给 Grok。

官方字段是 duration 和 resolution。

提交时返回 request_id：

json

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}

字段	说明
`request_id`	原生层的任务 ID，查结果时要用它
其他字段	提交响应只有这一个字段，任务进度与结果都在查询接口返回

状态机、失败错误码与下载方式全部在查询视频任务说明。

接下来：用 GET 查结果

本页只负责启动任务。提交成功后拿到的 request_id 就是查结果的凭据，交给：

http

GET /xai/v1/videos/{request_id}

状态值、失败错误码、下载方式全部在查询视频任务一处说明，不用在本页找。

这一层的注意点

prompt 在大部分模式里可以省略，但文生视频必须给：只传 image 就是图生视频。
last_frame 挑模型：经典 grok-imagine-video 会拒绝，只有 grok-imagine-video-1.5 支持。
image 和参考素材不能乱混：在 1.5 上，image 一旦和 reference_images / reference_audios / last_frame 同时出现，含义就变成「钉死首帧 + 参考引导」。
别把轮询写成死循环：服务端 600 秒后判定超时并退还额度，客户端也要有自己的超时上限。

生成视频

端点与完整链路 ​

请求 ​

四种生成模式 ​

请求参数 ​

返回 ​

接下来：用 GET 查结果 ​

这一层的注意点 ​

相关页 ​

端点与完整链路

请求

四种生成模式

请求参数

返回

接下来：用 GET 查结果

这一层的注意点

相关页