视频生成总览

这一页是视频能力的共享参考——异步模型、四种生成模式、轮询状态机、错误码、长期存储都在这儿。

具体怎么调，看对应端点的独立页：

操作	OpenAI 兼容层	原生透传层
生成视频	生成视频	生成视频
编辑视频	编辑视频	编辑视频
扩展视频	扩展视频	扩展视频
查询 / 下载	查询视频任务	查询视频任务

视频是异步的

视频不是一次请求就拿到结果。完整链路固定是三步：

① POST 提交任务  →  拿到任务 ID
② GET  轮询状态  →  直到 status 变成终态
③ 取视频地址     →  下载 mp4

两层的任务 ID 和状态值完全不同：

	原生透传	OpenAI 兼容
提交	`POST /xai/v1/videos/generations`	`POST /v1/videos/generations`
轮询	`GET /xai/v1/videos/{request_id}`	`GET /v1/videos/{task_id}`
任务 ID 字段	`request_id`	`task_id`
状态值	`pending` / `done` / `expired` / `failed`	`queued` / `processing` / `succeeded` / `failed`
视频地址	`video.url`	`url`

两层 ID 不通用：拿 request_id 去 /v1/videos/{id} 查会找不到任务，反之也一样。选一层就一路用到底。

四种生成模式

POST …/videos/generations 按你传了哪些字段自动进入不同模式：

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

prompt 只有文生视频必填。只要带了 image、reference_images、reference_audios 或 last_frame，prompt 就可以省略。

图生视频

不传 aspect_ratio 时，输出跟随输入图的比例；显式传了就会按你给的比例拉伸画面。

参考图 / 参考音

字段	限制
`reference_images`	参考图数组，写法同 `image`
`reference_audios`	最多 3 条。每条用 `voice_id` 选内置音色，或用 `url` 传真人有声素材（最长 15 秒，需申请开通）
指代方式	图用 `<IMAGE_0>`、`<IMAGE_1>`…，音用 `<AUDIO_0>`、`<AUDIO_1>`、`<AUDIO_2>`

voice_id 和文生音 TTS 用的是同一套内置音色 ID，大小写不敏感；写错了会返回 400 并附上可用音色列表。

参考音的三个前提

只有 grok-imagine-video-1.5 支持；
参考图模式下分辨率最高 720p；
内置音色可直接用，用自己的音频文件做音色参考需要单独开通。

首尾帧（`last_frame`）

传法	效果
`image` + `last_frame`	首帧和尾帧都钉死，模型在两者之间插值
只传 `last_frame`	钉死尾帧，模型自己生成开头并落到这张图
`last_frame` + 参考素材	钉死尾帧，同时受参考图/参考音引导

last_frame 的写法（URL / base64 data URI / file_id）和 image 完全一样。prompt 可以省略。

last_frame 只在 grok-imagine-video-1.5 上可用

经典模型 grok-imagine-video 会直接拒绝 last_frame，也会拒绝把 image 和参考素材混用。

反过来的限制：grok-imagine-video-1.5 上，image 一旦和 reference_images / reference_audios / last_frame 同时出现，含义就变成「钉死首帧 + 参考引导」，而不是把这张图当风格参考。

时长 / 分辨率 / 比例

参数	生成	编辑	扩展
`duration`	1–15 秒，默认 `8`	忽略（继承源片，上限 8.7 秒）	2–10 秒，默认 `6`，指新增部分
`resolution`	`480p`（默认）/ `720p` / `1080p`	忽略（继承源片，上限 720p）	跟随源片
`aspect_ratio`	7 个值，默认 `16:9`	忽略（继承源片）	跟随源片

aspect_ratio 全部取值：1:1、16:9、9:16、4:3、3:4、3:2、2:3。

1080p 不是所有场景都能用

grok-imagine-video-1.5 的文生视频 / 图生视频支持 1080p；
参考图 / 参考音模式上限 720p；
编辑模式跟随源片且上限 720p（1080p 源会被降到 720p）。

扩展的 duration 是增量

源视频 10 秒 + duration: 6 → 输出 16 秒（10 秒原片 + 6 秒新增）。

很多人以为 duration 是总时长——不是。

轮询节奏

网关查上游的默认值，你的客户端不必照抄：

项	值
网关查询间隔	10 秒
最多查询次数	60 次
失败退避	从 5 秒逐步退到最长 60 秒
任务硬超时	600 秒（自任务创建起算），超时标记失败并退还本次额度

失败或超时都会自动退款，不需要手动申请。

失败错误码

异步任务的 error.code 和同步 HTTP 错误码不是同一套：

`error.code`	含义	怎么办
`invalid_argument`	参数不合法：时长超范围、图片/视频输入有问题、提示词过长、请求模式冲突、被内容审核拦下	改参数或素材后重新提交
`permission_denied`	Key 或团队没有该操作的权限	确认 Key 所属分组和模型权限
`failed_precondition`	该模型/设置不支持这个操作（模型不支持编辑/扩展，或分辨率超了）	换模型、模式或分辨率
`service_unavailable`	上游暂时过载	稍后重试
`internal_error`	上游内部错误	重试；持续出现就带上任务 ID 找客服

注意：鉴权失败、模型不存在、限流这些错误是在创建任务之前同步返回的标准 API 错误，不会出现在任务结果的 error.code 里。

保存生成的视频

视频 url 是临时的，拿到后尽快下载转存。三种正规做法：

做法	怎么做
直接下载（推荐）	拿 `video.url`（兼容层是 `url`）立刻下载——这是 xAI 官方的做法
让上游长期保存	提交时带 `storage_options`
走网关下载代理	兼容层可以用 `GET /v1/videos/{task_id}/content`；这是本网关额外提供的，xAI 官方没有这个端点

storage_options 的字段：

字段	必填	说明
`filename`	是	存储用的文件名
`expires_after`	否	多少秒后自动过期，最大 2592000（30 天）。不传则不过期
`public_url`	否	是否额外生成公网直链

完成后 video.file_output 里会多出 file_id、filename、expires_at（有 TTL 时）、public_url（申请了才有）。存失败不影响出片：video.storage_error 给出原因，video.url 照常可用。

自带存储：提交时传 output.upload_url（你自己提供的、签好名的 HTTP PUT 地址），xAI 生成完会直接把视频 PUT 到你这里，不落在它的临时桶里：

json

"output": { "upload_url": "https://your-bucket.example.com/put/..." }

适合已经有对象存储、不想再多一跳下载的场景。

容易踩的坑

别把轮询写成死循环：服务端 600 秒后判定超时并退还额度，客户端也要有自己的超时上限。
两层 ID 不能互换：request_id 只对 /xai/... 有效，task_id 只对 /v1/... 有效。
prompt 在大部分模式里可以省略，但文生视频必须给。
last_frame 挑模型：经典 grok-imagine-video 会拒绝。
编辑/扩展忽略 duration / aspect_ratio / resolution：传了不报错，但也不生效。
参考音上限 3 条、单条最长 15 秒。
源视频必须是 .mp4：链接要带后缀，编码用 H.265 / H.264 / AV1 等。

视频生成总览

视频是异步的 ​

四种生成模式 ​

图生视频 ​

参考图 / 参考音 ​

首尾帧（last_frame） ​

时长 / 分辨率 / 比例 ​

轮询节奏 ​

失败错误码 ​

保存生成的视频 ​

容易踩的坑 ​

相关页 ​