OpenAI 兼容层

生成视频

提交一个视频生成任务，立刻拿到 task_id，再轮询到完成为止。异步接口——没有任何一次请求会直接返回视频文件。

POST/v1/videos/generations

端点与完整链路

http

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

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

① POST 提交  →  拿到 task_id
② GET  轮询  →  直到 status 变成 succeeded / failed
③ 取 url     →  下载 mp4

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

请求

bash

curl -X POST https://api.wxiai.com/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`。也接受 OpenAI 风格的 `seconds`
`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 条
`storage_options`	否	把产物存进 xAI 文件服务，见总览
`user`	否	你自己终端用户的标识

兼容层多认两个 OpenAI 叫法

除了上面的官方字段，兼容层额外还认 seconds（等价 duration）和 size（等价 resolution）。这是便利，官方文档里没有。

提交时返回 task_id 和初始状态：

json

{
  "task_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf",
  "status": "queued"
}

字段	说明
`task_id`	兼容层的任务 ID，查结果时要用它
`status`	提交后是 `queued`（排队）或 `processing`（生成中）

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

接下来：用 GET 查结果

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

http

GET /v1/videos/{task_id}

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

这一层的注意点

prompt 在大部分模式里可以省略，但文生视频必须给：只传 image 就是图生视频。
last_frame 挑模型：经典 grok-imagine-video 会拒绝，只有 grok-imagine-video-1.5 支持。
参考音上限 3 条、单条最长 15 秒：超了会报参数错误。
别把轮询写成死循环：服务端 600 秒后判定超时并退还额度，客户端也要有自己的超时上限。

生成视频

端点与完整链路 ​

请求 ​

四种生成模式 ​

请求参数 ​

返回 ​

接下来：用 GET 查结果 ​

这一层的注意点 ​

相关页 ​

端点与完整链路

请求

四种生成模式

请求参数

返回

接下来：用 GET 查结果

这一层的注意点

相关页