Grok 视频任务状态与结果参考

了解 xAI 原生视频任务的 ID、状态、响应字段和结果下载规则，避免把创建成功或 HTTP 200 当成生成成功。

适用范围

本页为 xAI 官方查询格式参考，不是本站 Grok 查询接口教程。本站本目录尚无已确认的 Grok 创建和查询配套方式，请先看接入说明。

尤其注意：相同的 /v1/videos/{id} 路径可以属于不同服务。不能把 xAI 的 request_id 放到本站统一视频查询入口，也不能自行增删 ID 前缀。

GET https://api.x.ai/v1/videos/{request_id}，使用 xAI 的 Bearer 凭据；不需要 JSON 请求体，也不使用 multipart 表单。

路径参数 request_id 为必填字符串，来自同一 xAI 服务的生成、编辑或续写创建响应。以下为结构示意：

{"request_id":"REPLACE_WITH_REQUEST_ID"}

本站 API Key 仅用于 https://top.qingyuntop.ai，不能发送到上述官方地址。

官方查询可返回 HTTP 202 表示仍在生成；不要假定每个 202 都有可解析的 JSON。HTTP 200 也可能表示任务失败，需要继续读取正文中的 status。

官方状态	含义与处理
`pending`	仍在生成，稍后查询。
`done`	生成结束，检查 video、审核标记与下载地址。
`expired`	请求已过期，停止轮询；不等同于下载 URL 到期。
`failed`	生成失败，读取 error.code 和 error.message，停止轮询。

建议从每 5 秒查询一次开始，遇到限流或暂时错误时逐步延长间隔，并设置业务等待上限。这是客户端建议，不是本站限流值或生成耗时承诺。超时、断线和停止轮询不会自动取消服务端任务。

字段	类型·必填	取值与说明
`error`	null / object；可选	失败对象，含必填 code 与 message 字符串；任务失败时读取，错误类型见下表。
`model`	string / null；可选	本次使用的模型；失败时可省略。
`progress`	integer / null；可选	0–100。约略完成百分比，0–100；pending 时为 0–99，done 时为 100，失败时省略。
`status`	string；必填	任务状态；HTTP 200 时仍需区分 done 与 failed，详见上表。
`usage`	null / object；可选	厂商用量与费用信息；不等同于本站扣费金额，请以本站账单为准。
`video`	null / object；可选	生成视频对象；失败时不返回，字段详见下表。

REST 响应在顶层读取 status，在 video.url 读取文件链接。SDK 的嵌套对象可能不同，不要把 SDK 的 response.video.url 直接当作 REST JSON 路径。

字段	类型·必填	取值与说明
`duration`	integer；必填	实际生成视频时长，单位秒。
`file_output`	null / object；可选	配置 storage_options 且存储成功时才返回的文件引用。
`respect_moderation`	boolean；必填	内容是否符合审核要求；false 时视频 URL 为空。
`storage_error`	string / null；可选	请求了文件存储但上传失败时返回的错误；不能仅靠生成 done 判断文件存储成功。
`url`	string / null；可选	临时视频 URL，可能缺省或为 null；审核未通过时为空，不保证永久有效。

done 后还应检查视频对象、respect_moderation 和非空 url。内容未通过审核时，不能假定总能取得文件。可选的 progress 只是约略进度，不表示剩余秒数。

xAI 返回的 URL 是临时地址，取得后及时下载到自己的存储；官方此处没有承诺固定保留小时数。下载结果文件不附加本站 API Key，也不要将任何 API Key 拼入 URL。

下载前确认协议和文件类型、检查 HTTP 状态，再保存二进制；错误 JSON 或 HTML 页面不能直接写成 MP4 后当作成功文件。查询超时但已有 request_id 时优先恢复查询，避免重复创建。

上述为任务正文的 error.code；鉴权失败、模型不存在和同步限流可能在创建时直接返回 HTTP 错误，没有任务 ID。对临时错误先退避；重新创建会产生新任务，不保证免除费用。

本站请求排错请提供时间、模型、任务 ID 和脱敏错误联系本站支持。不得提供完整 API Key。不要据此假定本站支持取消、批量查询、SSE 进度或 webhook。