适用范围
本页为 xAI 官方参数参考。本目录尚未提供本站 Grok 视频生成的可调用入口，请先阅读接入说明。不要将下方官方路径直接拼接到本站地址，也不要将本站 API Key 发给 xAI。
文生视频使用文字描述场景与运动；图生视频用一张图片作为起始画面；参考生视频借助图片或声音引导人物、商品和场景。在 1.5 模型中还可以固定结束画面。
官方模型与组合
| 官方型号 | 功能与规格 | 本站使用提示 |
|---|---|---|
grok-imagine-video | 经典视频模型；编辑和续写官方示例使用此型号；不能使用 1.5 的尾帧固定功能。 | 模型列表可见不等于已确认本目录的视频任务协议。 |
grok-imagine-video-1.5 | 文生、图生支持 1080p；参考生最高 720p，最长 15 秒；支持固定首尾帧及预设声音参考。 | 本站公开列表使用 1.5-preview 名称，接入方式请先确认。 |
生成类视频 duration 为 1–15 秒，默认 8 秒。1.5 文生和普通图生支持 1080p；参考生视频最高 720p，不能因为模型相同就把 1080p 用于所有动作。
官方接口与鉴权区别
xAI 原生创建地址为 POST https://api.x.ai/v1/videos/generations，请求体采用 application/json，使用 xAI 的 Bearer 凭据。
本站的地址是 https://top.qingyuntop.ai，使用青云TOP API Key。两者是不同的服务入口；本站支持的具体 Grok 请求格式需以对应接入说明为准。
官方请求参数
以下字段均放在 JSON 顶层。可选字段未注明默认值时，官方未声明固定默认值；并不代表支持所有模型或任意字段组合。
| 字段 | 类型·必填 | 取值与说明 |
|---|---|---|
aspect_ratio | null / string；可选 | 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3。文生默认 16:9；普通图生建议省略并预先调整输入图比例。 |
duration | integer / null；可选 | 1–15；默认 8。生成的视频长度，单位秒；建议传整数。原生兼容别名 seconds 不代表其他协议等价。 |
image | null / object；可选 | 单张起始图片对象，详见图片输入。不要传 images 数组。 |
model | string / null；见说明 | 明确填写具体型号；参见上方官方模型表，不推断本站别名映射。 |
output | null / object；可选 | 定制输出目的地对象；嵌套 upload_url 为必填字符串，是允许 HTTP PUT 的签名上传地址。无需定制存储时省略。 |
prompt | string；见说明 | 文生必填；图生可省略。参考素材和固定帧场景建议也填写非空文字，描述动作、镜头与声音。 |
reference_audios | array；可选 | 最多 3 项。1.5 参考声音，最多 3 项。普通用户使用预设 voice_id；自带音频文件需要厂商专项权限。 |
reference_images | array；可选 | 参考图片对象数组，最多 7 张；用于参考人物、物体或风格。参考生最高 720p。 |
resolution | null / string；可选 | 480p / 720p / 1080p。默认 480p。1080p 限 1.5 文生和普通图生；参考生最高 720p。 |
storage_options | null / object；可选 | 可选的 xAI Files 存储配置，不是本站对象存储设置。具体配置与权限见厂商 Files 文档。 |
user | string / null；可选 | 你的应用中终端用户的标识；不填写 API Key 或敏感个人资料。 |
图片对象和素材
image 及 reference_images[] 使用图片对象。填写 url 或 file_id 之一，不同时填写。
| 字段 | 类型·必填 | 取值与说明 |
|---|---|---|
file_id | string / null；可选 | 已上传完成的 xAI 图片文件 ID；与 url 互斥，不是本站文件 ID。 |
url | string；可选 | 图片 URL 或 Base64 Data URI；未填写 file_id 时必填，与 file_id 互斥。 |
图片支持 JPEG、PNG、WebP。url 可以是服务端可访问的公开图片 URL，或带 MIME 类型的 Base64 Data URI；本地磁盘路径不是 URL。file_id 属于 xAI Files 服务，不可直接使用本站的文件 ID 替代，也不表示本站已提供同样的文件上传流程。
参考图片、声音与首尾帧
reference_images：最多 7 张。图片作为内容或风格参考，不自动锁定首帧。reference_audios：最多 3 项预设声音对象，例如{"voice_id":"eve"}；通过<AUDIO_0>等索引在提示词中引用。不能假定任意上传录音都具有权限。last_frame：1.5 可选的尾帧图片对象，素材形状与image相同；放在 REST JSON 顶层。generate_audio：布尔值，默认 true；设置 false 请求静音视频。它控制视频音轨，不是独立音频生成接口。
1.5 的 image 与参考素材或 last_frame 组合时，表示参考生视频并固定首帧；只有 last_frame 也可以固定尾帧。经典 grok-imagine-video 不接受 last_frame，也不能把 image 与参考素材混合。
为清楚表达镜头和动作，建议每次填写非空 prompt。图片控制画面，文字描述运动和镜头，不要用 negative_prompt、watermark、private、orientation、size 替代这里的字段。
图生视频建议先将输入图片处理为目标宽高比，并省略 aspect_ratio。不要依赖该参数强制裁切或拉伸起始图片；参考生视频可按官方动作说明选用比例。
提交后如何处理
官方原生创建响应返回 request_id，并不直接返回已生成的 MP4。保存 ID 后按任务状态与结果参考理解轮询、失败与临时链接。不要将它当成本站统一视频任务的 id 或 Responses 的 response_id。
常见参数问题
- 文生请求缺少
prompt：填写非空场景与运动描述。 - 参考生视频选择 1080p：改为不超过 720p，并确认所选型号支持该动作。
- 把
images数组当成image：首帧输入为单个对象，参考图片放在reference_images数组。 - 把参数全部放进
metadata：本页列的是 xAI 原生顶层字段，不能直接套用其他兼容协议。 - 传入私有 URL 或本地路径：改为服务端可读取的素材，或使用该服务明确支持的文件输入。